dockermap.map.config package

Submodules

dockermap.map.config.client module

dockermap.map.config.container module

class dockermap.map.config.container.ContainerConfiguration(values=None, **kwargs)

Bases: dockermap.map.config.ConfigurationObject

Class to maintain resources that are associated with a container.

abstract

Marks this configuration as abstract, so that it can not be used for container actions directly, but for basing other configurations on.

attaches

Names of volumes that are assigned to this container, and that can be shared with other containers. For hosts that do not support named volumes, an empty container will be created that shares a single volume. This can be in the syntax alias: mount path (dict, tuple, list) or just alias if the mount path is set in the volumes property of the container map.

binds

The host volume shares for a container. These will be added to the shared volumes, and mapped to a host volume.

clients

Set this to client names that you would like to limit container instantiation to. This overrides clients specified globally for a map.

create_options

Additional keyword args for docker.client.Client.create_container().

exec_commands

Commands to run as soon as the container is started. Set in the format ExecCommand(cmd, user, policy), where the user is set to the same as this configuration’s user by default (or root, if not available). The policy decides when to start the command.

exposes

Ports and (virtual) interface name that a network service is exposed on.

The following formats are considered as valid input and will be converted to a list of PortBinding tuples:

  • Dictionary with container exposed ports as keys, and either host port and interface, or only the host port as values.
  • A list or tuple with elements
    • tuple or list: container exposed port, host port - for mapping all host addresses;
    • tuple or list: container exposed port, (host port, host interface) as nested tuple or list;
    • tuple or list: container exposed port, host port, host interface;
    • container exposed port only - will not be published, but is available to linked containers.

If the host port, but no interface is set, the port will be published to all interfaces (as this is the Docker default). Otherwise the relevant IP address to expose the service on will be looked up at run-time.

extends

Bases this configuration on one or more configurations.

healthcheck

Healthcheck instruction for testing the container state. Should be passed as a tuple or dictionary with the elements test, interval, timeout, retries, and start_period.

host_config

Additional keyword args for docker.client.Client.start() or HostConfig options to pass to docker.client.Client.create().

image

The base image of the container. If set to None, the containers will be instantiated with an image that has the same name.

instances

Separate instances of a container, if any. By default there is one instance of each container. If set, containers will be created for each instance in the format map_name.container_name.instance.

Linked containers. Links are set in the format ContainerLink(name, alias), where the name is the linked container’s name, and the alias name the alias to use for this container instance.

network_mode

Networking to apply to this container. If not bridge or host (as described in the docker-py docs), tries to locate a container configuration on this map. Prefixed with / assumes the full container name. Setting it to disabled deactivates networking for the container.

networks

Names of configured networks for this container to join.

permissions

Permission flags to be set for attached volumes. Can be in any notation accepted by chmod.

persistent

Set this to True for containers that are only started to share a volume, but exist immediately. Such containers are restarted and not removed during cleanup.

shares

Shared volumes for a container.

start_delay

Delay in seconds to insert after a container start.

stop_signal

By default Docker sends SIGTERM to containers on stop or restart. This may not always be the best signal to get the main process to shut down properly. This property can for example be set to SIGINT, where more appropriate.

stop_timeout

Individual timeout (in seconds) for stopping a container, i.e. the time between sending a SIGTERM and a SIGKILL to the container.

user

User name / group or id to launch the container with and to which the owner is set in attached containers. Can be set as a string (user_name or user_name:group), ids (e.g. user_id:group_id), tuple ((user_name, group_name)), or int (user_id).

uses

Volumes used from other containers. This can be a combination of attached volume aliases, and container names if all volumes are to be used of that container. For hosts that support named volumes this can be specified as volume alias: mount path (as a dict, list, or tuple); otherwise only volume names can be provided here and the mount path of the origin is re-used (attached or container volume).

dockermap.map.config.host_volume module

class dockermap.map.config.host_volume.HostVolumeConfiguration(*args, **kwargs)

Bases: dockermap.map.DictMap

Class for storing volumes, as shared from the host with Docker containers.

Parameters:root (unicode | str) – Optional root directory for host volumes.
get_path(item, instance=None)
root

Root directory for host volumes; if set, relative paths of host-shared directories will be prefixed with this.

Returns:Root directory for host volumes.
Return type:unicode | str
dockermap.map.config.host_volume.get_host_path(root, path, instance=None)

Generates the host path for a container volume. If the given path is a dictionary, uses the entry of the instance name.

