Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docker_swarm_service: Documentation fixes #53479

Merged
merged 11 commits into from
Mar 7, 2019
Merged

docker_swarm_service: Documentation fixes #53479

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
736056e
Document and validate mode choices
hannseman Mar 7, 2019
2319cfd
Update examples
hannseman Mar 7, 2019
c8a26af
Test cpu float values
hannseman Mar 7, 2019
7a0b963
Test correct option
hannseman Mar 7, 2019
6aa1eb3
Fix module return sample
hannseman Mar 7, 2019
3160da9
Add secrets and user to module return value
hannseman Mar 7, 2019
51dabcc
Order options alphabetically
hannseman Mar 7, 2019
cee0ade
Add changelog
hannseman Mar 7, 2019
82c1b9b
yaml indentation
hannseman Mar 7, 2019
fe24a55
Revert "Order options alphabetically"
hannseman Mar 7, 2019
2a74f95
Be consistent with choices type
hannseman Mar 7, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 2 additions & 0 deletions changelogs/fragments/53479-docker_swarm_service-documentation-fixes.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
bugfixes:
- "docker_swarm_service - Validate choices for option ``mode``."
206 changes: 146 additions & 60 deletions lib/ansible/modules/cloud/docker/docker_swarm_service.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -306,9 +306,13 @@
mode:
description:
- Service replication mode.
- Service will be removed and recreated when changed.
- Corresponds to the C(--mode) option of C(docker service create).
type: str
default: replicated
choices:
- replicated
- global
mounts:
description:
- List of dictionaries describing the service mounts.
Expand Down Expand Up @@ -461,7 +465,6 @@
mode:
description:
- What publish mode to use.
- Service will be removed and recreated when changed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this no longer true for publish mode?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was never true. In #52634 I added that string to the wrong mode-option.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's supposed to be documented on the actual mode-option and not publish.mode.

- Requires API version >= 1.32.
type: str
choices:
Expand Down Expand Up @@ -670,79 +673,121 @@
returned: always
type: dict
description:
- Dictionary of variables representing the current state of the service.
Matches the module parameters format.
- Note that facts are not part of registered vars but accessible directly.
- Note that before Ansible 2.7.9, the return variable was documented as C(ansible_swarm_service),
while the module actually returned a variable called C(ansible_docker_service). The variable
was renamed to C(swarm_service) in both code and documentation for Ansible 2.7.9 and Ansible 2.8.0.
In Ansible 2.7.x, the old name C(ansible_docker_service) can still be used.
- Dictionary of variables representing the current state of the service.
Matches the module parameters format.
- Note that facts are not part of registered vars but accessible directly.
- Note that before Ansible 2.7.9, the return variable was documented as C(ansible_swarm_service),
while the module actually returned a variable called C(ansible_docker_service). The variable
was renamed to C(swarm_service) in both code and documentation for Ansible 2.7.9 and Ansible 2.8.0.
In Ansible 2.7.x, the old name C(ansible_docker_service) can still be used.
sample: '{
"args": [
"sleep",
"3600"
],
"constraints": [],
"container_labels": {},
"endpoint_mode": "vip",
"command": [
"sleep"
],
"configs": null,
"constraints": [
"node.role == manager",
"engine.labels.operatingsystem == ubuntu 14.04"
],
"container_labels": null,
"dns": null,
"dns_options": null,
"dns_search": null,
"endpoint_mode": null,
"env": [
"ENVVAR1=envvar1"
"ENVVAR1=envvar1",
"ENVVAR2=envvar2"
],
"force_update": False,
"image": "alpine",
"labels": {},
"limit_cpu": 0.0,
"limit_memory": 0,
"log_driver": "json-file",
"log_driver_options": {},
"force_update": null,
"groups": null,
"healthcheck": {
"interval": 90000000000,
"retries": 3,
"start_period": 30000000000,
"test": [
"CMD",
"curl",
"--fail",
"http://nginx.host.com"
],
"timeout": 10000000000
},
"healthcheck_disabled": false,
"hostname": null,
"hosts": null,
"image": "alpine:latest@sha256:b3dbf31b77fd99d9c08f780ce6f5282aba076d70a513a8be859d8d3a4d0c92b8",
"labels": {
"com.example.department": "Finance",
"com.example.description": "Accounting webapp"
},
"limit_cpu": 0.5,
"limit_memory": 52428800,
"log_driver": "fluentd",
"log_driver_options": {
"fluentd-address": "127.0.0.1:24224",
"fluentd-async-connect": "true",
"tag": "myservice"
},
"mode": "replicated",
"mounts": [
{
"readonly": false,
"source": "/tmp/",
"target": "/remote_tmp/",
"type": "bind"
}
],
"secrets": [],
"configs": [],
"networks": [],
"publish": [],
"networks": null,
"placement_preferences": [
{
"spread": "node.labels.mylabel"
}
],
"publish": null,
"replicas": 1,
"reserve_cpu": 0.0,
"reserve_memory": 0,
"restart_policy": "any",
"restart_policy_attempts": 5,
"restart_policy_delay": 0,
"restart_policy_window": 30,
"update_delay": 10,
"update_parallelism": 1,
"update_failure_action": "continue",
"update_monitor": 5000000000
"update_max_failure_ratio": 0,
"update_order": "stop-first"
"reserve_cpu": 0.25,
"reserve_memory": 20971520,
"restart_policy": "on-failure",
"restart_policy_attempts": 3,
"restart_policy_delay": 5000000000,
"restart_policy_window": 120000000000,
"secrets": null,
"stop_grace_period": null,
"stop_signal": null,
"tty": null,
"update_delay": 10000000000,
"update_failure_action": null,
"update_max_failure_ratio": null,
"update_monitor": null,
"update_order": "stop-first",
"update_parallelism": 2,
"user": null,
"working_dir": null
}'
changes:
returned: always
description:
- List of changed service attributes if a service has been altered,
[] otherwise
- List of changed service attributes if a service has been altered, [] otherwise.
type: list
sample: ['container_labels', 'replicas']
rebuilt:
returned: always
description:
- True if the service has been recreated (removed and created)
- True if the service has been recreated (removed and created)
type: bool
sample: True
'''

EXAMPLES = '''
- name: Set arguments
- name: Set command and arguments
docker_swarm_service:
name: myservice
image: alpine
command: sleep
args:
- "sleep"
- "3600"

