docker_swarm_service – docker swarm service¶
New in version 2.7.
Requirements¶
The below requirements are needed on the host that executes this module.
- Docker API >= 1.24
- Docker SDK for Python: Please note that the docker-py Python module has been superseded by docker (see here for details). This module does not work with docker-py.
- Docker SDK for Python >= 2.0.2
- Python >= 2.7
Parameters¶
| Parameter | Choices/Defaults | Comments | ||
|---|---|---|---|---|
| api_version 
                    string
                                                                 | Default: "auto" | The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported by Docker SDK for Python and the docker daemon. If the value is not specified in the task, the value of environment variable  DOCKER_API_VERSIONwill be used instead. If the environment variable is not set, the default value will be used.aliases: docker_api_version | ||
| args 
                    list
                     / elements=string                                             | List arguments to be passed to the container. Corresponds to the  ARGparameter ofdocker service create. | |||
| ca_cert 
                    path
                                                                 | Use a CA certificate when performing server verification by providing the path to a CA certificate file. If the value is not specified in the task and the environment variable  DOCKER_CERT_PATHis set, the fileca.pemfrom the directory specified in the environment variableDOCKER_CERT_PATHwill be used.aliases: tls_ca_cert, cacert_path | |||
| client_cert 
                    path
                                                                 | Path to the client's TLS certificate file. If the value is not specified in the task and the environment variable  DOCKER_CERT_PATHis set, the filecert.pemfrom the directory specified in the environment variableDOCKER_CERT_PATHwill be used.aliases: tls_client_cert, cert_path | |||
| client_key 
                    path
                                                                 | Path to the client's TLS key file. If the value is not specified in the task and the environment variable  DOCKER_CERT_PATHis set, the filekey.pemfrom the directory specified in the environment variableDOCKER_CERT_PATHwill be used.aliases: tls_client_key, key_path | |||
| command 
                    raw
                                                                 added in 2.8 | Command to execute when the container starts. A command may be either a string or a list or a list of strings. Corresponds to the  COMMANDparameter ofdocker service create. | |||
| configs 
                    list
                     / elements=dictionary                                             | List of dictionaries describing the service configs. Corresponds to the  --configoption ofdocker service create.Requires API version >= 1.30. | |||
| config_id 
                    string
                                                                 | Config's ID. | |||
| config_name 
                    string
                                             / required                     | Config's name as defined at its creation. | |||
| filename 
                    string
                                                                 | Name of the file containing the config. Defaults to the config_name if not specified. | |||
| gid 
                    string
                                                                 | GID of the config file's group. | |||
| mode 
                    integer
                                                                 | File access mode inside the container. Must be an octal number (like  0644or0444). | |||
| uid 
                    string
                                                                 | UID of the config file's owner. | |||
| constraints 
                    list
                     / elements=string                                             | List of the service constraints. Corresponds to the  --constraintoption ofdocker service create.Deprecated in 2.8, will be removed in 2.12. Use parameter  placement.constraintsinstead. | |||
| container_labels 
                    dictionary
                                                                 | Dictionary of key value pairs. Corresponds to the  --container-labeloption ofdocker service create. | |||
| debug 
                    boolean
                                                                 | 
 | Debug mode | ||
| dns 
                    list
                     / elements=string                                             | List of custom DNS servers. Corresponds to the  --dnsoption ofdocker service create.Requires API version >= 1.25. | |||
| dns_options 
                    list
                     / elements=string                                             | List of custom DNS options. Corresponds to the  --dns-optionoption ofdocker service create.Requires API version >= 1.25. | |||
| dns_search 
                    list
                     / elements=string                                             | List of custom DNS search domains. Corresponds to the  --dns-searchoption ofdocker service create.Requires API version >= 1.25. | |||
| docker_host 
                    string
                                                                 | Default: "unix://var/run/docker.sock" | The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the TCP connection string. For example,  tcp://192.0.2.23:2376. If TLS is used to encrypt the connection, the module will automatically replacetcpin the connection URL withhttps.If the value is not specified in the task, the value of environment variable  DOCKER_HOSTwill be used instead. If the environment variable is not set, the default value will be used.aliases: docker_url | ||
