Pineapple Docker plugin

Introduction

Overview

Invoking the plugin

The plugin is invoked by the component when the core component is used by one of the Pineapple clients. To trigger invocation by the core component the plugin needs to be configured.

Configuration

Two steps are needed to configure the plugin:

Define resource: Define resource which enables usage of the the plugin. The resource enables usage by:
- Definition of connectivity information used by the Docker plugin to connect to the remote Docker daemon modeled by the resource.
- Definition of a mapping between the resource ID (e.g. some user defined key referenced from models) and the plugin ID (e.g. the Java package name which implements the plugin: com.alpha.pineapple.plugin.docker.
Define the module model and add content to the model by defining a set of entities which are processed at the targeted resource(s). The entities are processed in sequence when the plugin is invoked with the model. The model is defined using the The Docker plugin schema.

For more info about configuration of plugins:

For info about resources and credentials read the Environment configuration document.
For info about modules and module models read the Modules configuration document.

Supported operations by the plugin

The plugin supports the operations:

test
create-report
deploy-configuration
undeploy-configuration

For more information about the default operations, refer to the Operation and workflow reference.

Execution of the test operation

When invoked with this operation the plugin will traverse the module model and validate that the Docker entities (e.g. images and containers) defined in the model exists at the targeted Docker host:

Container: For each named container element defined in the model, the corresponding container is tested in the Docker host. If no container exist with designated name then the test case for the container fails. The actual runtime state of the container is validated against the expected runtime state defined in the model.

Execution of the create-report operation

When invoked with this operation the plugin will ignore the module model, but create a report that lists all defined images and containers at the targeted Docker host.

Execution of the deploy-configuration operation

When invoked with this operation the plugin will traverse the module model and create all the Docker entities (e.g. images and containers) defined in the model:

Container: A named container is created from every container element defined in the model. If the container exists then the container creation is skipped and marked as successful - because the goal of ensuring existence of the named container is achieved. Since Docker doesn't support update of existing containers, then any existing container isn't updated to match the container configuration defined in the model.
Image: An image is pulled for every image element defined in the model. If the image exists in the Docker host then the image creation is skipped and marked as successful - because the goal of ensuring availability of the image in the Docker host is achieved. The consequence is that the image isn't updated even if a newer version exists in the used repository.
Tagged image: A tagged image is created for every tagged image element defined in the model. If the tagged image exists in the Docker host then the image tagging is skipped and marked as successful - because the goal of ensuring availability of the image in the Docker host is achieved. The consequence is that the image isn't updated even if a newer version of the source image exists in the used repository.
Image from Dockerfile: An image is created for every image-from-Dockerfile element defined in the model. If the image exists in the Docker host then the image creation is skipped and marked as successful - because the goal of ensuring availability of the image in the Docker host is achieved. The consequence is that the image isn't updated even if the Dockerfile is updated or a newer version exists of the source image used by the Dockerfile.

The result of this operation should be that the subsequent execution of the test operation should result in a 100% success (Otherwise you have found a bug in the plugin).

Execution of the undeploy-configuration operation

When invoked with this operation the plugin will traverse the module model and delete all the Docker entities (e.g. images and containers) defined in the model at the target Docker host:

Container: For each named container element defined in the model, the corresponding container is deleted in the Docker host. If no container exist with designated name then the deletion is skipped and marked as successful - because the goal of ensuring that the named container doens't exist is achieved. If the targeted container is running then it stopped prior to deletion. If the targeted container is paused, then it is unpaused (i.e. started) and then stopped prior to deletion.
Image: For each image element defined in the model, the corresponding image is deleted in the Docker host. If no image exist with designated name then the deletion is skipped and marked as successful - because the goal of ensuring that the image doens't exist is achieved. If one or more containers exists, which are based on the image targeted for deletion, then the deletion fails.
Tagged image: Same semantics as supported for image.
Image from Dockerfile: Same semantics as supported for image.

The result of this operation should be that the subsequent execution of the test operation should result in a lot of failures since none of the resources should exist.

Define resource

The purpose of defining a resource for this plugin is twofold:

Define a mapping between the resource ID and the plugin ID. The resource ID is the user defined key which is referenced from module models which are targeting the resource. The plugin ID is the Java package name which implements the plugin: com.alpha.pineapple.plugin.docker.
Define connectivity information used by the Docker plugin to connect to the remote Docker daemon.

To define a new resource, add a resource element to the target environment in the configuration file ${pineapple.home.dir}/conf/resources.xml:

<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns="http://pineapple.dev.java.net/ns/environment_1_0" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  
  <environments>
    <environment id="linux-vagrant" >
      <resources>
        <resource id="docker-node" plugin-id="com.alpha.pineapple.plugin.docker" />
          <property value="192.168.34.10" key="host"/>
          <property value="8082" key="port"/>                   
          <property value="1000" key="timeout"/>                                                                
        </resource>
      </resources>
    </environment>                                                              
  </environments>
</configuration>

For all the details about configuration of environments and resources, please visit the Environment Configuration Reference.

The semantics of the resource element is:

The `id` attribute

Identifies the resource uniquely in the current environment. This ID is referenced from models which intends to use the plugin.

The `plugin-id` element

The plugin ID defines the name of the Java package which implements the plugin. The plugin ID for this plugin is: com.alpha.pineapple.plugin.docker.

The `property` attributes(s)

Mandatory properties used by the plugin:

host - Host name of the remote Docker daemon whose REST services are invoked to execute commands.
port - Port number on the remote Docker daemon.
timeout - Connection timeout in milli seconds.

A module defines the input used by Pineapple to execute operations. A module is defined by a directory layout. Part of a module is the model(s) which defines what happens when the module is invoked. A model is put together by one or more sub models from different plugins. Each plugin defines its own schema for its particular model

The docker plugin schema

This plugin defines a schema named The Docker plugin schema which defines the http://pineapple.dev.java.net/ns/plugin/docker_1_0 namespace. For more information about where the schema can be found, refer to the Schema locations for plugins page.

Name and location of the the module model file

The list of entities which should be processed when the plugin is invoked are defined in the module model files which are located at ${module-dir}/models/${environment}.xml where:

${module-dir} is the module root directory which identifies the module with a unique name and version.
${environment}.xml is a module model file for a target environment, with ${environment} substituted with the environment name, e.g. linux-vagrant.xml for an environment named linux-vagrant.

If the model file doesn't exist for an environment where the plugin should be used, then create the model file and name it after the target environment, e.g. linux-vagrant.xml for an environment named linux-vagrant.

The module model configuration schema

Module model files are defined using the module model configuration schema which defines the http://pineapple.dev.java.net/ns/module_model_1_0 namespace. Since module model files contain elements from multiple namespaces all the elements and attributes should be qualified. The header and root element should be defined as (look in the Modules configuration document for more details):

This example shows definition of the minimal model file for linux-vagrant:

<?xml version="1.0" encoding="UTF-8"?>
<mmd:models xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:mmd="http://pineapple.dev.java.net/ns/module_model_1_0" />

Adding the plugin schema to the model

The next step is to include the The Docker plugin schema to get access to the entities defined by the schema:

<?xml version="1.0" encoding="UTF-8"?>
<mmd:models xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:mmd="http://pineapple.dev.java.net/ns/module_model_1_0"                 
  xmlns:dkp="http://pineapple.dev.java.net/ns/plugin/docker_1_0" />

Now we have a minimal module model file with three namespaces:

xs: The basic XMLSchema schema which is only used in the root element of the document.
mmd: The module model schema which is used to define the skeleton of a model file.
dkp: The Docker plugin schema which is used to define docker resources.

Defining the model which targets resources

Add a new model stanza with a target-resource attribute. The value of the target-resource should match the id of the resource which was defined previously in the section Define resource, e.g. docker-node:

<?xml version="1.0" encoding="UTF-8"?>
<mmd:models xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:mmd="http://pineapple.dev.java.net/ns/module_model_1_0"                 
  xmlns:dkp="http://pineapple.dev.java.net/ns/plugin/docker_1_0" />
  
  <mmd:model target-resource="docker-node">             
    <mmd:content />                             
  </mmd:model>
</mmd:models>

Add content to the model which uses the plugin through the docker-node reference:

<?xml version="1.0" encoding="UTF-8"?>
<mmd:models xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:mmd="http://pineapple.dev.java.net/ns/module_model_1_0"                 
  xmlns:dkp="http://pineapple.dev.java.net/ns/plugin/docker_1_0" />
  
  <mmd:model target-resource="docker-node">             
    <mmd:content>
      <dkp:docker>
      </dkp:docker>                     
    </mmd:content>                                                                                                                                                                              
  </mmd:model>
</mmd:models>

Define Docker entities the module model

Define a sequence of entities which should be processed when Pineapple is invoked with the model:

<?xml version="1.0" encoding="UTF-8"?>
<mmd:models xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:mmd="http://pineapple.dev.java.net/ns/module_model_1_0"                 
  xmlns:dkp="http://pineapple.dev.java.net/ns/plugin/docker_1_0" />
  
  <mmd:model target-resource="docker-node">             
    <mmd:content>
      <dkp:docker>
        <dkp:image repository="centos" tag="latest" />
        <dkp:taggedImage>
          <dkp:sourceImage repository="centos" tag="latest" />
          <dkp:targetImage repository="pineapple/centos" tag="latest" />
        <dkp:taggedImage>
      </dkp:docker>                     
    </mmd:content>
  </mmd:model>
</mmd:models>

Image

Defines a Docker image and supports its creation and deletion. An image is defined through a Docker repository and image tag:

  <dkp:image repository="centos" tag="latest" />

Operation semantics:

deploy-configuration: Create Docker image. The image is created by pulling it from the used registry. If an image already exists in the Docker host then the image creation is skipped and marked as successful, the consequence is that the image isn't updated even if a newer version exists at the used repository.
undeploy-configuration: Delete Docker image. If no image exist with designated name then the deletion is skipped and marked as successful. If one or more containers exists, which are based on the image targeted for deletion, then the deletion fails.
create-report: Creates report which lists the defined Docker images and containers.

The semantics of the attributes are:

`repository` attribute

Mandatory attribute. Defines the repository where the image is create from.

Example of official repository name is ubuntu which holds Ubuntu images. Example of user repository (which has the name format user/repo) is mrpono/pineapple.

`tag` attribute

Optional attribute. Defines the image tag. Default value is latest.

Example of image tags are: latest and 12.10.

Tagged image

Defines a tagged Docker image and supports its creation and deletion:

  <dkp:taggedImage>
    <dkp:sourceImage repository="centos" tag="latest" />
    <dkp:targetImage repository="pineapple/centos" tag="latest" />
  <dkp:taggedImage>

Operation semantics:

deploy-configuration: Create tagged Docker image from an existing image. The source image defines the existing image from which the tagged image is created. The source image must exist otherwise the creation of the tagged image fails. The target image defines the created image. If the source image already exists in the Docker host then the image tagging is skipped and marked as successful. The consequence is that the image isn't updated even if a newer version of the source image exists in the used repository.
undeploy-configuration: Delete Docker image. The target image defines the image which is deleted if it exists. The source image is ignored during deletion. If the target image doesn't exists then the deletion is skipped and marked as successful. If one or more containers exists, which are based on the target image, then the deletion fails.
create-report: Creates report which lists the defined Docker images and containers.

The semantics of the elements and attributes are:

`source-image` element

Mandatory attribute. Defines the source image where the tagged image is created from.

`source-image.repository` attribute

Mandatory attribute. Defines the repository where the tagged image is create from.

Example of official repository name is ubuntu which holds Ubuntu images. Example of user repository (which has the name format user/repo) is mrpono/pineapple.

`source-image.tag` attribute

Optional attribute. Defines the tag of the source image. Default value is latest.

Example of image tags are: latest and 12.10.

`target-image` element

Mandatory attribute. Defines the tagged target image.

`target-image.repository` attribute

Mandatory attribute. Defines the repository for the tagged image.

Example of official repository name is ubuntu which holds Ubuntu images. Example of user repository (which has the name format user/repo) is mrpono/pineapple.

`target-image.tag` attribute

Optional attribute. Defines the tag of the tagged image.

Example of image tags are: latest and 12.10.

Image from Dockerfile

Defines a tagged Docker image and supports its creation and deletion from a Dockerfile:

   <dkp:image-from-dockerfile source-directory="modulepath:dockersrc" pull-image="false" >
     <dkp:target-image repository="pineapple/httpd" tag="1.0" />
   </dkp:image-from-dockerfile>

Operation semantics:

deploy-configuration: Create a TAR archive from a source directory which contains a Dockerfile. Create tagged Docker image from the TAR archive (using the Dockerfile and other resources within). The target image defines the created image. If the image already exists in the Docker host then the image creation is skipped and marked as successful The consequence is that the image isn't updated even if the Dockerfile is updated or a newer version exists of the source image used by the Dockerfile.
undeploy-configuration: Delete the tagged Docker image. The target image defines the image which is deleted if it exists. If the target image doesn't exists then the deletion is skipped and marked as successful. If one or more containers exists, which are based on the image targeted for deletion, then the deletion fails.
create-report: Creates report which lists the defined Docker images and containers.

The semantics of the elements and attributes are:

`source-directory` element

Mandatory attribute. Defines source directory which must contain a Dockerfile in the root. The source directory can contain other file resources referenced and used by the Dockerfile. Other file resources will be packed into a TAR archive along with the Dockerfile and uploaded to the Docker daemon to be used at input for creation of the image.

The element supports the usage of the modulepath: prefix which is resolved to the absolute directory where the model is defined.

`target-image` element

Mandatory attribute. Defines the tagged target image.

`target-image.repository` attribute

Mandatory attribute. Defines the repository for the tagged image.

Example of official repository name is ubuntu which holds Ubuntu images. Example of user repository (which has the name format user/repo) is mrpono/pineapple.

`target-image.tag` attribute

Optional attribute which is currently ignored. Defines the tag of the tagged image. Tagged image will be created with latest tag.

`pull-image` element

Optional attribute. Defines whether a new source image used in the DOckerfile should be pulled from docker hub even if a older local copy exist. Default value is false.

Container

Defines a named Docker container and supports its creation and deletion:

  <dkp:container name="alpha01" >
    <dkp:image repository="pineapple/httpd" tag="1.0" />   
    <dkp:configuration>
      <dkp:exposed-ports>
        <dkp:port value="8080" type="tcp" />
      </dkp:exposed-ports>
    </dkp:configuration>
  </dkp:container>

Operation semantics:

test: Tests the Docker container at the host with the definition in the model. The name defines the name of the container which is tested. If no container with designated name exists then the test case is skipped as failed. The actual runtime state of the container is validated against the expected runtime state defined in the model.
deploy-configuration: Create a named container. The name attribute defines the name of the created container. The name must be unique within the Docker daemon. The name is used to rename the Docker container as part of its creation. If a container with designated name already exists then the creation is skipped as successful. and the existing container isn't updated to reflect the container configuration in the model. The state attribute defines the target state of container as part of its creation, i.e. whether the container should be created, started, stopped, or paused. The image element defines the image from which the container is created.
undeploy-configuration: Delete the Docker container. The name defines the name of the container which is deleted. If no container exist with designated name then the deletion is skipped and marked as successful. If the container is running then it is stopped prior to deletion. If the container is paused then it is unpaused and stopped prior to deletion.
create-report: Creates report which lists the defined Docker images and containers.

The semantics of the elements and attributes are:

`name` attribute

Mandatory attribute. Defines the name of container. The name of the container must be unique within the Docker daemon.

By default containers are primarily identified by an ID in Docker, but since Pineapple is stateless, there is no way for Pineapple to maintain the container ID across invocation of a model. Usage of a container name solves that problem.

`state` attribute

Optional attribute. Defines which state the container should enter as part of its creation, i.e then the model is invoked with the deploy-configuration operation. The default value is running, e.g. the container created and started.

The supported states are:

running - container is started and running.
paused - container is paused from running.
stopped - container is stopped.

When the model is invoked with a undeploy-configuration operation then a container handled a bit differently depending on its state:

If the container is running then container is stopped and then deleted.
If the container is stopped then container is deleted.
If the container is paused then container is un-paused (i.e. started), stopped and then deleted.

`image` element

Mandatory element. Defines the image that the container is created from.

`image.repository` attribute

Mandatory attribute. Defines the repository for the image.

Example of official repository name is ubuntu which holds Ubuntu images. Example of user repository (which has the name format user/repo) is mrpono/pineapple.

`image.tag` attribute

Optional attribute. Defines the tag of the image. Default value is latest.

`configuration` element

Optional element. Supports detailed (embedded) configuration of the container.

`configuration.ref` attribute

Optional attribute. Defines reference to reusable container configuration in model. The purpose of supporting referenced container configurations it to enable reuse of container properties which is defined for multiple container within a model, and thus reducing the amount of XML:

  <dkp:container-configuration id="my-container-config">
    <dkp:exposed-ports>
      <dkp:port value="8080" type="tcp" />
    </dkp:exposed-ports>
  </dkp:container-configuration>            

  <dkp:container name="alpha02" >
    <dkp:image repository="pineapple/httpd" tag="1.0" />   
      <dkp:configuration ref="my-container-config" />
  </dkp:container>

A referenced container configuration is defined using the container-configuration element.

If a reference isn't valid, i.e. the referenced container configuration doesn't exist within the model, then the reference is just ignored.

The container configuration within the container takes precedence over a refereced container configuration. Example #1: If property A is defined with value V within the container and property A is also defined in a referenced configuration with value R, then the value of A is resolved to V when the container is created.

Example #2: If property A isn't defined within the container and property A is defined in a referenced configuration with value R, then the value of A is resolved to R when the container is created.

Example #3: If property A isn't defined within the container and the reference to the referenced configuration is invalid, then the value of A is resolved to the default value D when the container is created.

Docker specfic attributes

Optional attributes. The container configuration supports these Docker properties defined as attributes on the configuration element with simple types:

attach-stderr. Type is boolean, default value during container creation is true.
attach-stdin. Type is boolean, default value during container creation is true.
attach-stdout. Type is boolean. default value during container creation is true.
domainname. Type is string, , default value during container creation is the empty string.
hostname. Type is string, default value during container creation is the empty string.
mac-address. Type is string.
network-disabled. Type is boolean, , default value during container creation is false.
open-stdin. Type is boolean, default value during container creation is true.
stdin-once. Type is boolean, default value during container creation is false.
tty. Type is boolean, default value during container creation is true.
user. Type is string, default value during container creation is the empty string.
working-dir. Type is string, , default value during container creation is the empty string.

The container configuration supports these Docker container properties as object based structures:

cmd. List of commands.
env. List of environment variables.
entrypoint. List of inital commands.
exposed-ports. List of exposed ports.
host-config. Container host configuration as an object.
labels. List of container labels.
on-build List of On build commands.
volumes. List of mounted volumes.

These properties are described in detail below.

`configuration.cmd` element

Optional element. Defines a command to run specified as a string or an array of strings. The command is specificed as a string. Each space in the string is interpreted as a separator and will result in interpretation of the string as an array.

  <dkp:container>
    <dkp:cmd>date</dkp:cmd>
  </dkp:container>

Multiple commands (e.g. parameters) are defined within the same cmd element with a space in between:

  <dkp:configuration>
    <dkp:cmd>/bin/sh date</dkp:cmd>  
  </dkp:configuration>

`configuration.entrypoint` element

Optional element. Defines the default command to execute at runtime, specified as a string or an array of strings. Each space in the string is interpreted as a separator and will result in interpretation of the string as an array.

  <dkp:container>
    <dkp:entrypoint>/bin/bash</dkp:entrypoint>
  </dkp:container>

Multiple commands (e.g. parameters) are defined within the same entrypoint element with a space in between:

  <dkp:configuration>
    <dkp:entrypoint>/bin/sh date</dkp:entrypoint>  
  </dkp:configuration>

`configuration.env` element

Optional element. Defines a list of environment variables defined within the container. Each variable is defined with a variable element. A variable element defines a mandatory name attribute for the variable name and a mandatory value attribute for the variable value.

  <dkp:container>
    <dkp:env>
      <dkp:variable name="PATH" value="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" />         
    </dkp:env>
  </dkp:container>

`configuration.exposed-ports` element

Optional element. Defines list of TCP and UDP ports exposed by the container. Each exposed port is defined with a port element. A port element defines a mandatory value attribute. Legal values are integers between 1 to 65535. A port element defines a mandatory type attribute. Legal values are tcp or udp.

If two ports with identical port numbers are added to the model, then only the first port is registered.

  <dkp:container>
    <dkp:exposed-ports>
      <dkp:port value="8080" type="tcp" />
    </dkp:exposed-ports>
  </dkp:container>

`configuration.labels` element

Optional element. Defines list of labels to register with the container. Each label is defined with a label element. A label element defines a mandatory key attribute for the label key and a mandatory value attribute for the label value.

If two labels with identical keys are added to the model, then only the first label is registered.

  <dkp:container>
    <dkp:labels>
      <dkp:label key="com.example.vendor" value="Acme" />
      <dkp:label key="com.example.license" value="GPL" />
      <dkp:label key="com.example.version" value="1.0" />
    </dkp:labels>
  </dkp:container>

`configuration.on-build` element

Optional element.

Defines the command to be executed at a later time, when the image is used as the base for another build (see the Docker ONBUILD command reference). The command is specified as a string or an array of strings. Each space in the string is interpreted as a separator and will result in interpretation of the string as an array.

  <dkp:container>
    <dkp:on-build>ADD . /app/src</dkp:on-build>
  </dkp:container>

Multiple commands (e.g. parameters) are defined within the same on-build element with a space in between.

`configuration.volumes` element

Optional element. Defines list of volumes mounted by the container. Each volume is defined with a volume element. A volume element defines a mandatory mountpoint attribute. Legal values are string based path expressions.

If two volumes with identical mountpoints are added to the model, then only the first volume is registered.

  <dkp:container>
    <dkp:volumes>
      <dkp:volume mountpoint="/tmp" />
      <dkp:volume mountpoint="/opt" />
    </dkp:volumes>
  </dkp:container>

`configuration.host-config` element

Optional element. Defines the host specific container configuration. The host configuration is defined with a host-config element. The host configuration contains properties and objects.

  <dkp:container>
    <dkp:host-config>      
      <dkp:restart-policy maximum-retry-count="5" name="on-failure" />
      <dkp:port-bindings>
        <dkp:bind container-port="8080" container-type="tcp" host-port="8080" />
      <dkp:port-bindings>
    </dkp:host-config>
  </dkp:container>

The host config element supports these Docker properties defined as attributes:

binds. List of container volume bindings.
cpu-shares. Type is long, default value during container creation is 0.
cpu-period. Type is long, default value during container creation is 0.
cpuset-cpus. Type is string, default value during container creation is the empty string.
cpuset-mems Type is string, default value during container creation is the empty string.
dns. List of DNS servers for the container to use.
dns-search List of DNS search domains.
extra-hosts. List of hostnames/IP mappings to add to the container’s /etc/hosts file.
group-add. List of additional groups that the container process will run as.
links. List of container network links that the container will create to other containers.
memory. Type is long, default value during container creation is 0.
memory-swap Type is long, , default value during container creation is 0.
security-opt. List of string values to customize labels for MLS systems, such as SELinux.
volumes-from. List of volumes to take from other container.

The host config element supports these Docker container properties as object based structures:

port-bindings. Map of port bindings.
restart-policy. Container restart policy as an object.

These properties are described in detail below.

`configuration.host-config.binds` element

TODO: Complete documentation.

Optional element. Defines the XXXX, specified as a string or an array of strings. Each space in the string is interpreted as a separator and will result in interpretation of the string as an array.

 TODO: add example.

Multiple commands (e.g. XXX) are defined within the same binds element with a space in between.

`configuration.host-config.dns` element

Optional element. Defines the list of DNS servers for the container to use, specified as a string or an array of strings. Each space in the string is interpreted as a separator and will result in interpretation of the string as an array.

  <dkp:host-config>      
    <dkp:dns>8.8.8.8 and 8.8.4.4</dkp:dns>              
  </dkp:host-config>

Multiple servers are defined within the same dns element with a space in between.

`configuration.host-config.dns-search` element

TODO: Complete documentation.

Optional element. Defines the list of DNS search domains for the container to use, specified as a string or an array of strings. Each space in the string is interpreted as a separator and will result in interpretation of the string as an array.

 TODO: add example.

Multiple domains are defined within the same dns-search element with a space in between.

`configuration.host-config.extra-hosts` element

TODO: Complete documentation.

Optional element. Defines the list of host names/IP mappings to add to the container’s /etc/hosts file, specified as a string or an array of strings. Each space in the string is interpreted as a separator and will result in interpretation of the string as an array.

 TODO: add example.

Multiple host names are defined within the same extra-hosts element with a space in between.

`configuration.host-config.group-add` element

TODO: Complete documentation.

Optional element. Defines the list of additional groups that the container process will run as, specified as a string or an array of strings. Each space in the string is interpreted as a separator and will result in interpretation of the string as an array.

 TODO: add example.

Multiple host names are defined within the same group-add element with a space in between.

`configuration.host-config.links` element

Optional element. Defines the list of container network links that the container will create to other containers, specified as a string or an array of strings. Each space in the string is interpreted as a separator and will result in interpretation of the string as an array.

A link is defined by a container-name:dns:

The container-name defines the name of the target container that the defining container should be able to initiate and communicate with.
the dns part defines an alias that is added to the defining containers /etc/hosts file file and can then be resolved internally within the defining container.

 <dkp:host-config>      
  <dkp:links>backend01:httpd1 backend02:httpd2 backend03:httpd3 backend04:httpd4</dkp:links>              
</dkp:host-config>

Multiple links are defined within the same links element with a space in between.

`configuration.host-config.security-opt` element

TODO: Complete documentation. security-opt defines list of string values to customize labels for MLS systems, such as SELinux.

`configuration.host-config.volumes-from` element

TODO: Complete documentation. volumes-from defines list of volumes to take from other container.

`configuration.host-config.port-bindings` element

Optional element. Defines the list of port bindings for the container. Binds (and exposes) container ports at the host. A binding is defined with a bind element.

A bind element defines a mandatory container-port attribute which defines the container port which should be bound and exposed to the host. Legal values are 1 to 65535. A bind element defines a mandatory host-port attribute which defines to which host port the container port should be bound Legal values are 1 to 65535. A bind element defines a mandatory type attribute which defines type of the bound container port. Legal values are tcp or udp.

If two bindings with identical container ports are added to the model, then only the first binding is registered.

  <dkp:container>
    <dkp:host-config>      
      <dkp:port-bindings>
        <dkp:bind container-port="8080" host-port="8080" type="tcp" />
      <dkp:port-bindings>
    </dkp:host-config>
  </dkp:container>

`configuration.host-config.restart-policy` element

Optional element. Defines the restart policy for the container. The policy is defined with a restart-policy element. The policy defines a mandatory maximum-retry-count attribute which defines the number of times to retry before giving up. Legal values are 0 to 1000000. The policy defines a mandatory name attribute which defines the used policy. Legal values are always or on-failure.

  <dkp:container>
    <dkp:host-config>      
      <dkp:restart-policy maximum-retry-count="5" name="on-failure" />
    </dkp:host-config>
  </dkp:container>

Referenced container configuration

Defines a named Docker container configuration which can be referenced from containers within the model during creation:

  <dkp:container-configuration id="my-container-config">
    <dkp:exposed-ports>
      <dkp:port value="8080" type="tcp" />
    </dkp:exposed-ports>
  </dkp:container-configuration>            

  <dkp:container name="alpha02" >
    <dkp:image repository="pineapple/httpd" tag="1.0" />   
      <dkp:configuration ref="my-container-config" />
  </dkp:container>

Operation semantics:

test: NOP.
create-report: NOP.
deploy-configuration: If referenced by a container then the values in the container configuration are used as input to resolve the values for the created container.
undeploy-configuration: NOP.

The semantics of the elements and attributes are:

`id` attribute

Mandatory attribute. Defines unique ID for the container configuration within the model.

Docker specfic attributes and properties

The container configuration supports all standard Docker container attributes and properties as described above.