diff --git a/lib/ansible/modules/cloud/alicloud/ali_instance_facts.py b/lib/ansible/modules/cloud/alicloud/ali_instance_facts.py index 8636622c515..591ff887a61 100644 --- a/lib/ansible/modules/cloud/alicloud/ali_instance_facts.py +++ b/lib/ansible/modules/cloud/alicloud/ali_instance_facts.py @@ -72,15 +72,26 @@ EXAMPLES = ''' tasks: - name: Find all instances in the specified region ali_instance_facts: + alicloud_access_key: '{{ alicloud_access_key }}' + alicloud_secret_key: '{{ alicloud_secret_key }}' + alicloud_region: '{{ alicloud_region }}' register: all_instances + - name: Find all instances based on the specified ids ali_instance_facts: + alicloud_access_key: '{{ alicloud_access_key }}' + alicloud_secret_key: '{{ alicloud_secret_key }}' + alicloud_region: '{{ alicloud_region }}' instance_ids: - "i-35b333d9" - "i-ddav43kd" register: instances_by_ids + - name: Find all instances based on the specified names/name-prefixes ali_instance_facts: + alicloud_access_key: '{{ alicloud_access_key }}' + alicloud_secret_key: '{{ alicloud_secret_key }}' + alicloud_region: '{{ alicloud_region }}' instance_names: - "ecs_instance-1" - "ecs_instance_2" diff --git a/lib/ansible/modules/cloud/amazon/ec2.py b/lib/ansible/modules/cloud/amazon/ec2.py index c3b5a77fc3d..e75d7e37193 100644 --- a/lib/ansible/modules/cloud/amazon/ec2.py +++ b/lib/ansible/modules/cloud/amazon/ec2.py @@ -195,11 +195,11 @@ options: state: version_added: "1.3" description: - - create, terminate, start, stop or restart instances. - The state 'restarted' was added in 2.2 - required: false + - Create, terminate, start, stop or restart instances. The state 'restarted' was added in Ansible 2.2. + - When 'absent', I(instance_ids) is required. + - When 'running', 'stopped' and 'restarted', I(instance_ids) or I(instance_tags) is required. default: 'present' - choices: ['present', 'absent', 'running', 'restarted', 'stopped'] + choices: ['absent', 'present', 'restarted', 'running', 'stopped'] type: str volumes: version_added: "1.5" diff --git a/lib/ansible/modules/cloud/amazon/ec2_eip_facts.py b/lib/ansible/modules/cloud/amazon/ec2_eip_facts.py index 01e926a5d3b..0a1f5c06c39 100644 --- a/lib/ansible/modules/cloud/amazon/ec2_eip_facts.py +++ b/lib/ansible/modules/cloud/amazon/ec2_eip_facts.py @@ -52,6 +52,24 @@ EXAMPLES = ''' - i-987654321 register: my_vms_eips +# List all EIP addresses using the 'Name' tag as a filter. +- ec2_eip_facts: + filters: + tag:Name: www.example.com + register: my_vms_eips + +# List all EIP addresses using the Allocation-id as a filter +- ec2_eip_facts: + filters: + allocation-id: eipalloc-64de1b01 + register: my_vms_eips + +# Set the variable eip_alloc to the value of the first allocation_id +# and set the variable my_pub_ip to the value of the first public_ip +- set_fact: + eip_alloc: my_vms_eips.addresses[0].allocation_id + my_pub_ip: my_vms_eips.addresses[0].public_ip + ''' diff --git a/lib/ansible/modules/cloud/amazon/ecs_service.py b/lib/ansible/modules/cloud/amazon/ecs_service.py index 630d2b41e70..0cd23b992ec 100644 --- a/lib/ansible/modules/cloud/amazon/ecs_service.py +++ b/lib/ansible/modules/cloud/amazon/ecs_service.py @@ -160,6 +160,8 @@ extends_documentation_fragment: EXAMPLES = ''' # Note: These examples do not set authentication details, see the AWS Guide for details. + +# Basic provisioning example - ecs_service: state: present name: console-test-service @@ -167,12 +169,6 @@ EXAMPLES = ''' task_definition: 'new_cluster-task:1' desired_count: 0 -# Basic provisioning example -- ecs_service: - name: default - state: present - cluster: new_cluster - - name: create ECS service on VPC network ecs_service: state: present diff --git a/lib/ansible/modules/cloud/amazon/ecs_taskdefinition.py b/lib/ansible/modules/cloud/amazon/ecs_taskdefinition.py index 632686c2b0b..54c59b83483 100644 --- a/lib/ansible/modules/cloud/amazon/ecs_taskdefinition.py +++ b/lib/ansible/modules/cloud/amazon/ecs_taskdefinition.py @@ -120,8 +120,9 @@ EXAMPLES = ''' logConfiguration: logDriver: awslogs options: - awslogs-group: ecs + awslogs-group: /ecs/test-cluster-taskdef awslogs-region: us-west-2 + awslogs-stream-prefix: ecs - name: busybox command: - > diff --git a/lib/ansible/modules/cloud/google/gcp_container_cluster_facts.py b/lib/ansible/modules/cloud/google/gcp_container_cluster_facts.py index a19f87428cc..ea1f91bc675 100644 --- a/lib/ansible/modules/cloud/google/gcp_container_cluster_facts.py +++ b/lib/ansible/modules/cloud/google/gcp_container_cluster_facts.py @@ -58,7 +58,6 @@ EXAMPLES = ''' project: test_project auth_kind: serviceaccount service_account_file: "/tmp/auth.pem" - state: facts ''' RETURN = ''' diff --git a/lib/ansible/modules/cloud/hcloud/hcloud_server.py b/lib/ansible/modules/cloud/hcloud/hcloud_server.py index 5c4a92f1a19..b2bfe7d438a 100644 --- a/lib/ansible/modules/cloud/hcloud/hcloud_server.py +++ b/lib/ansible/modules/cloud/hcloud/hcloud_server.py @@ -46,7 +46,9 @@ options: type: str ssh_keys: description: - - List of SSH Keys Names + - List of SSH key names + - The key names correspond to the SSH keys configured for your + Hetzner Cloud account access. type: list volumes: description: @@ -117,7 +119,7 @@ EXAMPLES = """ image: ubuntu-18.04 location: fsn1 ssh_keys: - - my-ssh-key + - me@myorganisation state: present - name: Resize an existing server diff --git a/lib/ansible/modules/cloud/openstack/os_image.py b/lib/ansible/modules/cloud/openstack/os_image.py index fd4a36e1d59..b76992b9273 100644 --- a/lib/ansible/modules/cloud/openstack/os_image.py +++ b/lib/ansible/modules/cloud/openstack/os_image.py @@ -91,6 +91,8 @@ EXAMPLES = ''' username: admin password: passme project_name: admin + os_user_domain_name: Default + os_project_domain_name: Default name: cirros container_format: bare disk_format: qcow2 diff --git a/lib/ansible/modules/cloud/ovirt/ovirt_disk.py b/lib/ansible/modules/cloud/ovirt/ovirt_disk.py index 47a9199f711..62c4757f4b0 100644 --- a/lib/ansible/modules/cloud/ovirt/ovirt_disk.py +++ b/lib/ansible/modules/cloud/ovirt/ovirt_disk.py @@ -37,8 +37,8 @@ options: - "ID of the Virtual Machine to manage. Either C(vm_id) or C(vm_name) is required if C(state) is I(attached) or I(detached)." state: description: - - "Should the Virtual Machine disk be present/absent/attached/detached." - choices: ['present', 'absent', 'attached', 'detached'] + - "Should the Virtual Machine disk be present/absent/attached/detached/exported." + choices: ['present', 'absent', 'attached', 'detached', 'exported'] default: 'present' download_image_path: description: diff --git a/lib/ansible/modules/files/file.py b/lib/ansible/modules/files/file.py index 218051bb228..63d6abd4662 100644 --- a/lib/ansible/modules/files/file.py +++ b/lib/ansible/modules/files/file.py @@ -52,7 +52,8 @@ options: description: - Path of the file to link to. - This applies only to C(state=link) and C(state=hard). - - Will accept absolute, relative and non-existing paths. + - Will accept absolute and non-existing paths. + - Will accept relative paths unless state=hard. - Relative paths are relative to the file being created (C(path)) which is how the Unix command C(ln -s SRC DEST) treats relative paths. type: path diff --git a/lib/ansible/modules/monitoring/sensu_subscription.py b/lib/ansible/modules/monitoring/sensu_subscription.py index 3e3b55ae1d8..6921c15c536 100644 --- a/lib/ansible/modules/monitoring/sensu_subscription.py +++ b/lib/ansible/modules/monitoring/sensu_subscription.py @@ -49,7 +49,7 @@ author: Anders Ingemann (@andsens) RETURN = ''' reasons: - description: the reasons why the moule changed or did not change something + description: the reasons why the module changed or did not change something returned: success type: list sample: ["channel subscription was absent and state is `present'"] diff --git a/lib/ansible/modules/packaging/os/package_facts.py b/lib/ansible/modules/packaging/os/package_facts.py index 90aa208732e..e1e6fe5f9ab 100644 --- a/lib/ansible/modules/packaging/os/package_facts.py +++ b/lib/ansible/modules/packaging/os/package_facts.py @@ -44,12 +44,13 @@ author: ''' EXAMPLES = ''' -- name: get the rpm package facts +- name: Gather the rpm package facts package_facts: - manager: "auto" + manager: auto -- name: show them - debug: var=ansible_facts.packages +- name: Print the rpm package facts + debug: + var: ansible_facts.packages ''' diff --git a/lib/ansible/modules/system/java_keystore.py b/lib/ansible/modules/system/java_keystore.py index abd15ec00b3..51b4bd7c602 100644 --- a/lib/ansible/modules/system/java_keystore.py +++ b/lib/ansible/modules/system/java_keystore.py @@ -28,15 +28,15 @@ options: certificate: description: - Certificate that should be used to create the key store. - required: false + required: true private_key: description: - Private key that should be used to create the key store. - required: false + required: true password: description: - Password that should be used to secure the key store. - required: false + required: true dest: description: - Absolute path where the jks should be generated. diff --git a/lib/ansible/modules/system/setup.py b/lib/ansible/modules/system/setup.py index 77cbc57127e..54fc9ce1dd5 100644 --- a/lib/ansible/modules/system/setup.py +++ b/lib/ansible/modules/system/setup.py @@ -82,6 +82,7 @@ notes: output of your scripts. This option was added in Ansible 2.1. - This module is also supported for Windows targets. + - This module should be run with elevated priviliges on BSD systems to gather facts like ansible_product_version. author: - "Ansible Core Team" - "Michael DeHaan" diff --git a/lib/ansible/modules/utilities/logic/include_role.py b/lib/ansible/modules/utilities/logic/include_role.py index 2b887156874..722251cb8ed 100644 --- a/lib/ansible/modules/utilities/logic/include_role.py +++ b/lib/ansible/modules/utilities/logic/include_role.py @@ -19,16 +19,17 @@ author: Ansible Core Team (@ansible) module: include_role short_description: Load and execute a role description: - - Loads and executes a role as a task dynamically. - - This frees roles from the C(roles:) directive and allows them to be treated more as tasks. - - Unlike M(import_role), most keywords, including loop, with_items, and conditionals, apply to this statement. - - The do until loop is not supported on M(include_role). + - Dynamically loads and executes a specified role as a task. + - May be used only where Ansible tasks are allowed - inside C(pre_tasks), C(tasks), or C(post_tasks) playbook objects, or as a task inside a role. + - Task-level keywords, loops, and conditionals apply only to the C(include_role) statement itself. + - To apply keywords to the tasks within the role, pass them using the C(apply) option or use M(import_role) instead. + - Ignores some keywords, like C(until) and C(retries). - This module is also supported for Windows targets. version_added: "2.2" options: apply: description: - - Accepts a hash of task keywords (e.g. C(tags), C(become)) that will be applied to the tasks within the include. + - Accepts a hash of task keywords (e.g. C(tags), C(become)) that will be applied to all tasks within the included role. version_added: '2.7' name: description: diff --git a/lib/ansible/modules/windows/win_dns_record.py b/lib/ansible/modules/windows/win_dns_record.py index 6874a123681..0e499515ad2 100644 --- a/lib/ansible/modules/windows/win_dns_record.py +++ b/lib/ansible/modules/windows/win_dns_record.py @@ -71,17 +71,17 @@ options: EXAMPLES = r''' - name: Create database server alias win_dns_record: - name: db1 - type: CNAME - value: cgyl1404p.amer.example.com - zone: amer.example.com + name: "db1" + type: "CNAME" + value: "cgyl1404p.amer.example.com" + zone: "amer.example.com" - name: Remove static record win_dns_record: - name: db1 - type: A + name: "db1" + type: "A" state: absent - zone: amer.example.com + zone: "amer.example.com" ''' RETURN = r''' diff --git a/lib/ansible/modules/windows/win_domain_group_membership.py b/lib/ansible/modules/windows/win_domain_group_membership.py index 49e4fd4f3be..a8a30fb9b95 100644 --- a/lib/ansible/modules/windows/win_domain_group_membership.py +++ b/lib/ansible/modules/windows/win_domain_group_membership.py @@ -25,7 +25,8 @@ options: members: description: - A list of members to ensure are present/absent from the group. - - The given names must be a SmaAccountName of a user, group, service account, or computer + - The given names must be a SamAccountName of a user, group, service account, or computer. + - For computers, you must add "$" after the name; for example, to add "Mycomputer" to a group, use "Mycomputer$" as the member. type: list required: yes state: diff --git a/lib/ansible/playbook/attribute.py b/lib/ansible/playbook/attribute.py index 20370b9826e..50047c47211 100644 --- a/lib/ansible/playbook/attribute.py +++ b/lib/ansible/playbook/attribute.py @@ -52,7 +52,8 @@ class Attribute: :kwarg isa: The type of the attribute. Allowable values are a string representation of any yaml basic datatype, python class, or percent. (Enforced at post-validation time). - :kwarg private: (not used) + :kwarg private: Hides the attribute from being documented. + TODO: it should also should prevent it from being user settable :kwarg default: Default value if unspecified in the YAML document. :kwarg required: Whether or not the YAML document must contain this field. If the attribute is None when post-validated, an error will be raised. diff --git a/lib/ansible/plugins/doc_fragments/openstack.py b/lib/ansible/plugins/doc_fragments/openstack.py index 91f4985c6d0..3451c3f85fa 100644 --- a/lib/ansible/plugins/doc_fragments/openstack.py +++ b/lib/ansible/plugins/doc_fragments/openstack.py @@ -24,7 +24,8 @@ options: - Dictionary containing auth information as needed by the cloud's auth plugin strategy. For the default I(password) plugin, this would contain I(auth_url), I(username), I(password), I(project_name) and any - information about domains if the cloud supports them. For other plugins, + information about domains (for example, I(os_user_domain_name) or I(os_project_domain_name)) if the cloud supports them. + For other plugins, this param will need to contain whatever parameters that auth plugin requires. This parameter is not needed if a named cloud is provided or OpenStack OS_* environment variables are present. diff --git a/lib/ansible/plugins/lookup/template.py b/lib/ansible/plugins/lookup/template.py index a5b30b06261..6b00e8ebc8e 100644 --- a/lib/ansible/plugins/lookup/template.py +++ b/lib/ansible/plugins/lookup/template.py @@ -11,7 +11,7 @@ DOCUMENTATION = """ version_added: "0.9" short_description: retrieve contents of file after templating with Jinja2 description: - - this is mostly a noop, to be used as a with_list loop when you do not want the content transformed in any way. + - Returns a list of strings; for each template in the list of templates you pass in, returns a string containing the results of processing that template. options: _terms: description: list of files to template