| endpoint_mode 
                    string
                                                                 | 
 | Service endpoint mode. Corresponds to the  --endpoint-modeoption ofdocker service create.Requires API version >= 1.25. | ||
| env 
                    raw
                                                                 | List or dictionary of the service environment variables. If passed a list each items need to be in the format of  KEY=VALUE.If passed a dictionary values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (e.g.  "true") in order to avoid data loss.Corresponds to the  --envoption ofdocker service create. | |||
| env_files 
                    list
                     / elements=path                                             added in 2.8 | List of paths to files, present on the target, containing environment variables  FOO=BAR.The order of the list is significant in determining the value assigned to a variable that shows up more than once. If variable also present in env, then env value will override. | |||
| force_update 
                    boolean
                                                                 | 
 | Force update even if no changes require it. Corresponds to the  --forceoption ofdocker service update.Requires API version >= 1.25. | ||
| groups 
                    list
                     / elements=string                                             added in 2.8 | List of additional group names and/or IDs that the container process will run as. Corresponds to the  --groupoption ofdocker service update.Requires API version >= 1.25. | |||
| healthcheck 
                    dictionary
                                                                 added in 2.8 | Configure a check that is run to determine whether or not containers for this service are "healthy". See the docs for the HEALTHCHECK Dockerfile instruction for details on how healthchecks work. interval, timeout and start_period are specified as durations. They accept duration as a string in a format that look like:  5h34m56s,1m30setc. The supported units areus,ms,s,mandh.Requires API version >= 1.25. | |||
| interval 
                    string
                                                                 | Time between running the check. | |||
| retries 
                    integer
                                                                 | Consecutive failures needed to report unhealthy. It accept integer value. | |||
| start_period 
                    string
                                                                 | Start period for the container to initialize before starting health-retries countdown. | |||
| test 
                    raw
                                                                 | Command to run to check health. Must be either a string or a list. If it is a list, the first item must be one of  NONE,CMDorCMD-SHELL. | |||
| timeout 
                    string
                                                                 | Maximum time to allow one check to run. | |||
| hostname 
                    string
                                                                 | Container hostname. Corresponds to the  --hostnameoption ofdocker service create.Requires API version >= 1.25. | |||
| hosts 
                    dictionary
                                                                 added in 2.8 | Dict of host-to-IP mappings, where each host name is a key in the dictionary. Each host name will be added to the container's /etc/hosts file. Corresponds to the  --hostoption ofdocker service create.Requires API version >= 1.25. | |||
| image 
                    string
                                                                 | Service image path and tag. Corresponds to the  IMAGEparameter ofdocker service create. | |||
| labels 
                    dictionary
                                                                 | Dictionary of key value pairs. Corresponds to the  --labeloption ofdocker service create. | |||
| limit_cpu 
                    float
                                                                 | Service CPU limit.  0equals no limit.Corresponds to the  --limit-cpuoption ofdocker service create.Deprecated in 2.8, will be removed in 2.12. Use parameter  limits.cpusinstead. | |||
| limit_memory 
                    string
                                                                 | Service memory limit in format  <number>[<unit>]. Number is a positive integer. Unit can beB(byte),K(kibibyte, 1024B),M(mebibyte),G(gibibyte),T(tebibyte), orP(pebibyte).0equals no limit.Omitting the unit defaults to bytes. Corresponds to the  --limit-memoryoption ofdocker service create.Deprecated in 2.8, will be removed in 2.12. Use parameter  limits.memoryinstead. | |||
| limits 
                    dictionary
                                                                 added in 2.8 | Configures service resource limits. | |||
| cpus 
                    float
                                                                 | Service CPU limit.  0equals no limit.Corresponds to the  --limit-cpuoption ofdocker service create. | |||
| memory 
                    string
                                                                 | Service memory limit in format  <number>[<unit>]. Number is a positive integer. Unit can beB(byte),K(kibibyte, 1024B),M(mebibyte),G(gibibyte),T(tebibyte), orP(pebibyte).0equals no limit.Omitting the unit defaults to bytes. Corresponds to the  --limit-memoryoption ofdocker service create. | |||
| log_driver 
                    string
                                                                 | Configure the logging driver for a service. Corresponds to the  --log-driveroption ofdocker service create.Deprecated in 2.8, will be removed in 2.12. Use parameter  logging.driverinstead. | |||
