1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00

docker_swarm_facts: New module to retrieve Docker Swarm information (#50622)

* docker_swarm_facts: PR cleanup after rebasing

* docker_swarm_facts: Adding the features similar to docker_host_facts

* docker_swarm_facts: Minor documentation and documentation updates

* docker_swarm_facts: Minor documentation and documentation adjustments to changes in #51700

* docker_swarm_facts: Using AnsibleDockerSwarmClient class method to fail module if not run on swarm manager
module_utils\docker\swarm.py: Adjustment of error message to me bore descriptive if module fails because it is not run on swarm manager node
This commit is contained in:
Piotr Wojciechowski 2019-02-12 06:59:31 +01:00 committed by ansibot
parent ea72f7001c
commit 42f20091dd
2 changed files with 308 additions and 1 deletions

View file

@ -92,7 +92,7 @@ class AnsibleDockerSwarmClient(AnsibleDockerClient):
If host is not a swarm manager then Ansible task on this host should end with 'failed' state
"""
if not self.check_if_swarm_manager():
self.fail(msg="This node is not a manager.")
self.fail(msg="Error running docker swarm module: must run on swarm manager node")
def check_if_swarm_worker(self):
"""
@ -216,3 +216,6 @@ class AnsibleDockerSwarmClient(AnsibleDockerClient):
return None
return nodes_list
def get_node_name_by_id(self, nodeid):
return self.get_node_inspect(nodeid)['Description']['Hostname']

View file

@ -0,0 +1,304 @@
#!/usr/bin/python
#
# (c) 2019 Piotr Wojciechowski <piotr@it-playground.pl>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'community'}
DOCUMENTATION = '''
---
module: docker_swarm_facts
short_description: Retrieves facts about Docker Swarm cluster.
description:
- Retrieves facts about a Docker Swarm.
- Returns lists of swarm objects names for the services - nodes, services, tasks.
- The output differs depending on API version available on docker host.
- Must be run on Swarm Manager node otherwise module fails with error message.
version_added: "2.8"
author:
- Piotr Wojciechowski (@wojciechowskipiotr)
options:
nodes:
description:
- Whether to list swarm nodes.
type: bool
default: no
nodes_filters:
description:
- A dictionary of filter values used for selecting nodes to list.
- "For example, C(name: mynode)."
- See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/node_ls/#filtering)
for more information on possible filters.
type: dict
services:
description:
- Whether to list swarm services.
type: bool
default: no
services_filters:
description:
- A dictionary of filter values used for selecting services to list.
- "For example, C(name: myservice)."
- See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/service_ls/#filtering)
for more information on possible filters.
type: dict
tasks:
description:
- Whether to list containers.
type: bool
default: no
tasks_filters:
description:
- A dictionary of filter values used for selecting tasks to list.
- "For example, C(node: mynode-1)."
- See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/service_ps/#filtering)
for more information on possible filters.
type: dict
verbose_output:
description:
- When set to C(yes) and I(nodes), I(services) or I(tasks) is set to C(yes)
then output will contain verbose information about objects matching the full output of API method.
For details see the documentation of your version of Docker API at U(https://docs.docker.com/engine/api/).
- The verbose output in this module contains only subset of information returned by I(_facts) module
for each type of the objects.
type: bool
default: no
extends_documentation_fragment:
- docker
- docker.docker_py_1_documentation
requirements:
- "docker-py >= 1.10.0"
- "Docker API >= 1.24"
'''
EXAMPLES = '''
- name: Get info on Docker Swarm
docker_swarm_facts:
register: result
- name: Get info on Docker Swarm and list of registered nodes
docker_swarm_facts:
nodes: yes
register: result
- name: Get info on Docker Swarm and extended list of registered nodes
docker_swarm_facts:
nodes: yes
verbose_output: yes
register: result
- name: Get info on Docker Swarm and filtered list of registered nodes
docker_swarm_facts:
nodes: yes
nodes_filter:
name: mynode
register: result
- debug:
var: result.docker_swarm_facts
'''
RETURN = '''
docker_swarm_facts:
description:
- Facts representing the basic state of the docker Swarm cluster.
- Contains tokens to connect to the Swarm
returned: always
type: dict
docker_nodes_list:
description:
- List of dict objects containing the basic information about each volume.
Keys matches the C(docker node ls) output unless I(verbose_output=yes).
See description for I(verbose_output).
returned: When I(nodes) is C(yes)
type: list
docker_services_list:
description:
- List of dict objects containing the basic information about each volume.
Keys matches the C(docker service ls) output unless I(verbose_output=yes).
See description for I(verbose_output).
returned: When I(services) is C(yes)
type: list
docker_tasks_list:
description:
- List of dict objects containing the basic information about each volume.
Keys matches the C(docker service ps) output unless I(verbose_output=yes).
See description for I(verbose_output).
returned: When I(tasks) is C(yes)
type: list
'''
try:
from docker.errors import APIError, NotFound
except ImportError:
# missing docker-py handled in ansible.module_utils.docker_common
pass
from ansible.module_utils._text import to_native
from ansible.module_utils.docker.swarm import AnsibleDockerSwarmClient
from ansible.module_utils.docker.common import DockerBaseClass, clean_dict_booleans_for_docker_api
class DockerSwarmManager(DockerBaseClass):
def __init__(self, client, results):
super(DockerSwarmManager, self).__init__()
self.client = client
self.results = results
self.verbose_output = self.client.module.params['verbose_output']
listed_objects = ['tasks', 'services', 'nodes']
self.client.fail_task_if_not_swarm_manager()
self.results['docker_swarm_facts'] = self.get_docker_swarm_facts()
for docker_object in listed_objects:
if self.client.module.params[docker_object]:
returned_name = "docker_" + docker_object + "_list"
filter_name = docker_object + "_filters"
filters = clean_dict_booleans_for_docker_api(client.module.params.get(filter_name))
self.results[returned_name] = self.get_docker_items_list(docker_object, filters)
def get_docker_swarm_facts(self):
try:
return self.client.inspect_swarm()
except APIError as exc:
self.client.fail_json(msg="Error inspecting docker swarm: %s" % to_native(exc))
def get_docker_items_list(self, docker_object=None, filters=None):
items = None
items_list = []
try:
if docker_object == 'nodes':
items = self.client.nodes(filters=filters)
elif docker_object == 'tasks':
items = self.client.tasks(filters=filters)
elif docker_object == 'services':
items = self.client.services(filters=filters)
except APIError as exc:
self.client.fail_json(msg="Error inspecting docker swarm for object '%s': %s" %
(docker_object, to_native(exc)))
if self.verbose_output:
return items
for item in items:
item_record = dict()
if docker_object == 'nodes':
item_record = self.get_essential_facts_nodes(item)
elif docker_object == 'tasks':
item_record = self.get_essential_facts_tasks(item)
elif docker_object == 'services':
item_record = self.get_essential_facts_services(item)
if item_record['Mode'] == 'Global':
item_record['Replicas'] = len(items)
items_list.append(item_record)
return items_list
@staticmethod
def get_essential_facts_nodes(item):
object_essentials = dict()
object_essentials['ID'] = item.get('ID')
object_essentials['Hostname'] = item['Description']['Hostname']
object_essentials['Status'] = item['Status']['State']
object_essentials['Availability'] = item['Spec']['Availability']
if 'ManagerStatus' in item:
object_essentials['ManagerStatus'] = item['ManagerStatus']['Reachability']
if 'Leader' in item['ManagerStatus'] and item['ManagerStatus']['Leader'] is True:
object_essentials['ManagerStatus'] = "Leader"
else:
object_essentials['ManagerStatus'] = None
object_essentials['EngineVersion'] = item['Description']['Engine']['EngineVersion']
return object_essentials
def get_essential_facts_tasks(self, item):
object_essentials = dict()
object_essentials['ID'] = item['ID']
# Returning container ID to not trigger another connection to host
# Container ID is sufficient to get extended info in other tasks
object_essentials['ContainerID'] = item['Status']['ContainerStatus']['ContainerID']
object_essentials['Image'] = item['Spec']['ContainerSpec']['Image']
object_essentials['Node'] = self.client.get_node_name_by_id(item['NodeID'])
object_essentials['DesiredState'] = item['DesiredState']
object_essentials['CurrentState'] = item['Status']['State']
if 'Err' in item['Status']:
object_essentials['Error'] = item['Status']['Err']
else:
object_essentials['Error'] = None
return object_essentials
@staticmethod
def get_essential_facts_services(item):
object_essentials = dict()
object_essentials['ID'] = item['ID']
object_essentials['Name'] = item['Spec']['Name']
if 'Replicated' in item['Spec']['Mode']:
object_essentials['Mode'] = "Replicated"
object_essentials['Replicas'] = item['Spec']['Mode']['Replicated']['Replicas']
elif 'Global' in item['Spec']['Mode']:
object_essentials['Mode'] = "Global"
# Number of replicas have to be updated in calling method or may be left as None
object_essentials['Replicas'] = None
object_essentials['Image'] = item['Spec']['TaskTemplate']['ContainerSpec']['Image']
if 'Ports' in item['Spec']['EndpointSpec']:
object_essentials['Ports'] = item['Spec']['EndpointSpec']['Ports']
else:
object_essentials['Ports'] = []
return object_essentials
def main():
argument_spec = dict(
nodes=dict(type='bool', default=False),
nodes_filters=dict(type='dict'),
tasks=dict(type='bool', default=False),
tasks_filters=dict(type='dict'),
services=dict(type='bool', default=False),
services_filters=dict(type='dict'),
verbose_output=dict(type='bool', default=False),
)
client = AnsibleDockerSwarmClient(
argument_spec=argument_spec,
supports_check_mode=True,
min_docker_version='1.10.0',
min_docker_api_version='1.24',
)
results = dict(
changed=False,
docker_swarm_facts=[],
)
DockerSwarmManager(client, results)
client.module.exit_json(**results)
if __name__ == '__main__':
main()