From 644057e9eccce89d4ce7d66bff70ff4fbb3d5669 Mon Sep 17 00:00:00 2001 From: Hannes Ljungberg Date: Mon, 14 Jan 2019 14:32:03 +0100 Subject: [PATCH] docker_swarm_service: Documentation fixes (#50861) * Describe labels and container_labels correctly * Clarify reserve_memory and limit_memory docs * Remove default from container_labels doc * Remove trailing whitespace * Document min api version for configs and secrets * Add changelog fragment * Specify type on labels and container_labels * Consolidate required API version descriptions * Update reserve and limit memory docs * Use correct power-of-two units * Remove description about limit_memory minimum 4mb --- ...cker_swarm_service-documentation-fixes.yml | 4 ++ .../cloud/docker/docker_swarm_service.py | 37 ++++++++++++------- 2 files changed, 28 insertions(+), 13 deletions(-) create mode 100644 changelogs/fragments/50861-docker_swarm_service-documentation-fixes.yml diff --git a/changelogs/fragments/50861-docker_swarm_service-documentation-fixes.yml b/changelogs/fragments/50861-docker_swarm_service-documentation-fixes.yml new file mode 100644 index 00000000000..05383b25214 --- /dev/null +++ b/changelogs/fragments/50861-docker_swarm_service-documentation-fixes.yml @@ -0,0 +1,4 @@ +bugfixes: + - "docker_swarm_service - Document minimal API version for ``configs`` and ``secrets``." + - "docker_swarm_service - Document ``labels`` and ``container_labels`` with correct type." + - "docker_swarm_service - Document ``limit_memory`` and ``reserve_memory`` correctly on how to specify sizes." diff --git a/lib/ansible/modules/cloud/docker/docker_swarm_service.py b/lib/ansible/modules/cloud/docker/docker_swarm_service.py index 3045fdbc6b4..ffcce8ac61c 100644 --- a/lib/ansible/modules/cloud/docker/docker_swarm_service.py +++ b/lib/ansible/modules/cloud/docker/docker_swarm_service.py @@ -53,7 +53,7 @@ options: description: - Container hostname - Maps docker service --hostname option. - - Requires api_version >= 1.25 + - Requires API version >= 1.25 tty: required: false type: bool @@ -61,28 +61,28 @@ options: description: - Allocate a pseudo-TTY - Maps docker service --tty option. - - Requires api_version >= 1.25 + - Requires API version >= 1.25 dns: required: false default: [] description: - List of custom DNS servers. - Maps docker service --dns option. - - Requires api_version >= 1.25 + - Requires API version >= 1.25 dns_search: required: false default: [] description: - List of custom DNS search domains. - Maps docker service --dns-search option. - - Requires api_version >= 1.25 + - Requires API version >= 1.25 dns_options: required: false default: [] description: - List of custom DNS options. - Maps docker service --dns-option option. - - Requires api_version >= 1.25 + - Requires API version >= 1.25 force_update: required: false type: bool @@ -90,18 +90,19 @@ options: description: - Force update even if no changes require it. - Maps to docker service update --force option. - - Requires api_version >= 1.25 + - Requires API version >= 1.25 labels: required: false + type: dict description: - - List of the service labels. + - Dictionary of key value pairs. - Maps docker service --label option. container_labels: required: false + type: dict description: - - List of the service containers labels. + - Dictionary of key value pairs. - Maps docker service --container-label option. - default: [] endpoint_mode: required: false description: @@ -143,13 +144,21 @@ options: required: false default: 0 description: - - Service memory limit in MB. 0 equals no limit. + - "Service memory limit (format: C([])). Number is a positive integer. + Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte), + C(T) (tebibyte), or C(P) (pebibyte)." + - 0 equals no limit. + - Omitting the unit defaults to bytes. - Maps docker service --limit-memory option. reserve_memory: required: false default: 0 description: - - Service memory reservation in MB. 0 equals no reservation. + - "Service memory reservation (format: C([])). Number is a positive integer. + Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte), + C(T) (tebibyte), or C(P) (pebibyte)." + - 0 equals no reservation. + - Omitting the unit defaults to bytes. - Maps docker service --reserve-memory option. mode: required: false @@ -170,6 +179,7 @@ options: - List of dictionaries describing the service secrets. - Every item must be a dictionary exposing the keys secret_id, secret_name, filename, uid (defaults to 0), gid (defaults to 0), mode (defaults to 0o444) - Maps docker service --secret option. + - Requires API version >= 1.25 default: [] configs: required: false @@ -177,6 +187,7 @@ options: - List of dictionaries describing the service configs. - Every item must be a dictionary exposing the keys config_id, config_name, filename, uid (defaults to 0), gid (defaults to 0), mode (defaults to 0o444) - Maps docker service --config option. + - Requires API version >= 1.30 default: null networks: required: false @@ -191,7 +202,7 @@ options: - List of dictionaries describing the service published ports. - Every item must be a dictionary exposing the keys published_port, target_port, protocol (defaults to 'tcp') - Only used with api_version >= 1.25 - - If api_version >= 1.32 and docker python library >= 3.0.0 attribute 'mode' can be set to 'ingress' or 'host' (default 'ingress'). + - If API version >= 1.32 and docker python library >= 3.0.0 attribute 'mode' can be set to 'ingress' or 'host' (default 'ingress'). replicas: required: false default: -1 @@ -267,7 +278,7 @@ options: description: - Specifies the order of operations when rolling out an updated task. - Maps to docker service --update-order - - Requires docker api version >= 1.29 + - Requires API version >= 1.29 user: required: false default: root