xd.docker.parameters module¶

Module containing helper classes and functions for handling Docker Remote API parameters.

xd.docker.parameters.ApiVersion¶

alias of Tuple

xd.docker.parameters.json_update(obj, values, json_fields, api_version=None)[source]¶

Update JSON object (dict).

This function is used to update a JSON object (a dict) with name/value pairs from the values argument, based on the specification in json_fields and api_version arguments.

Parameters:	obj (Dict[str, Any]) – JSON object to update. values (Dict[str, Any]) – Name/value pairs to update with. json_fields (Sequence[Tuple[str, Tuple[int, int], str]]) – Specification of supported JSON object name/value pairs, including information on which API version they are supported in. api_version (Optional[Tuple[int, int]]) – API version to update for.

class xd.docker.parameters.Parameter[source]¶

Bases: object

Base class for all XD Docker parameter classes.

json(api_version=None)[source]¶

Return Docker Remote API JSON representation.

Parameters:	api_version (Optional[Tuple[int, int]]) – Docker Remote API version.

class xd.docker.parameters.Hostname(hostname)[source]¶

Bases: xd.docker.parameters.Parameter

Hostname.

A Hostname instance represents a network hostname. A hostname must not contain dots (‘.’). To specify a fully qualified domain name, use Domainname.

Parameters:	hostname (str) – Hostname.

hostname¶

str – Hostname.

class xd.docker.parameters.Domainname(domainname)[source]¶

Bases: xd.docker.parameters.Hostname

Domain name.

A Domainname instance represents a network domain name.

Parameters:	domainname (str) – Domain name.

domainname¶

str – Domain name.

class xd.docker.parameters.MacAddress(addr)[source]¶

Bases: xd.docker.parameters.Parameter

Ethernet MAC address.

A MacAddress instance represents an Ethernet MAC address.

Parameters:	addr (str) – MAC address (fx. ‘01:02:03:04:05:06’).

addr¶

str – MAC address (fx. ‘01:02:03:04:05:06’).

class xd.docker.parameters.Username(username)[source]¶

Bases: xd.docker.parameters.Parameter

User name.

A Username instance represents a UNIX user name.

Parameters:	username (str) – User name.

username¶

str – User name.

class xd.docker.parameters.Repository(repo)[source]¶

Bases: xd.docker.parameters.Parameter

Repository name (and optionally tag) parameter.

A Repository instance is used to represent a Docker repository name, or repository name and tag.

Parameters:	repo (str) – Repository name, or name and tag (separated by ‘:’).

name¶

str – Repository name.

tag¶

Optional[str] – Repository tag.

class xd.docker.parameters.RepoTags(repos)[source]¶

Bases: xd.docker.parameters.Parameter

List of repository name and tags.

A RepoTags instance is used to represent a list of repository name and tags.

Parameters:	repos (List[str]) – List of repository name and tags (separated by ‘:’).

repos¶

List[Repository] – List of repository name and tags.

class xd.docker.parameters.ContainerName(name)[source]¶

Bases: xd.docker.parameters.Parameter

Container name parameter.

A ContainerName instance is used to represent a Docker container name.

Parameters:	name (str) – Container name

name¶

str – Container name.

class xd.docker.parameters.Env(env=None)[source]¶

Bases: xd.docker.parameters.Parameter

Environment variables.

An Environment instance contains the environment variables for a Docker container.

Parameters:	env (Optional[Mapping[str, str]]) – Environment variables, name/value pairs.

env¶

Mapping[str, str] – Environment variables, name/value pairs.

class xd.docker.parameters.Port(port, protocol='tcp')[source]¶

Bases: xd.docker.parameters.Parameter

Network port.

A Port instance represents a network port (TCP or UDP).

Parameters:	port (int) – Port number. protocol (str) – Protocol (‘tcp’ or ‘udp’).

port¶

int – Port number.

protocol¶

str – Protocol (‘tcp’ or ‘udp’).

class xd.docker.parameters.PortBinding(port, protocol='tcp', host_ip=None, host_port=None)[source]¶

Bases: xd.docker.parameters.Parameter

Docker container port binding.

A PortBinding instance represents a binding of a network port of a Docker container to a host port.

Parameters:	port (int) – Container port number. protocol (str) – Protocol (‘tcp’ or ‘udp’). host_ip (Union[IPv4Address, IPv6Address, None]) – Host IP address. host_port (Optional[int]) – Host port number (defaults to container port number).