| log_driver_options 
                    dictionary
                                                                 | Options for service logging driver. Corresponds to the  --log-optoption ofdocker service create.Deprecated in 2.8, will be removed in 2.12. Use parameter  logging.optionsinstead. | |||
| logging 
                    dictionary
                                                                 added in 2.8 | Logging configuration for the service. | |||
| driver 
                    string
                                                                 | Configure the logging driver for a service. Corresponds to the  --log-driveroption ofdocker service create. | |||
| options 
                    dictionary
                                                                 | Options for service logging driver. Corresponds to the  --log-optoption ofdocker service create. | |||
| mode 
                    string
                                                                 | 
 | Service replication mode. Service will be removed and recreated when changed. Corresponds to the  --modeoption ofdocker service create. | ||
| mounts 
                    list
                     / elements=dictionary                                             | List of dictionaries describing the service mounts. Corresponds to the  --mountoption ofdocker service create. | |||
| driver_config 
                    dictionary
                                                                 added in 2.8 | Volume driver configuration. Can only be used when mode is  volume. | |||
| name 
                    string
                                                                 | Name of the volume-driver plugin to use for the volume. | |||
| options 
                    dictionary
                                                                 | Options as key-value pairs to pass to the driver for this volume. | |||
| labels 
                    dictionary
                                                                 added in 2.8 | Volume labels to apply. | |||
| no_copy 
                    boolean
                                                                 added in 2.8 | 
 | Disable copying of data from a container when a volume is created. Can only be used when mode is  volume. | ||
| propagation 
                    string
                                                                 added in 2.8 | 
 | The propagation mode to use. Can only be used when mode is  bind. | ||
| readonly 
                    boolean
                                                                 | 
 | Whether the mount should be read-only. | ||
| source 
                    string
                                                                 | Mount source (e.g. a volume name or a host path). Must be specified if type is not  tmpfs. | |||
| target 
                    string
                                             / required                     | Container path. | |||
| tmpfs_mode 
                    integer
                                                                 added in 2.8 | File mode of the tmpfs in octal. Can only be used when mode is  tmpfs. | |||
| tmpfs_size 
                    string
                                                                 added in 2.8 | Size of the tmpfs mount in format  <number>[<unit>]. Number is a positive integer. Unit can beB(byte),K(kibibyte, 1024B),M(mebibyte),G(gibibyte),T(tebibyte), orP(pebibyte).Can only be used when mode is  tmpfs. | |||
| type 
                    string
                                                                 | 
 | The mount type. Note that  npipeis only supported by Docker for Windows. Also note thatnpipewas added in Ansible 2.9. | ||
| name 
                    string
                                             / required                     | Service name. Corresponds to the  --nameoption ofdocker service create. | |||
| networks 
                    list
                     / elements=raw                                             | List of the service networks names or dictionaries. When passed dictionaries valid sub-options are name, which is required, and aliases and options. Prior to API version 1.29, updating and removing networks is not supported. If changes are made the service will then be removed and recreated. Corresponds to the  --networkoption ofdocker service create. | |||
| placement 
                    dictionary
                                                                 added in 2.8 | Configures service placement preferences and constraints. | |||
| constraints 
                    list
                     / elements=string                                             | List of the service constraints. Corresponds to the  --constraintoption ofdocker service create. | |||
| preferences 
                    list
                     / elements=dictionary                                             | List of the placement preferences as key value pairs. Corresponds to the  --placement-prefoption ofdocker service create.Requires API version >= 1.27. | |||
| publish 
                    list
                     / elements=dictionary                                             | List of dictionaries describing the service published ports. Corresponds to the  --publishoption ofdocker service create.Requires API version >= 1.25. | |||
| mode 
                    string
                                                                 | 
 | What publish mode to use. Requires API version >= 1.32. | ||
| protocol 
                    string
                                                                 | 
 | What protocol to use. | ||
| published_port 
                    integer
                                             / required                     | The port to make externally available. | |||
| target_port 
                    integer
                                             / required                     | The port inside the container to expose. | |||
| read_only 
                    boolean
                                                                 added in 2.8 | 
 | Mount the containers root filesystem as read only. Corresponds to the  --read-onlyoption ofdocker service create. | ||
