ansible / ansible.builtin / v2.9.24 / module / docker_swarm Manage Swarm cluster | "added in version" 2.7 of ansible.builtin" Authors: Thierry Bouvet (@tbouvet), Piotr Wojciechowski (@WojciechowskiPiotr) preview | supported by communityansible.builtin.docker_swarm (v2.9.24) — module
pip
Install with pip install ansible==2.9.24
Create a new Swarm cluster.
Add/Remove nodes or managers to an existing cluster.
- name: Init a new swarm with default parameters docker_swarm: state: present
- name: Update swarm configuration docker_swarm: state: present election_tick: 5
- name: Add nodes docker_swarm: state: join advertise_addr: 192.168.1.2 join_token: SWMTKN-1--xxxxx remote_addrs: [ '192.168.1.1:2377' ]
- name: Leave swarm for a node docker_swarm: state: absent
- name: Remove a swarm manager docker_swarm: state: absent force: true
- name: Remove node from swarm docker_swarm: state: remove node_id: mynode
- name: Inspect swarm docker_swarm: state: inspect register: swarm_info
tls: default: false description: - Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Note that if I(validate_certs) is set to C(yes) as well, it will take precedence. - If the value is not specified in the task, the value of environment variable C(DOCKER_TLS) will be used instead. If the environment variable is not set, the default value will be used. type: bool name: description: - The name of the swarm. type: str debug: default: false description: - Debug mode type: bool force: default: false description: - Use with state C(present) to force creating a new Swarm, even if already part of one. - Use with state C(absent) to Leave the swarm even if this node is a manager. type: bool state: choices: - present - join - absent - remove - inspect default: present description: - Set to C(present), to create/update a new cluster. - Set to C(join), to join an existing cluster. - Set to C(absent), to leave an existing cluster. - Set to C(remove), to remove an absent node from the cluster. Note that removing requires Docker SDK for Python >= 2.4.0. - Set to C(inspect) to display swarm informations. type: str labels: description: - User-defined key/value metadata. - Label operations in this module apply to the docker swarm cluster. Use M(docker_node) module to add/modify/remove swarm node labels. - Requires API version >= 1.32. type: dict ca_cert: aliases: - tls_ca_cert - cacert_path description: - 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 C(DOCKER_CERT_PATH) is set, the file C(ca.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used. type: path node_id: description: - Swarm id of the node to remove. - Used with I(state=remove). type: str timeout: default: 60 description: - 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 C(DOCKER_TIMEOUT) will be used instead. If the environment variable is not set, the default value will be used. type: int client_key: aliases: - tls_client_key - key_path description: - Path to the client's TLS key file. - If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set, the file C(key.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used. type: path join_token: description: - Swarm token used to join a swarm cluster. - Used with I(state=join). - If this value is specified, the corresponding value in the return values will be censored by Ansible. This is a side-effect of this value not being logged. type: str api_version: aliases: - docker_api_version default: auto description: - 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 C(DOCKER_API_VERSION) will be used instead. If the environment variable is not set, the default value will be used. type: str client_cert: aliases: - tls_client_cert - cert_path description: - Path to the client's TLS certificate file. - If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set, the file C(cert.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used. type: path docker_host: aliases: - docker_url default: unix://var/run/docker.sock description: - 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, C(tcp://192.0.2.23:2376). If TLS is used to encrypt the connection, the module will automatically replace C(tcp) in the connection URL with C(https). - If the value is not specified in the task, the value of environment variable C(DOCKER_HOST) will be used instead. If the environment variable is not set, the default value will be used. type: str listen_addr: default: 0.0.0.0:2377 description: - Listen address used for inter-manager communication. - This can either be an address/port combination in the form C(192.168.1.1:4567), or an interface followed by a port number, like C(eth0:4567). - If the port number is omitted, the default swarm listening port is used. - Only used when swarm is initialised or joined. Because of this it's not considered for idempotency checking. type: str ssl_version: description: - 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 C(DOCKER_SSL_VERSION) will be used instead. type: str subnet_size: description: - Default address pool subnet mask length. - Only used when swarm is initialised. Because of this it's not considered for idempotency checking. - Requires API version >= 1.39. type: int version_added: '2.8' version_added_collection: ansible.builtin remote_addrs: description: - Remote address of one or more manager nodes of an existing Swarm to connect to. - Used with I(state=join). elements: str type: list tls_hostname: default: localhost description: - 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 C(DOCKER_TLS_HOSTNAME) will be used instead. If the environment variable is not set, the default value will be used. type: str election_tick: description: - Amount of ticks (in seconds) needed without a leader to trigger a new election. - Docker default value is C(10s). type: int advertise_addr: description: - Externally reachable address advertised to other nodes. - This can either be an address/port combination in the form C(192.168.1.1:4567), or an interface followed by a port number, like C(eth0:4567). - If the port number is omitted, the port number from the listen address is used. - If I(advertise_addr) is not specified, it will be automatically detected when possible. - Only used when swarm is initialised or joined. Because of this it's not considered for idempotency checking. type: str heartbeat_tick: description: - Amount of ticks (in seconds) between each heartbeat. - Docker default value is C(1s). type: int signing_ca_key: description: - The desired signing CA key for all swarm node TLS leaf certificates, in PEM format. - This must not be a path to a key, but the contents of the key. - Requires API version >= 1.30. type: str use_ssh_client: default: false description: - For SSH transports, use the C(ssh) CLI tool instead of paramiko. - Requires Docker SDK for Python 4.4.0 or newer. type: bool version_added: 1.5.0 version_added_collection: community.docker validate_certs: aliases: - tls_verify default: false description: - 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 C(DOCKER_TLS_VERIFY) will be used instead. If the environment variable is not set, the default value will be used. type: bool ca_force_rotate: description: - An integer whose purpose is to force swarm to generate a new signing CA certificate and key, if none have been specified. - Docker default value is C(0). - Requires API version >= 1.30. type: int signing_ca_cert: description: - The desired signing CA certificate for all swarm node TLS leaf certificates, in PEM format. - This must not be a path to a certificate, but the contents of the certificate. - Requires API version >= 1.30. type: str node_cert_expiry: description: - Automatic expiry for nodes certificates. - Docker default value is C(3months). type: int autolock_managers: description: - If set, generate a key and use it to lock data stored on the managers. - Docker default value is C(no). - M(docker_swarm_info) can be used to retrieve the unlock key. type: bool default_addr_pool: description: - Default address pool in CIDR format. - Only used when swarm is initialised. Because of this it's not considered for idempotency checking. - Requires API version >= 1.39. elements: str type: list version_added: '2.8' version_added_collection: ansible.builtin snapshot_interval: description: - Number of logs entries between snapshot. - Docker default value is C(10000). type: int keep_old_snapshots: description: - Number of snapshots to keep beyond the current snapshot. - Docker default value is C(0). type: int rotate_worker_token: default: false description: Rotate the worker join token. type: bool rotate_manager_token: default: false description: Rotate the manager join token. type: bool dispatcher_heartbeat_period: description: - The delay for an agent to send a heartbeat to the dispatcher. - Docker default value is C(5s). type: int task_history_retention_limit: description: - Maximum number of tasks history stored. - Docker default value is C(5). type: int log_entries_for_slow_followers: description: - Number of log entries to keep around to sync up slow followers after a snapshot is created. type: int
actions: description: Provides the actions done on the swarm. elements: str example: '[''This cluster is already a swarm cluster'']' returned: when action failed. type: list swarm_facts: contains: JoinTokens: contains: Manager: description: - Token to join the cluster as a new *manager* node. - B(Note:) if this value has been specified as I(join_token), the value here will not be the token, but C(VALUE_SPECIFIED_IN_NO_LOG_PARAMETER). If you pass I(join_token), make sure your playbook/role does not depend on this return value! example: SWMTKN-1--xxxxx returned: success type: str Worker: description: - Token to join the cluster as a new *worker* node. - B(Note:) if this value has been specified as I(join_token), the value here will not be the token, but C(VALUE_SPECIFIED_IN_NO_LOG_PARAMETER). If you pass I(join_token), make sure your playbook/role does not depend on this return value! example: SWMTKN-1--xxxxx returned: success type: str description: Tokens to connect to the Swarm. returned: success type: dict UnlockKey: description: The swarm unlock-key if I(autolock_managers) is C(true). example: SWMKEY-1-xxx returned: on success if I(autolock_managers) is C(true) and swarm is initialised, or if I(autolock_managers) has changed. type: str description: Informations about swarm. returned: success type: dict