From c320caf2853cf72254a37fc7a81af1db41e1c2d8 Mon Sep 17 00:00:00 2001 From: Hiroaki Nakamura Date: Thu, 7 Jul 2016 00:34:51 +0900 Subject: [PATCH] Fix lxd_container and lxd_profile document to be rendered properly --- cloud/lxd/lxd_container.py | 87 ++++++++++++++++++-------------------- cloud/lxd/lxd_profile.py | 63 +++++++++++++-------------- 2 files changed, 69 insertions(+), 81 deletions(-) diff --git a/cloud/lxd/lxd_container.py b/cloud/lxd/lxd_container.py index 12a64775215..17a8a0fa233 100644 --- a/cloud/lxd/lxd_container.py +++ b/cloud/lxd/lxd_container.py @@ -19,7 +19,7 @@ # along with Ansible. If not, see . -DOCUMENTATION = """ +DOCUMENTATION = ''' --- module: lxd_container short_description: Manage LXD Containers @@ -35,17 +35,16 @@ options: architecture: description: - The archiecture for the container (e.g. "x86_64" or "i686"). - See https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1 + See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1) required: false config: description: - - > - The config for the container (e.g. {"limits.cpu": "2"}). - See https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1 + - 'The config for the container (e.g. {"limits.cpu": "2"}). + See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1)' - If the container already exists and its "config" value in metadata obtained from GET /1.0/containers/ - https://github.com/lxc/lxd/blob/master/doc/rest-api.md#10containersname + U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#10containersname) are different, they this module tries to apply the configurations. - The key starts with 'volatile.' are ignored for this comparison. - Not all config values are supported to apply the existing container. @@ -53,26 +52,24 @@ options: required: false devices: description: - - > - The devices for the container + - 'The devices for the container (e.g. { "rootfs": { "path": "/dev/kvm", "type": "unix-char" }). - See https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1 + See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1)' required: false ephemeral: description: - Whether or not the container is ephemeral (e.g. true or false). - See https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1 + See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1) required: false source: description: - - > - The source for the container + - 'The source for the container (e.g. { "type": "image", "mode": "pull", "server": "https://images.linuxcontainers.org", "protocol": "lxd", "alias": "ubuntu/xenial/amd64" }). - See https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1 + See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1)' required: false state: choices: @@ -95,14 +92,14 @@ options: default: 30 wait_for_ipv4_addresses: description: - - If this is true, the lxd_module waits until IPv4 addresses + - If this is true, the M(lxd_container) waits until IPv4 addresses are set to the all network interfaces in the container after starting or restarting. required: false default: false force_stop: description: - - If this is true, the lxd_module forces to stop the container + - If this is true, the M(lxd_container) forces to stop the container when it stops or restarts the container. required: false default: false @@ -115,21 +112,19 @@ options: description: - The client certificate key file path. required: false - default: > - '{}/.config/lxc/client.key'.format(os.environ['HOME']) + default: '"{}/.config/lxc/client.key" .format(os.environ["HOME"])' cert_file: description: - The client certificate file path. required: false - default: > - '{}/.config/lxc/client.crt'.format(os.environ['HOME']) + default: '"{}/.config/lxc/client.crt" .format(os.environ["HOME"])' trust_password: description: - The client trusted password. - You need to set this password on the LXD server before running this module using the following command. lxc config set core.trust_password - See https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/ + See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/) - If trust_password is set, this module send a request for authentication before sending any requests. required: false @@ -142,14 +137,14 @@ notes: 2.1, the later requires python to be installed in the container which can be done with the command module. - You can copy a file from the host to the container - with the Ansible `copy` and `template` module and the `lxd` connection plugin. + with the Ansible M(copy) and M(templater) module and the `lxd` connection plugin. See the example below. - You can copy a file in the creatd container to the localhost with `command=lxc file pull container_name/dir/filename filename`. See the first example below. -""" +''' -EXAMPLES = """ +EXAMPLES = ''' # An example for creating a Ubuntu container and install python - hosts: localhost connection: local @@ -225,32 +220,30 @@ EXAMPLES = """ src: /etc/hosts dest: /tmp/mycontainer-hosts flat: true -""" +''' -RETURN=""" -lxd_container: - description: container information - returned: success +RETURN=''' +addresses: + description: Mapping from the network device name to a list of IPv4 addresses in the container + returned: when state is started or restarted type: object - contains: - addresses: - description: Mapping from the network device name to a list of IPv4 addresses in the container - returned: when state is started or restarted - type: object - sample: {"eth0": ["10.155.92.191"]} - old_state: - description: The old state of the container - returned: when state is started or restarted - sample: "stopped" - logs: - descriptions: The logs of requests and responses. - returned: when ansible-playbook is invoked with -vvvv. - actions: - description: List of actions performed for the container. - returned: success - type: list - sample: ["create", "start"] -""" + sample: {"eth0": ["10.155.92.191"]} +old_state: + description: The old state of the container + returned: when state is started or restarted + type: string + sample: "stopped" +logs: + description: The logs of requests and responses. + returned: when ansible-playbook is invoked with -vvvv. + type: list + sample: "(too long to be placed here)" +actions: + description: List of actions performed for the container. + returned: success + type: list + sample: '["create", "start"]' +''' import os from ansible.modules.extras.cloud.lxd import LXDClient, LXDClientException diff --git a/cloud/lxd/lxd_profile.py b/cloud/lxd/lxd_profile.py index 8158a401643..2584908623c 100644 --- a/cloud/lxd/lxd_profile.py +++ b/cloud/lxd/lxd_profile.py @@ -19,7 +19,7 @@ # along with Ansible. If not, see . -DOCUMENTATION = """ +DOCUMENTATION = ''' --- module: lxd_profile short_description: Manage LXD profiles @@ -34,29 +34,27 @@ options: required: true config: description: - - > - The config for the container (e.g. {"limits.memory": "4GB"}). - See https://github.com/lxc/lxd/blob/master/doc/rest-api.md#patch-3 + - 'The config for the container (e.g. {"limits.memory": "4GB"}). + See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#patch-3)' - If the profile already exists and its "config" value in metadata obtained from GET /1.0/profiles/ - https://github.com/lxc/lxd/blob/master/doc/rest-api.md#get-19 + U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#get-19) are different, they this module tries to apply the configurations. - Not all config values are supported to apply the existing profile. Maybe you need to delete and recreate a profile. required: false devices: description: - - > - The devices for the profile + - 'The devices for the profile (e.g. {"rootfs": {"path": "/dev/kvm", "type": "unix-char"}). - See https://github.com/lxc/lxd/blob/master/doc/rest-api.md#patch-3 + See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#patch-3)' required: false new_name: description: - A new name of a profile. - If this parameter is specified a profile will be renamed to this name. - See https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-11 + See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-11) required: false state: choices: @@ -75,21 +73,19 @@ options: description: - The client certificate key file path. required: false - default: > - '{}/.config/lxc/client.key'.format(os.environ['HOME']) + default: '"{}/.config/lxc/client.key" .format(os.environ["HOME"])' cert_file: description: - The client certificate file path. required: false - default: > - '{}/.config/lxc/client.crt'.format(os.environ['HOME']) + default: '"{}/.config/lxc/client.crt" .format(os.environ["HOME"])' trust_password: description: - The client trusted password. - You need to set this password on the LXD server before running this module using the following command. lxc config set core.trust_password - See https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/ + See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/) - If trust_password is set, this module send a request for authentication before sending any requests. required: false @@ -97,9 +93,9 @@ notes: - Profiles must have a unique name. If you attempt to create a profile with a name that already existed in the users namespace the module will simply return as "unchanged". -""" +''' -EXAMPLES = """ +EXAMPLES = ''' # An example for creating a profile - hosts: localhost connection: local @@ -155,26 +151,25 @@ EXAMPLES = """ name: macvlan new_name: macvlan2 state: present -""" +''' -RETURN=""" -lxd_profile: - description: profile information +RETURN=''' +old_state: + description: The old state of the profile returned: success - type: object - contains: - old_state: - description: The old state of the profile - sample: "absent" - logs: - descriptions: The logs of requests and responses. - returned: when ansible-playbook is invoked with -vvvv. - actions: - description: List of actions performed for the profile. - returned: success - type: list - sample: ["create"] -""" + type: string + sample: "absent" +logs: + description: The logs of requests and responses. + returned: when ansible-playbook is invoked with -vvvv. + type: list + sample: "(too long to be placed here)" +actions: + description: List of actions performed for the profile. + returned: success + type: list + sample: '["create"]' +''' import os from ansible.modules.extras.cloud.lxd import LXDClient, LXDClientException