Documentation

docker_stack – docker stack module

New in version 2.8.

Synopsis

  • Manage docker stacks using the ‘docker stack’ command on the target node (see examples).

Requirements

The below requirements are needed on the host that executes this module.

  • jsondiff

  • pyyaml

Parameters

Parameter Choices/Defaults Comments
absent_retries
integer
Default:
0
If >0 and state==absent the module will retry up to absent_retries times to delete the stack until all the resources have been effectively deleted. If the last try still reports the stack as not completely removed the module will fail.
absent_retries_interval
integer
Default:
1
Interval in seconds between absent_retries
compose
list
Default:
[]
List of compose definitions. Any element may be a string referring to the path of the compose file on the target host or the YAML contents of a compose file nested as dictionary.
name
string / required
Stack name
prune
boolean
    Choices:
  • no ←
  • yes
If true will add the --prune option to the docker stack deploy command. This will have docker remove the services not present in the current stack definition.
resolve_image
string
    Choices:
  • always
  • changed
  • never
If set will add the --resolve-image option to the docker stack deploy command. This will have docker query the registry to resolve image digest and supported platforms. If not set, docker use "always" by default.
state
string
    Choices:
  • present ←
  • absent
Service state.
with_registry_auth
boolean
    Choices:
  • no ←
  • yes
If true will add the --with-registry-auth option to the docker stack deploy command. This will have docker send registry authentication details to Swarm agents.

Examples

-   name: deploy 'stack1' stack from file
    docker_stack:
        state: present
        name: stack1
        compose:
        -   /opt/stack.compose

-   name: deploy 'stack2' from base file and yaml overrides
    docker_stack:
        state: present
        name: stack2
        compose:
        -   /opt/stack.compose
        -   version: '3'
            services:
                web:
                    image: nginx:latest
                    environment:
                        ENVVAR: envvar

-   name: deprovision 'stack1'
    docker_stack:
        name: stack1
        state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
stack_spec_diff
dictionary
on change
dictionary containing the differences between the 'Spec' field of the stack services before and after applying the new stack definition.

Sample:
"stack_spec_diff": {'test_stack_test_service': {u'TaskTemplate': {u'ContainerSpec': {delete: [u'Env']}}}}


Status

Authors

  • Dario Zanzico (@dariko)

Hint

If you notice any issues in this documentation you can edit this document to improve it.