Parameters:
  • root (unicode | str | AbstractLazyObject) – Root path to prepend, if path does not already describe an absolute path.
  • path (unicode | str | dict | AbstractLazyObject) – Path string or dictionary of per-instance paths.
  • instance (unicode | str) – Optional instance name.
Returns:

Path on the host that is mapped to the container volume.

Return type:

unicode | str

dockermap.map.config.main module

class dockermap.map.config.main.ContainerMap(name, initial=None, check_integrity=True, check_duplicates=True, **kwargs)

Bases: dockermap.map.config.ConfigurationObject

Class for merging container configurations, host shared volumes, and volume alias names.

Parameters:
  • name (unicode | str) – Name for this container map.
  • initial (dict) – Initial container configurations, host shares, and volumes.
  • check_integrity (bool) – If initial values are given, the container integrity is checked by default at the end of this constructor. Setting this to False deactivates it.
  • check_duplicates (bool) – Check for duplicate attached volumes during integrity check.
  • kwargs – Kwargs with initial container configurations, host shares, and volumes.
as_dict()
check_integrity(check_duplicates=True)

Checks the integrity of the container map. This means, that * every shared container (instance name) and attached volume should only exist once (can be deactivated); * every container declared as used needs to have at least a shared volume or a host bind; * every host bind declared under binds needs to be shared from the host; * every volume alias used in attached and binds needs to be associated with a path in volumes; * every container referred to in links needs to be defined; * every container named in extended is available.

Parameters:check_duplicates (bool) – Check for duplicate attached volumes.
clean()
clients

Alias names of clients associated with this container map.

containers

Container configurations of the map.

Returns:Container configurations.
Return type:dict[unicode | str, dockermap.map.config.container.ContainerConfiguration]
default_domain

Value to use as domain name for new containers, unless the client specifies otherwise.

default_tag

Default tag to use for images where it is not specified. Default is latest.

dependency_items()

Generates all containers’ dependencies, i.e. an iterator on tuples in the format (container_name, used_containers), whereas the used containers are a set, and can be empty.

Returns:Container dependencies.
Return type:collections.Iterable
get(item)

Returns a container configuration from the map; if it does not yet exist, an initial config is created and returned (to avoid this, use get_existing() instead). item can be any valid Docker container name.

Parameters:item (unicode | str) – Container name.
Returns:A container configuration.
Return type:ContainerConfiguration
get_existing(item)

Same as get(), except for that non-existing container configurations will not be created; None is returned instead in this case.

Parameters:item (unicode | str) – Container name.
Returns:A container configuration
Return type:ContainerConfiguration
get_existing_network(name)

Same as get_network(), except for that non-existing network configurations will not be created; None is returned instead in this case.

Parameters:name (unicode | str) – Network name.
Returns:A network configuration.
Return type:dockermap.map.config.network.NetworkConfiguration
get_existing_volume(name)

Same as get_volume(), except for that non-existing volume configurations will not be created; None is returned instead in this case.

Parameters:name (unicode | str) – Volume alias.
Returns:A volume configuration.
Return type:dockermap.map.config.volume.VolumeConfiguration
get_extended(config)

Generates a configuration that includes all inherited values.

Parameters:config (ContainerConfiguration) – Container configuration.
Returns:A merged (shallow) copy of all inherited configurations merged with the container configuration.
Return type:ContainerConfiguration
get_extended_map()

Creates a copy of this map which includes all non-abstract configurations in their extended form.

Returns:Copy of this map.
Return type:ContainerMap
get_image(image)

Generates a tuple of the full image name and tag, that should be used when creating a new container.

This implementation applies the following rules:

  • If the image name starts with /, the following image name is returned.
  • If / is found anywhere else in the image name, it is assumed to be a repository-prefixed image and returned as it is.
  • Otherwise, if the given container map has a repository prefix set, this is prepended to the image name.
  • In any other case, the image name is not modified.

Where there is a tag included in the image name, it is not modified. If it is not, the default tag from the container map, or latest is used.

Parameters:image (unicode | str) – Image name.
Returns:Image name, where applicable prefixed with a repository, and tag.
Return type:(unicode | str, unicode | str)
get_network(name)

Returns a network configuration from the map; if it does not yet exist, an initial config is created and returned (to avoid this, use get_existing_network() instead). name can be any valid network name.

Parameters:name (unicode | str) – Network name.
Returns:A network configuration.
Return type:dockermap.map.config.network.NetworkConfiguration
get_persistent_items()

Returns attached container items and container configurations that are marked as persistent. Each returned item is in the format (config name, instance/attached name), where the instance name can also be None.

Returns:Lists of attached items.
Return type:(list[(unicode | str, unicode | str)], list[unicode | str, unicode | str | NoneType])
get_volume(name)