port¶

int – Container port number (1 ... 65535).

protocol¶

str – Protocol (‘tcp’ or ‘udp’).

host_ip¶

Optional[IPAddress] – Host IP address.

host_port¶

int – Host port number (1 ... 65535).

class xd.docker.parameters.VolumeMount(source, destination, ro=False, label_mode=None)[source]¶

Bases: xd.docker.parameters.Parameter

Volume mount point.

A VolumeMount instance represents a container mount point.

Parameters:	source (str) – Host path. destination (str) – Container path. ro (bool) – Read-only mount. label_mode (Optional[str]) – SELinux label mode (‘z’ or ‘Z’).

source¶

str – Source path.

destination¶

str – Destination path.

ro¶

bool – Read-only mount.

label_mode¶

str – SELinux label mode (‘’, ‘z’, or ‘Z’).

class xd.docker.parameters.VolumeBinding(container_path, volume=None, ro=False)[source]¶

Bases: xd.docker.parameters.Parameter

Volume binding.

A VolumeBinding instance represents a volume binding for a container. The binding can either be to a new volume, an existing host path, or a volume provided by a Docker volume plugin.

Parameters:	container_path (str) – Container path to bind the volume to. volume (Optional[str]) – Host path or volume name, identifying the volume to bind to. Host path must start with a ‘/’. Volume name must not begin with a ‘/’. ro (bool) – Read-only mount.

container_path¶

str – Container path to bind the volume to.

volume¶

Optional[str] – Host path or volume name, identifying the volume to bind to.

ro¶

bool – Read-only mount.

class xd.docker.parameters.ContainerLink(name, alias)[source]¶

Bases: xd.docker.parameters.Parameter

Container link.

A ContainerLink instance represents a link to another container.

Parameters:	name (str) – Name of container to link to. alias (str) – Alias to use for linked container.

name¶

str – Name of container to link to.

alias¶

str – Alias to use for linked container.

class xd.docker.parameters.Cpuset(cpuset)[source]¶

Bases: xd.docker.parameters.Parameter

List of CPUs.

A Cpuset instance represents a set of CPU or memory nodes, for use when specifying where to run a container.

Parameters:	cpuset (str) – Cpuset specification. See cpuset(7) for syntax.

cpuset¶

str – Cpuset specification.

class xd.docker.parameters.HostnameIPMapping(hostname, ip)[source]¶

Bases: xd.docker.parameters.Parameter

Hostname to IP address mapping.

A HostnameIPMapping instance represents a mapping from a hostname to an IP address (IPv6 or IPv4).

Parameters:	hostname (Union[Hostname, str]) – Hostname. ip (Union[IPv4Address, IPv6Address, str]) – IP address.

hostname¶

Hostname – Hostname.

ip¶

IPAddress – IP address.

class xd.docker.parameters.VolumesFrom(name, ro=None)[source]¶

Bases: xd.docker.parameters.Parameter

Docker container to inherit volumes from.

A VolumesFrom instance represents a single docker container to inherit volumes from.

Parameters:	name (Union[ContainerName, str]) – Container name. ro (Optional[bool]) – Mount volumes read-only (default is read/write).

name¶

ContainerName – Container name.

ro¶

Optional[bool] – Mount volumes read-only.

class xd.docker.parameters.RestartPolicy(policy, maximum_retry_count=None)[source]¶

Bases: xd.docker.parameters.Parameter

Restart policy for when the container exits.

A RestartPolicy instance represents the restart policy to use when container exits.

Parameters:	policy (str) – One of ‘always’, ‘unless-stopped’, or ‘on-failure. maximum_retry_count (Optional[int]) – Number of times to retry before giving up (required and only allowed together with ‘on-failure’)

policy¶

str – One of ‘always’, ‘unless-stopped’, or ‘on-failure’.

maximum_retry_count¶

int – Number of times to retry before giving up (only present when policy is ‘on-failure’).

class xd.docker.parameters.DeviceToAdd(path_on_host, path_in_container=None, cgroup_permissions='rwm')[source]¶

Bases: xd.docker.parameters.Parameter

Device to add to container.

A DeviceToAdd instance represents a device to add to a container.