| replicas 
                    integer
                                                                 | Default: -1 | Number of containers instantiated in the service. Valid only if mode is  replicated.If set to  -1, and service is not present, service replicas will be set to1.If set to  -1, and service is present, service replicas will be unchanged.Corresponds to the  --replicasoption ofdocker service create. | ||
| reservations 
                    dictionary
                                                                 added in 2.8 | Configures service resource reservations. | |||
| cpus 
                    float
                                                                 | Service CPU reservation.  0equals no reservation.Corresponds to the  --reserve-cpuoption ofdocker service create. | |||
| memory 
                    string
                                                                 | Service memory reservation in format  <number>[<unit>]. Number is a positive integer. Unit can beB(byte),K(kibibyte, 1024B),M(mebibyte),G(gibibyte),T(tebibyte), orP(pebibyte).0equals no reservation.Omitting the unit defaults to bytes. Corresponds to the  --reserve-memoryoption ofdocker service create. | |||
| reserve_cpu 
                    float
                                                                 | Service CPU reservation.  0equals no reservation.Corresponds to the  --reserve-cpuoption ofdocker service create.Deprecated in 2.8, will be removed in 2.12. Use parameter  reservations.cpusinstead. | |||
| reserve_memory 
                    string
                                                                 | Service memory reservation in format  <number>[<unit>]. Number is a positive integer. Unit can beB(byte),K(kibibyte, 1024B),M(mebibyte),G(gibibyte),T(tebibyte), orP(pebibyte).0equals no reservation.Omitting the unit defaults to bytes. Corresponds to the  --reserve-memoryoption ofdocker service create.Deprecated in 2.8, will be removed in 2.12. Use parameter  reservations.memoryinstead. | |||
| resolve_image 
                    boolean
                                                                 added in 2.8 | 
 | If the current image digest should be resolved from registry and updated if changed. Requires API version >= 1.30. | ||
| restart_config 
                    dictionary
                                                                 added in 2.8 | Configures if and how to restart containers when they exit. | |||
| condition 
                    string
                                                                 | 
 | Restart condition of the service. Corresponds to the  --restart-conditionoption ofdocker service create. | ||
| delay 
                    string
                                                                 | Delay between restarts. Accepts a a string in a format that look like:  5h34m56s,1m30setc. The supported units areus,ms,s,mandh.Corresponds to the  --restart-delayoption ofdocker service create. | |||
| max_attempts 
                    integer
                                                                 | Maximum number of service restarts. Corresponds to the  --restart-conditionoption ofdocker service create. | |||
| window 
                    string
                                                                 | Restart policy evaluation window. Accepts a string in a format that look like:  5h34m56s,1m30setc. The supported units areus,ms,s,mandh.Corresponds to the  --restart-windowoption ofdocker service create. | |||
| restart_policy 
                    string
                                                                 | 
 | Restart condition of the service. Corresponds to the  --restart-conditionoption ofdocker service create.Deprecated in 2.8, will be removed in 2.12. Use parameter  restart_config.conditioninstead. | ||
| restart_policy_attempts 
                    integer
                                                                 | Maximum number of service restarts. Corresponds to the  --restart-conditionoption ofdocker service create.Deprecated in 2.8, will be removed in 2.12. Use parameter  restart_config.max_attemptsinstead. | |||
| restart_policy_delay 
                    raw
                                                                 | Delay between restarts. Accepts a duration as an integer in nanoseconds or as a string in a format that look like:  5h34m56s,1m30setc. The supported units areus,ms,s,mandh.Corresponds to the  --restart-delayoption ofdocker service create.Deprecated in 2.8, will be removed in 2.12. Use parameter  restart_config.delayinstead. | |||
| restart_policy_window 
                    raw
                                                                 | Restart policy evaluation window. Accepts a duration as an integer in nanoseconds or as a string in a format that look like:  5h34m56s,1m30setc. The supported units areus,ms,s,mandh.Corresponds to the  --restart-windowoption ofdocker service create.Deprecated in 2.8, will be removed in 2.12. Use parameter  restart_config.windowinstead. | |||