Returns a volume configuration from the map; if it does not yet exist, an initial config is created and returned (to avoid this, use get_existing_volume() instead). name can be any valid volume name.

Parameters:name (unicode | str) – Volume alias.
Returns:A volume configuration.
Return type:dockermap.map.config.volume.VolumeConfiguration
groups

Groups of configured containers.

host

Volume alias assignments of the map.

Returns:Host volumes.
Return type:dockermap.map.config.host_volume.HostVolumeConfiguration
merge_default_from_dict(key, value, lists_only=False)
merge_from_obj(obj, lists_only=False)
name

Container map name.

Returns:Container map name.
Return type:unicode | str
networks

Network configurations on the map.

Returns:Network configurations.
Return type:dict[unicode | str, dockermap.map.config.network.NetworkConfiguration]
repository

Repository prefix for images. This is prepended to image names used by container configurations.

set_hostname

Whether to set the hostname for new containers. When set to False, uses Docker’s default autogeneration of hostnames instead.

update_default_from_dict(key, value)
update_from_obj(obj, copy=False, update_containers=True)
use_attached_parent_name

Whether to include the parent name of an attached volume in the attached container name for disambiguation.

volumes

Volume configurations on the map.

Returns:Volume configurations.
Return type:dict[unicode | str, dockermap.map.config.volume.VolumeConfiguration]

dockermap.map.config.network module

class dockermap.map.config.network.NetworkConfiguration(values=None, **kwargs)

Bases: dockermap.map.config.ConfigurationObject

Configuration class for networks.

create_options

Additional keyword arguments to creating the network.

driver

The network driver name.

driver_options

Custom options to the driver.

internal

Whether the network is internal.

dockermap.map.config.utils module

dockermap.map.config.utils.expand_groups(config_ids, maps)

Iterates over a list of container configuration ids, expanding groups of container configurations.

Parameters:
  • config_ids (collections.Iterable[dockermap.map.input.InputConfigId | dockermap.map.input.MapConfigId]) – List of container configuration ids.
  • maps (dict[unicode | str, dockermap.map.config.main.ContainerMap]) – Extended container maps.
Returns:

Expanded MapConfigId tuples.

Return type:

collections.Iterable[dockermap.map.input.InputConfigId]

dockermap.map.config.utils.expand_instances(config_ids, ext_maps)

Iterates over a list of input configuration ids, expanding configured instances if None is specified. Otherwise where instance names are specified as a tuple, they are expanded.

Parameters:
  • config_ids (collections.Iterable[dockermap.map.input.InputConfigId] | collections.Iterable[tuple[unicode | str, unicode | str, unicode | str]]) – Iterable of container configuration ids or (map, config, instance names) tuples.
  • ext_maps (dict[unicode | str, ContainerMap]) – Dictionary of extended ContainerMap instances for looking up container configurations.
Returns:

MapConfigId tuples.

Return type:

collections.Iterable[dockermap.map.input.MapConfigId]

dockermap.map.config.utils.get_map_config_ids(value, maps, default_map_name=None, default_instances=None)

From a value, which can be a string, a iterable of strings, or MapConfigId tuple(s), generates a list of MapConfigId tuples with expanded groups, listing all input or configured instances, and sorted by map and configuration.

Parameters:
  • value (str | unicode | dockermap.map.input.InputConfigId | collection.Iterable[str | unicode | dockermap.map.input.InputConfigId]) – Input value(s).
  • maps – Dictionary with expanded container maps, for resolving groups, aliases ('__all__'), and configured instances in absence of instance specification in the input.
  • default_map_name – Default map name that is used, in case it is not part of the input.
  • default_instances – Default instance name list that is used, in case it is not specified in the input.
Returns:

List of MapConfigId tuples.

Return type:

list[dockermap.map.input.MapConfigId]

dockermap.map.config.volume module

class dockermap.map.config.volume.VolumeConfiguration(*args, **kwargs)

Bases: dockermap.map.config.ConfigurationObject

Configuration class for networks.

create_options

Additional keyword arguments to creating the volume.

default_path

Default path of the volume when used in a container. If the Docker host does not yet support named volumes yet, this path also applies to all containers using the volume.

driver

The volume driver name.

driver_options

Custom options to the driver.

merge_from_dict(dct, lists_only=False)
permissions

Permission flags to be set for attached volumes. Can be in any notation accepted by chmod. This takes precedence over the permissions set in each container config attaching this volume, where applicable.

update_from_dict(dct)
user