Parameters:	path_on_host (str) – Device path on host. path_in_container (Optional[str]) – Device path in container (defaults to path_on_host). cgroup_permissions (str) – Access permission, composition of ‘r’ (read), ‘w’ (write), and ‘m’ (mknod) (defaults to ‘rwm’).

path_on_host¶

str – Device path on host.

path_in_container¶

str – Device path in container.

cgroup_permissions¶

str – Access permission, composition of ‘r’ (read), ‘w’ (write), and ‘m’ (mknod).

class xd.docker.parameters.Ulimit(name, soft, hard=None)[source]¶

Bases: xd.docker.parameters.Parameter

Ulimit parameter.

A Ulimit instance represents a ulimit (user limit) to set in a container.

Parameters:	name (str) – Name of ulimit. soft (int) – Soft limit. hard (Optional[int]) – Hard limit (defaults to soft limit).

name¶

str – Name of ulimit.

soft¶

str – Soft limit.

hard¶

str – Hard limit.

class xd.docker.parameters.LogConfiguration(type, config=None)[source]¶

Bases: xd.docker.parameters.Parameter

Log configuration for container.

A LogConfiguration instance represents configuration of how logging is done for a container.

Parameters:	type (str) – Logging driver name. config (Optional[Mapping[str, str]]) – Driver specific configuration parameters.

type¶

str – Logging driver name.

config¶

Dict[str, str] – Driver specific configuration parameters.

class xd.docker.parameters.AuthConfig[source]¶

Bases: xd.docker.parameters.Parameter

Login information for a docker registry.

An AuthConfig instance represents login information for authenticating to a docker repository.

class xd.docker.parameters.CredentialAuthConfig(username, password, email=None)[source]¶

Bases: xd.docker.parameters.AuthConfig

Credential based login information for a docker registry.

A CredentialAuthConfig instance represents credential based login information for authenticating to a docker repository.

Parameters:	username (str) – User name. password (str) – Password. email (Optional[str]) – Email address.

username¶

str – User name.

password¶

str – Password.

email¶

Optional[str] – Email address.

class xd.docker.parameters.TokenAuthConfig(token)[source]¶

Bases: xd.docker.parameters.AuthConfig

Token based login information for a docker registry.

A TokenAuthConfig instance represents token based login information for authenticating to a docker repository.

Parameters:	token (str) – Login token.

token¶

str – Login token.

class xd.docker.parameters.RegistryAuthConfig(registry_auths)[source]¶

Bases: xd.docker.parameters.Parameter

Docker registry authentication configuration.

A RegistryAuthConfig instance represents the login information for one or more docker registries.

Parameters:

registry_auths (Mapping[str, AuthConfig]) – Mapping of registry hostnames to the login information for authenticating to that registry. Only the registry domain name (and port if not the default “443”) are required. However (for legacy reasons) the “official” Docker, Inc. hosted registry must be specified with both a “https://” prefix and a “/v1/” suffix even though Docker will prefer to use the v2 registry API.

registry_auths¶

Mapping of registry hostnames to login information.

class xd.docker.parameters.ContainerConfig(image, command=None, entrypoint=None, on_build=None, hostname=None, domainname=None, user=None, attach_stdin=None, attach_stdout=None, attach_stderr=None, tty=None, open_stdin=None, stdin_once=None, env=None, labels=None, working_dir=None, network=None, mac_address=None, exposed_ports=None, volumes=None, stop_signal=None)[source]¶

Bases: xd.docker.parameters.Parameter

Container configuration parameter.

A ContainerConfig instance represents the configuration of a container.

Parameters:

image (str) – Image to create container from. command (Optional[Sequence[str]]) – Command to run. entrypoint (Optional[Sequence[str]]) – Container entrypoint. on_build (Optional[Sequence[str]]) – Trigger instructions to be executed later (when used as base image for another build). hostname (Union[Hostname, str, None]) – Hostname to use for the container. domainname (Union[Domainname, str, None]) – Domain name to use for the container. user (Union[Username, str, None]) – User inside the container. attach_stdin (Optional[bool]) – Attach to stdin. attach_stdout (Optional[bool]) – Attach to stdout. attach_stderr (Optional[bool]) – Attach to stderr. tty (Optional[bool]) – Attach standard streams to a tty. open_stdin (Optional[bool]) – Open stdin. stdin_once (Optional[bool]) – Close stdin after the client disconnects. env (Union[Env, Mapping[str, str], None]) – Environment variables. labels (Optional[Mapping[str, str]]) – Labels to set on container. working_dir (Optional[str]) – Working directory for command to run in. network (Optional[bool]) – Whether to enable networking in the container. mac_address (Union[MacAddress, str, None]) – MAC address. exposed_ports (Optional[Sequence[Port]]) – Exposed ports. volumes (Optional[Sequence[str]]) – List of (in container) paths to use as volumes. stop_signal (Union[int, str, None]) – Signal to stop container.