| rollback_config 
                    dictionary
                                                                 added in 2.8 | Configures how the service should be rolled back in case of a failing update. | |||
| delay 
                    string
                                                                 | Delay between task rollbacks. Accepts a string in a format that look like:  5h34m56s,1m30setc. The supported units areus,ms,s,mandh.Corresponds to the  --rollback-delayoption ofdocker service create.Requires API version >= 1.28. | |||
| failure_action 
                    string
                                                                 | 
 | Action to take in case of rollback failure. Corresponds to the  --rollback-failure-actionoption ofdocker service create.Requires API version >= 1.28. | ||
| max_failure_ratio 
                    float
                                                                 | Fraction of tasks that may fail during a rollback. Corresponds to the  --rollback-max-failure-ratiooption ofdocker service create.Requires API version >= 1.28. | |||
| monitor 
                    string
                                                                 | Duration after each task rollback to monitor for failure. Accepts a string in a format that look like:  5h34m56s,1m30setc. The supported units areus,ms,s,mandh.Corresponds to the  --rollback-monitoroption ofdocker service create.Requires API version >= 1.28. | |||
| order 
                    string
                                                                 | Specifies the order of operations during rollbacks. Corresponds to the  --rollback-orderoption ofdocker service create.Requires API version >= 1.29. | |||
| parallelism 
                    integer
                                                                 | The number of containers to rollback at a time. If set to 0, all containers rollback simultaneously. Corresponds to the  --rollback-parallelismoption ofdocker service create.Requires API version >= 1.28. | |||
| secrets 
                    list
                     / elements=dictionary                                             | List of dictionaries describing the service secrets. Corresponds to the  --secretoption ofdocker service create.Requires API version >= 1.25. | |||
| filename 
                    string
                                                                 | Name of the file containing the secret. Defaults to the secret_name if not specified. Corresponds to the  targetkey ofdocker service create --secret. | |||
| gid 
                    string
                                                                 | GID of the secret file's group. | |||
| mode 
                    integer
                                                                 | File access mode inside the container. Must be an octal number (like  0644or0444). | |||
| secret_id 
                    string
                                                                 | Secret's ID. | |||
| secret_name 
                    string
                                             / required                     | Secret's name as defined at its creation. | |||
| uid 
                    string
                                                                 | UID of the secret file's owner. | |||
| ssl_version 
                    string
                                                                 | Provide a valid SSL version number. Default value determined by ssl.py module. If the value is not specified in the task, the value of environment variable  DOCKER_SSL_VERSIONwill be used instead. | |||
| state 
                    string
                                                                 | 
 | absent- A service matching the specified name will be removed and have its tasks stopped.present- Asserts the existence of a service matching the name and provided configuration parameters. Unspecified configuration parameters will be set to docker defaults. | ||
| stop_grace_period 
                    string
                                                                 added in 2.8 | Time to wait before force killing a container. Accepts a duration as a string in a format that look like:  5h34m56s,1m30setc. The supported units areus,ms,s,mandh.Corresponds to the  --stop-grace-periodoption ofdocker service create. | |||
| stop_signal 
                    string
                                                                 added in 2.8 | Override default signal used to stop the container. Corresponds to the  --stop-signaloption ofdocker service create. | |||
| timeout 
                    integer
                                                                 | Default: 60 | The maximum amount of time in seconds to wait on a response from the API. If the value is not specified in the task, the value of environment variable  DOCKER_TIMEOUTwill be used instead. If the environment variable is not set, the default value will be used. | ||
| tls 
                    boolean
                                                                 | 
 | Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Note that if validate_certs is set to  yesas well, it will take precedence.If the value is not specified in the task, the value of environment variable  DOCKER_TLSwill be used instead. If the environment variable is not set, the default value will be used. | ||
| tls_hostname 
                    string
                                                                 | Default: "localhost" | When verifying the authenticity of the Docker Host server, provide the expected name of the server. If the value is not specified in the task, the value of environment variable  DOCKER_TLS_HOSTNAMEwill be used instead. If the environment variable is not set, the default value will be used. | ||
| tty 
                    boolean
                                                                 | 
 | Allocate a pseudo-TTY. Corresponds to the  --ttyoption ofdocker service create.Requires API version >= 1.25. | ||