User name / group or id of the owner to be set on the volume. By default uses the user of the container that attaches the volume. Can be set as a string (user_name or user_name:group), ids (e.g. user_id:group_id), tuple ((user_name, group_name)), or int (user_id). This takes precedence over the user set in each container config attaching this volume, where applicable.

class dockermap.map.config.volume.VolumeConfigurationMap(default_factory=None, *args, **kwargs)

Bases: dockermap.map.DefaultDictMap

default_factory

alias of VolumeConfiguration

get_default_paths()

Returns the default paths (visible from inside the container) of each volume.

Returns:Default volume paths.
Return type:dict[unicode | str, unicode | str | dockermap.functional.AbstractLazyObject]
get_permissions()

Returns the permissions to set for each volume.

Returns:Volume permissions.
Return type:dict[unicode | str, unicode | str | dockermap.functional.AbstractLazyObject]
get_users()

Returns the users to set for each volume.

Returns:Volume users.
Return type:dict[unicode | str, unicode | str | int | dockermap.functional.AbstractLazyObject]
update(other=None, **kwargs)

Module contents

dockermap.map.config.CP

alias of ConfigurationProperty

class dockermap.map.config.ConfigurationMeta

Bases: type

class dockermap.map.config.ConfigurationObject(values=None, **kwargs)

Bases: object

CONFIG_PROPERTIES = OrderedDict()
DOCSTRINGS = {}
as_dict()

Returns a copy of the configuration dictionary. Changes in this should not reflect on the original object.

Returns:Configuration dictionary.
Return type:dict
clean()

Cleans the input values of this configuration object.

Fields that have gotten updated through properties are converted to configuration values that match the format needed by functions using them. For example, for list-like values it means that input of single strings is transformed into a single-entry list. If this conversion fails, a ValueError is raised.

copy()

Creates a copy of the current instance.

Returns:Copy of this ConfigurationObject.
Return type:ConfigurationObject
is_clean

Whether the current object is ‘clean’, i.e. has no non-converted input.

Returns:True if no values have been modified since the last clean, False otherwise.
Return type:bool
merge(values, lists_only=False)

Merges list-based attributes into one list including unique elements from both lists. When lists_only is set to False, updates dictionaries and overwrites single-value attributes. The resulting configuration is ‘clean’, i.e. input values converted and validated. If the conversion is not possible, a ValueError is raised.

Parameters:
  • values (dict | ConfigurationObject) – Values to update the ConfigurationObject with.
  • lists_only (bool) – Ignore single-value attributes and update dictionary options.
merge_default_from_dict(key, value, lists_only=False)

When merging from a dictionary, this is processed for any key that does not match a ConfigurationProperty.

Parameters:
Returns:

merge_from_dict(dct, lists_only=False)

Merges a dictionary into this configuration object.

See ConfigurationObject.merge() for details.

Parameters:
  • dct (dict) – Values to update the ConfigurationObject with.
  • lists_only (bool) – Ignore single-value attributes and update dictionary options.
merge_from_obj(obj, lists_only=False)

Merges a configuration object into this one.

See ConfigurationObject.merge() for details.

Parameters:
  • obj (ConfigurationObject) – Values to update the ConfigurationObject with.
  • lists_only (bool) – Ignore single-value attributes and update dictionary options.
update(values, copy_instance=False)

Updates the configuration with the contents of the given configuration object or dictionary.

In case of a dictionary, only valid attributes for this class are considered. Existing attributes are replaced with the new values. The object is not cleaned before or after, i.e. may accept invalid input.

In case of an update by object, that object is cleaned before the update, so that updated values should be validated. However, already-stored values are not cleaned before or after.

Parameters:
  • values (dict | ConfigurationObject) – Dictionary or ConfigurationObject to update this configuration with.
  • copy_instance (bool) – Copies lists and dictionaries. Only has an effect if values is a ConfigurationObject.
update_default_from_dict(key, value)

When updating from a dictionary, this is processed for any key that does not match a ConfigurationProperty.

Parameters:
  • key (unicode | str) – Dictionary key.
  • value – Dictionary value.
update_from_dict(dct)

Updates this configuration object from a dictionary.

See ConfigurationObject.update() for details.

Parameters:dct (dict) – Values to update the ConfigurationObject with.
update_from_obj(obj, copy=False)

Updates this configuration object from another.

See ConfigurationObject.update() for details.

Parameters:
  • obj (ConfigurationObject) – Values to update the ConfigurationObject with.
  • copy (bool) – Copies lists and dictionaries.
class dockermap.map.config.ConfigurationProperty

Bases: dockermap.map.config.ConfigurationProperty