image¶

str – Image to create container from.

command¶

Optional[Command] – Command to run.

entrypoint¶

Optional[Command] – Container entrypoint.

on_build¶

Optional[Sequence[str]] – Trigger instructions to be executed later (when used as base image for another build).

hostname¶

Optional[Hostname] – Hostname to use for the container.

domainname¶

Optional[Domainname] – Domain name to use for the container.

user¶

Optional[Username] – User inside the container.

attach_stdin¶

Optional[bool] – Attach to stdin.

attach_stdout¶

Optional[bool] – Attach to stdout.

attach_stderr¶

Optional[bool] – Attach to stderr.

tty¶

Optional[bool] – Attach standard streams to a tty.

open_stdin¶

Optional[bool] – Open stdin.

stdin_once¶

Optional[bool] – Close stdin after the client disconnects.

env¶

Optional[Env] – Environment variables.

labels¶

Optional[Mapping[str, str]] – Labels to set on container.

working_dir¶

Optional[str] – Working directory for command to run in.

network¶

Optional[bool] – Whether to enable networking in the container.

mac_address¶

Optional[MacAddress] – MAC address.

exposed_ports¶

Optional[Sequence[Port]] – Exposed ports.

volumes¶

Optional[Sequence[str] – List of (in container) paths to use as volumes.

stop_signal¶

Optional[Union[int, str]] – Signal to stop container.

class xd.docker.parameters.HostConfig(binds=None, links=None, lxc_conf=None, port_bindings=None, publish_all_ports=None, privileged=None, read_only_rootfs=None, dns=None, dns_options=None, dns_search=None, extra_hosts=None, volumes_from=None, cap_add=None, cap_drop=None, group_add=None, restart_policy=None, network_mode=None, devices=None, ulimits=None, security_opt=None, log_config=None, cgroup_parent=None, volume_driver=None, shm_size=None, memory=None, swap=None, memory_reservation=None, kernel_memory=None, cpu_shares=None, cpu_period=None, cpu_quota=None, cpuset_cpus=None, cpuset_mems=None, blkio_weight=None, memory_swappiness=None, oom_kill=None)[source]¶

Bases: xd.docker.parameters.Parameter

Docker container host configuration.

Parameters:

binds (Optional[Sequence[VolumeBinding]]) – List of volume bindings. links (Optional[Sequence[ContainerLink]]) – List of links to other containers. lxc_config – LXC specific configurations. Only valid when using the lxc execution driver. port_bindings (Optional[Sequence[PortBinding]]) – List of port bindings, ie. container ports that exposed as host ports. publish_all_ports (Optional[bool]) – Allocate a random host port for all exposed ports. privileged (Optional[bool]) – Container has full access to host. read_only_rootfs (Optional[bool]) – Mount container root filesystem read only. dns (Optional[Sequence[Union[IPv4Address, IPv6Address]]]) – List of DNS servers to use. dns_options (Optional[Sequence[str]]) – List of DNS options. dns_search (Optional[Sequence[str]]) – List of DNS search domains. extra_hosts (Optional[Sequence[Union[HostnameIPMapping, str]]]) – A list of hostname to IP mappings to add to container’s /etc/hosts file. volumes_from (Optional[Sequence[Union[VolumesFrom, str]]]) – List of containers to inherit volumes from. cap_add (Optional[Sequence[str]]) – List of kernel capabilities to add to container. cap_drop (Optional[Sequence[str]]) – List of kernel capabilities to drop from container. group_add (Optional[Sequence[str]]) – List of additional groups that the container process will run as. restart_policy (Optional[RestartPolicy]) – Behavior when container exits. network_mode (Optional[str]) – Networking mode for the container. devices (Optional[Sequence[Union[DeviceToAdd, str]]]) – List of devices to add to container. ulimits (Optional[Sequence[Ulimit]]) – List of ulimits to set in container. security_opt (Optional[Sequence[str]]) – List of string values to customize labels for MLS systems, such as SELinux. log_config (Optional[LogConfiguration]) – Log configuration for container. cgroup_parent (Optional[str]) – Path to cgroups under which the container’s cgroup is created. volume_driver (Optional[str]) – Driver that this container uses to mount volumes. shm_size (Optional[int]) – Size of /dev/shm in bytes. memory (Optional[int]) – Memory limit in bytes. swap (Optional[int]) – Swap limit in bytes. memory_reservation (Optional[int]) – Memory soft limit in bytes. kernel_memory (Optional[int]) – Kernel memory limit in bytes. cpu_shares (Optional[int]) – CPU shares relative to other containers. cpu_period (Optional[int]) – Length of a CPU period in microseconds. cpu_quota (Optional[int]) – Microseconds of CPU time that the container can get in a CPU period. cpuset_cpus (Union[Cpuset, str, None]) – Cgroups cpuset.cpu to use. cpuset_mems (Union[Cpuset, str, None]) – Cgroups cpuset.mem to use. blkio_weight (Optional[int]) – Relative block io weight (10 ... 1000). memory_swappiness (Optional[int]) – Memory swappiness behavior (10 ... 100). oom_kill (Optional[bool]) – Enable OOM killer for container.

binds¶

Optional[List[VolumeBinding]] – List of volume bindings.

links¶

Optional[List[ContainerLink]] – List of links to other containers.

lxc_config¶

Optional[Dict[str, str]] – LXC specific configurations. Only valid when using the lxc execution driver.

port_bindings¶

Optional[List[PortBinding]] – List of port bindings, ie. container ports that exposed as host ports.

publish_all_ports¶

Optional[bool] – Allocate a random host port for all exposed ports.

privileged¶

Optional[bool] – Container has full access to host.

read_only_rootfs¶

Optional[bool] – Mount container root filesystem read only.

dns¶

Optional[List[IPAddress]] – List of DNS servers to use.

dns_options¶

Optional[List[str]] – List of DNS options.

dns_search¶

Optional[List[str]] – List of DNS search domains.

extra_hosts¶

Optional[List[HostnameIPMapping]] – A list of hostname to IP mappings to add to container’s /etc/hosts file.

volumes_from¶

Optional[List[VolumesFrom]] – List of containers to inherit volumes from.

cap_add¶

Optional[List[str]] – List of kernel capabilities to add to container.

cap_drop¶

Optional[List[str]] – List of kernel capabilities to drop from container.

group_add¶

Optional[List[str]] – List of additional groups that the container process will run as.

restart_policy¶

Optional[RestartPolicy] – Behavior when container exits.

network_mode¶

Optional[str] – Networking mode for the container.

devices¶

Optional[List[DeviceToAdd]] – List of devices to add to container.

ulimits¶

Optional[List[Ulimit]] – List of ulimits to set in container.

security_opt¶

Optional[List[str]] – List of string values to customize labels for MLS systems, such as SELinux.

log_config¶

Optional[LogConfiguration] – Log configuration for container.

cgroup_parent¶

Optional[str] – Path to cgroups under which the container’s cgroup is created.

volume_driver¶

Optional[str] – Driver that this container uses to mount volumes.

shm_size¶

Optional[int] – Size of /dev/shm in bytes.

memory¶

Optional[int] – Memory limit in bytes.

swap¶

Optional[int] – Swap limit in bytes.

memory_reservation¶

Optional[int] – Memory soft limit in bytes.

kernel_memory¶

Optional[int] – Kernel memory limit in bytes.

cpu_shares¶

Optional[int] – CPU shares relative to other containers.

cpu_period¶

Optional[int] – Length of a CPU period in microseconds.

cpu_quota¶

Optional[int] – Microseconds of CPU time that the container can get in a CPU period.

cpuset_cpus¶

Optional[Cpuset] – Cgroups cpuset.cpu to use.

cpuset_mems¶

Optional[Cpuset] – Cgroups cpuset.mem to use.

blkio_weight¶

Optional[int] – Relative block io weight (10 ... 1000).

memory_swappiness¶

Optional[int] – Memory swappiness behavior (10 ... 100).

oom_kill¶

Optional[bool] – Enable OOM killer for container.