| update_config 
                    dictionary
                                                                 added in 2.8 | Configures how the service should be updated. Useful for configuring rolling updates. | |||
| delay 
                    string
                                                                 | Rolling update delay. Accepts a string in a format that look like:  5h34m56s,1m30setc. The supported units areus,ms,s,mandh.Corresponds to the  --update-delayoption ofdocker service create. | |||
| failure_action 
                    string
                                                                 | 
 | Action to take in case of container failure. Corresponds to the  --update-failure-actionoption ofdocker service create.Usage of rollback requires API version >= 1.29. | ||
| max_failure_ratio 
                    float
                                                                 | Fraction of tasks that may fail during an update before the failure action is invoked. Corresponds to the  --update-max-failure-ratiooption ofdocker service create.Requires API version >= 1.25. | |||
| monitor 
                    string
                                                                 | Time to monitor updated tasks for failures. Accepts a string in a format that look like:  5h34m56s,1m30setc. The supported units areus,ms,s,mandh.Corresponds to the  --update-monitoroption ofdocker service create.Requires API version >= 1.25. | |||
| order 
                    string
                                                                 | Specifies the order of operations when rolling out an updated task. Corresponds to the  --update-orderoption ofdocker service create.Requires API version >= 1.29. | |||
| parallelism 
                    integer
                                                                 | Rolling update parallelism. Corresponds to the  --update-parallelismoption ofdocker service create. | |||
| update_delay 
                    raw
                                                                 | Rolling update delay. Accepts a duration as an integer in nanoseconds or as a string in a format that look like:  5h34m56s,1m30setc. The supported units areus,ms,s,mandh.Corresponds to the  --update-delayoption ofdocker service create.Before Ansible 2.8, the default value for this option was  10.Deprecated in 2.8, will be removed in 2.12. Use parameter  update_config.delayinstead. | |||
| update_failure_action 
                    string
                                                                 | 
 | Action to take in case of container failure. Corresponds to the  --update-failure-actionoption ofdocker service create.Usage of rollback requires API version >= 1.29. Deprecated in 2.8, will be removed in 2.12. Use parameter  update_config.failure_actioninstead. | ||
| update_max_failure_ratio 
                    float
                                                                 | Fraction of tasks that may fail during an update before the failure action is invoked. Corresponds to the  --update-max-failure-ratiooption ofdocker service create.Requires API version >= 1.25. Deprecated in 2.8, will be removed in 2.12. Use parameter  update_config.max_failure_ratioinstead. | |||
| update_monitor 
                    raw
                                                                 | Time to monitor updated tasks for failures. Accepts a duration as an integer in nanoseconds or as a string in a format that look like:  5h34m56s,1m30setc. The supported units areus,ms,s,mandh.Corresponds to the  --update-monitoroption ofdocker service create.Requires API version >= 1.25. Deprecated in 2.8, will be removed in 2.12. Use parameter  update_config.monitorinstead. | |||
| update_order 
                    string
                                                                 | 
 | Specifies the order of operations when rolling out an updated task. Corresponds to the  --update-orderoption ofdocker service create.Requires API version >= 1.29. Deprecated in 2.8, will be removed in 2.12. Use parameter  update_config.orderinstead. | ||
| update_parallelism 
                    integer
                                                                 | Rolling update parallelism. Corresponds to the  --update-parallelismoption ofdocker service create.Before Ansible 2.8, the default value for this option was  1.Deprecated in 2.8, will be removed in 2.12. Use parameter  update_config.parallelisminstead. | |||
| user 
                    string
                                                                 | Sets the username or UID used for the specified command. Before Ansible 2.8, the default value for this option was  root.The default has been removed so that the user defined in the image is used if no user is specified here. Corresponds to the  --useroption ofdocker service create. | |||
| validate_certs 
                    boolean
                                                                 | 
 | Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server. If the value is not specified in the task, the value of environment variable  DOCKER_TLS_VERIFYwill be used instead. If the environment variable is not set, the default value will be used.aliases: tls_verify | ||
| working_dir 
                    string
                                                                 added in 2.8 | Path to the working directory. Corresponds to the  --workdiroption ofdocker service create. | |||
