Docker plugin

The 'docker' plugin provides instance operations implemented as starting and stopping Docker [^1] containers and service-discovery control operations (connect or disconnect instances from the application's bridge network).

Quick jump to Configuration.

[^1]: All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

Plugin-specific component attributes

This plugin supports the following plugin-specific attributes of components in the Skopos model:

  • command - specify the container command (string or list of strings)
  • raw - attributes to override settings in the low-level Docker API object passed to Docker to create a container (Config + HostConfig + NetworkingConfig). Some field may not be overridden if they are already defined in the Skopos model (e.g., AttachStdin). Exception is made for HostConfig.RestartPolicy, which can be overridden.

Note: the raw settings may cause the docker plugin to malfunction due to unexpected behavior caused by specific settings

Example model file:

components:
  web:
    image: opsani/sample-back

    provides:
      ports:
        - "8080/tcp"
    visual: { x: 350, y: 200 }

    plugin:
      docker:
        command: ['ls', '-l']
        raw:
          WorkingDir: '/root'

Configuration

Configuration for this plugin is optional and may be omitted.

Example target environment file:

core_plugin: docker

plugin_config:
  docker:
    ipv6: true
    local_images_only: true
    insecure_registries: true
    dflt_vol_prefix: /mnt/vols/
    volumes:
      db:
        from: '/usr/var/mysql'

The following configuration setting may be provided when desired:

ipv6

ipv6 - a boolean; set this to true to enable IPv6 when creating the application network with the network_create operation. NOTE if network_create is not used or if the application network already exists, this setting has no effect.

local_images_only

local_images_only - a boolean, default: false; If set to true, the plugin will not try to pull images before creating new instances (will cause failure if there is no local copy) and will also not monitor remote registries for newer versions of any of the images that are running. Setting this to true is suitable for local development mode, where detecting changes between your local and remote registries or overwriting local images is undesirable.

insecure_registries

insecure_registries - a boolean, default: false; If set to true, the plugin will fall back to insecure calls to image registry if it cannot establish a secure connection when checking metadata of images. Has no impact if local_images_only is true. Note that this setting does not allow images to be pulled from insecure registries (this is a setting of the docker engine, see https://docs.docker.com/registry/insecure/)

dflt_vol_prefix

dflt_vol_prefix - a string to prefix the default volume name/path if an explicit entry for a volume is note defined in the volumes map.

See Default Volumes for further details and examples

volumes

volumes - a optional map defining the location of data for volumes used by the application. This map needs to be present only to use specific names that differ from the default. See Default Volumes.

The format of the volumes map is:

volumes:
  <logical-name>:
    from: "<path-or-name>"
  ...

Each <logical-name> corresponds to a volume name as used in the application model. <path-or-name> is either an absolute file/directory path accessible to the Docker engine or the name of a Docker volume object (visible with the Docker CLI command 'docker volume ls').

If a volume name (or host directory path) is defined here but does not exist on the host Docker will create it, and copy any content from the container. This can be used to initialize volumes with their default content.

Default Volumes

If a logical volume is used in the application model and the volume is not named in the volumes map here, the docker plugin generates a default name.

The default name consists of a prefix, project name, underscore separator and logical volume name.

In the simplest case, the volume name is <project>_<logical-name>, producing a project-scoped volume name in a manner similar to how container names and network names are produced. For example, if the model refers to a volume www and the project name is myblog, the default volume name will be myblog_www.

If the dflt_vol_prefix configuration setting is defined, then it is used to prefix the default name, producing <dflt_vol_prefix><project>_<logical-name>. This allows further modifying the volume names, and, more importantly, using host-mapped directories. For example:

  • if dflt_vol_prefix is set to /mnt/, the resulting default mount will be /mnt/myblog/www
  • if dflt_vol_prefix is set to joe_, the resulting default mount will be joe_myblog_www

Note that the default prefix is used without any separator; make sure that if you need a separator (such as / or _), it is explicitly included in the value, as shown in the above examples.