- name: Set a bind mount
Expand All @@ -754,41 +799,65 @@
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"
ENVVAR1: envvar1
ENVVAR2: envvar2
env_files:
- envs/common.env
- envs/apps/web.env

- name: Set fluentd logging
docker_swarm_service:
name: myservice
image: alpine
log_driver: fluentd
log_driver_options:
fluentd-address: "127.0.0.1:24224"
fluentd-async-connect: true
tag: myservice
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: any
max_attempts: 5
condition: on-failure
delay: 5s
window: 30s
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 placement preferences
docker_swarm_service:
name: myservice
image: alpine:edge
placement:
preferences:
- spread: "node.labels.mylabel"
- spread: node.labels.mylabel
constraints:
- node.role == manager
- engine.labels.operatingsystem == ubuntu 14.04

- name: Set configs
docker_swarm_service:
Expand All @@ -815,11 +884,6 @@
secret_name: mysecret_name
filename: "/run/secrets/secret.txt"

- name: Remove service
docker_swarm_service:
name: myservice
state: absent

- name: Start service with healthcheck
docker_swarm_service:
name: myservice
Expand All @@ -832,6 +896,22 @@
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
'''

import shlex
Expand Down Expand Up @@ -1018,6 +1098,7 @@ def get_facts(self):
'replicas': self.replicas,
'endpoint_mode': self.endpoint_mode,
'restart_policy': self.restart_policy,
'secrets': self.secrets,
'stop_grace_period': self.stop_grace_period,
'stop_signal': self.stop_signal,
'limit_cpu': self.limit_cpu,
Expand All @@ -1033,6 +1114,7 @@ def get_facts(self):
'update_monitor': self.update_monitor,
'update_max_failure_ratio': self.update_max_failure_ratio,
'update_order': self.update_order,
'user': self.user,
'working_dir': self.working_dir,
}

Expand Down Expand Up @@ -2123,8 +2205,8 @@ def main():
publish=dict(type='list', elements='dict', options=dict(
published_port=dict(type='int', required=True),
target_port=dict(type='int', required=True),
protocol=dict(type='str', default='tcp', choices=('tcp', 'udp')),
mode=dict(type='str', choices=('ingress', 'host')),
protocol=dict(type='str', default='tcp', choices=['tcp', 'udp']),
mode=dict(type='str', choices=['ingress', 'host']),
)),
placement=dict(type='dict', options=dict(
constraints=dict(type='list'),
Expand All @@ -2146,7 +2228,11 @@ def main():
hosts=dict(type='dict'),
labels=dict(type='dict'),
container_labels=dict(type='dict'),
mode=dict(type='str', default='replicated'),
mode=dict(
type='str',
default='replicated',
choices=['replicated', 'global']
),
replicas=dict(type='int', default=-1),
endpoint_mode=dict(type='str', choices=['vip', 'dnsrr']),
stop_grace_period=dict(type='str'),
Expand Down
4 changes: 2 additions & 2 deletions test/integration/targets/docker_swarm_service/tasks/tests/options.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1106,7 +1106,7 @@
image: alpine:3.8
resolve_image: no
command: '/bin/sh -v -c "sleep 10m"'
labels: {}
healthcheck: {}
register: healthcheck_8
ignore_errors: yes

Expand All @@ -1116,7 +1116,7 @@
image: alpine:3.8
resolve_image: no
command: '/bin/sh -v -c "sleep 10m"'
labels: {}
healthcheck: {}
register: healthcheck_9
ignore_errors: yes

Expand Down
4 changes: 2 additions & 2 deletions test/integration/targets/docker_swarm_service/tasks/tests/resources.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@
resolve_image: no
command: '/bin/sh -v -c "sleep 10m"'
limits:
cpus: 2
cpus: 0.5
register: limit_cpu_3

- name: cleanup
Expand Down Expand Up @@ -159,7 +159,7 @@
resolve_image: no
command: '/bin/sh -v -c "sleep 10m"'
reservations:
cpus: 2
cpus: 0.5
register: reserve_cpu_3

- name: cleanup
Expand Down
2 changes: 2 additions & 0 deletions test/integration/targets/docker_swarm_service/vars/main.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ service_expected_output:
mode: global
mounts: null
networks: null
secrets: null
stop_grace_period: null
stop_signal: null
placement_preferences: null
Expand All @@ -46,4 +47,5 @@ service_expected_output:
update_monitor: null
update_order: null
update_parallelism: null
user: null
working_dir: null