Notes¶
Note
- Images will only resolve to the latest digest when using Docker API >= 1.30 and Docker SDK for Python >= 3.2.0. When using older versions use force_update: trueto trigger the swarm to resolve a new image.
- Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST,DOCKER_TLS_HOSTNAME,DOCKER_API_VERSION,DOCKER_CERT_PATH,DOCKER_SSL_VERSION,DOCKER_TLS,DOCKER_TLS_VERIFYandDOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.
- When connecting to Docker daemon with TLS, you might need to install additional Python packages. For the Docker SDK for Python, version 2.4 or newer, this can be done by installing docker[tls]with pip.
- Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions. In general, it will use $HOME/.docker/config.jsonif theDOCKER_CONFIGenvironment variable is not specified, and use$DOCKER_CONFIG/config.jsonotherwise.
Examples¶
- name: Set command and arguments
  docker_swarm_service:
    name: myservice
    image: alpine
    command: sleep
    args:
      - "3600"
- name: Set a bind mount
  docker_swarm_service:
    name: myservice
    image: alpine
    mounts:
      - source: /tmp/
        target: /remote_tmp/
        type: bind
- name: Set service labels
  docker_swarm_service:
    name: myservice
    image: alpine
    labels:
      com.example.description: "Accounting webapp"
      com.example.department: "Finance"
- name: Set environment variables
  docker_swarm_service:
    name: myservice
    image: alpine
    env:
      ENVVAR1: envvar1
      ENVVAR2: envvar2
    env_files:
      - envs/common.env
      - envs/apps/web.env
- name: Set fluentd logging
  docker_swarm_service:
    name: myservice
    image: alpine
    logging:
      driver: fluentd
      options:
        fluentd-address: "127.0.0.1:24224"
        fluentd-async-connect: "true"
        tag: myservice
- name: Set restart policies
  docker_swarm_service:
    name: myservice
    image: alpine
    restart_config:
      condition: on-failure
      delay: 5s
      max_attempts: 3
      window: 120s
- name: Set update config
  docker_swarm_service:
    name: myservice
    image: alpine
    update_config:
      parallelism: 2
      delay: 10s
      order: stop-first
- name: Set rollback config
  docker_swarm_service:
    name: myservice
    image: alpine
    update_config:
      failure_action: rollback
    rollback_config:
      parallelism: 2
      delay: 10s
      order: stop-first
- name: Set placement preferences
  docker_swarm_service:
    name: myservice
    image: alpine:edge
    placement:
      preferences:
        - spread: node.labels.mylabel
      constraints:
        - node.role == manager
        - engine.labels.operatingsystem == ubuntu 14.04
- name: Set configs
  docker_swarm_service:
    name: myservice
    image: alpine:edge
    configs:
      - config_name: myconfig_name
        filename: "/tmp/config.txt"
- name: Set networks
  docker_swarm_service:
    name: myservice
    image: alpine:edge
    networks:
      - mynetwork
- name: Set networks as a dictionary
  docker_swarm_service:
    name: myservice
    image: alpine:edge
    networks:
      - name: "mynetwork"
        aliases:
          - "mynetwork_alias"
        options:
          foo: bar
- name: Set secrets
  docker_swarm_service:
    name: myservice
    image: alpine:edge
    secrets:
      - secret_name: mysecret_name
        filename: "/run/secrets/secret.txt"
- name: Start service with healthcheck
  docker_swarm_service:
    name: myservice
    image: nginx:1.13
    healthcheck:
      # Check if nginx server is healthy by curl'ing the server.
      # If this fails or timeouts, the healthcheck fails.
      test: ["CMD", "curl", "--fail", "http://nginx.host.com"]
      interval: 1m30s
      timeout: 10s
      retries: 3
      start_period: 30s
- name: Configure service resources
  docker_swarm_service:
    name: myservice
    image: alpine:edge
    reservations:
      cpus: 0.25
      memory: 20M
    limits:
      cpus: 0.50
      memory: 50M
- name: Remove service
  docker_swarm_service:
    name: myservice
    state: absent
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
Status¶
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors¶
- Dario Zanzico (@dariko)
- Jason Witkowski (@jwitko)
- Hannes Ljungberg (@hannseman)
Hint
If you notice any issues in this documentation, you can edit this document to improve it.
