diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-14 20:03:01 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-14 20:03:01 +0000 |
| commit | a453ac31f3428614cceb99027f8efbdb9258a40b (patch) | |
| tree | f61f87408f32a8511cbd91799f9cececb53e0374 /collections-debian-merged/ansible_collections/amazon/aws/docs | |
| parent | Initial commit. (diff) | |
| download | ansible-a453ac31f3428614cceb99027f8efbdb9258a40b.tar.xz ansible-a453ac31f3428614cceb99027f8efbdb9258a40b.zip | |
Adding upstream version 2.10.7+merged+base+2.10.8+dfsg.upstream/2.10.7+merged+base+2.10.8+dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'collections-debian-merged/ansible_collections/amazon/aws/docs')
34 files changed, 21804 insertions, 0 deletions
diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_account_attribute_lookup.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_account_attribute_lookup.rst new file mode 100644 index 00000000..45f0a9c3 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_account_attribute_lookup.rst @@ -0,0 +1,236 @@ +.. _amazon.aws.aws_account_attribute_lookup: + + +******************************** +amazon.aws.aws_account_attribute +******************************** + +**Look up AWS account attributes.** + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Describes attributes of your AWS account. You can specify one of the listed attribute choices or omit it to see all attributes. + + + +Requirements +------------ +The below requirements are needed on the local Ansible controller node that executes this lookup. + +- boto3 +- botocore + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th>Configuration</th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>attribute</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>supported-platforms</li> + <li>default-vpc</li> + <li>max-instances</li> + <li>vpc-max-security-groups-per-interface</li> + <li>max-elastic-ips</li> + <li>vpc-max-elastic-ips</li> + <li>has-ec2-classic</li> + </ul> + </td> + <td> + </td> + <td> + <div>The attribute for which to get the value(s).</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:EC2_ACCESS_KEY</div> + <div>env:AWS_ACCESS_KEY</div> + <div>env:AWS_ACCESS_KEY_ID</div> + </td> + <td> + <div>The AWS access key to use.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_access_key_id</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:AWS_DEFAULT_PROFILE</div> + <div>env:AWS_PROFILE</div> + </td> + <td> + <div>The AWS profile</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: boto_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:EC2_SECRET_KEY</div> + <div>env:AWS_SECRET_KEY</div> + <div>env:AWS_SECRET_ACCESS_KEY</div> + </td> + <td> + <div>The AWS secret key that corresponds to the access key.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_secret_access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:EC2_SECURITY_TOKEN</div> + <div>env:AWS_SESSION_TOKEN</div> + <div>env:AWS_SECURITY_TOKEN</div> + </td> + <td> + <div>The AWS security token if using temporary access and secret keys.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:EC2_REGION</div> + <div>env:AWS_REGION</div> + </td> + <td> + <div>The region for which to create the connection.</div> + </td> + </tr> + </table> + <br/> + + + + +Examples +-------- + +.. code-block:: yaml + + vars: + has_ec2_classic: "{{ lookup('aws_account_attribute', attribute='has-ec2-classic') }}" + # true | false + + default_vpc_id: "{{ lookup('aws_account_attribute', attribute='default-vpc') }}" + # vpc-xxxxxxxx | none + + account_details: "{{ lookup('aws_account_attribute', wantlist='true') }}" + # {'default-vpc': ['vpc-xxxxxxxx'], 'max-elastic-ips': ['5'], 'max-instances': ['20'], + # 'supported-platforms': ['VPC', 'EC2'], 'vpc-max-elastic-ips': ['5'], 'vpc-max-security-groups-per-interface': ['5']} + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this lookup: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>_raw</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + </div> + </td> + <td></td> + <td> + <div>Returns a boolean when <em>attribute</em> is check_ec2_classic. Otherwise returns the value(s) of the attribute (or all attributes if one is not specified).</div> + <br/> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Sloane Hertel <shertel@redhat.com> + + +.. hint:: + Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_az_info_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_az_info_module.rst new file mode 100644 index 00000000..11661b89 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_az_info_module.rst @@ -0,0 +1,314 @@ +.. _amazon.aws.aws_az_info_module: + + +********************** +amazon.aws.aws_az_info +********************** + +**Gather information about availability zones in AWS.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Gather information about availability zones in AWS. +- This module was called :ref:`amazon.aws.aws_az_facts <amazon.aws.aws_az_facts_module>` before Ansible 2.9. The usage did not change. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- botocore +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>filters</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">{}</div> + </td> + <td> + <div>A dict of filters to apply.</div> + <div>Each dict item consists of a filter key and a filter value.</div> + <div>See <a href='https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeAvailabilityZones.html'>https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeAvailabilityZones.html</a> for possible filters.</div> + <div>Filter names and values are case sensitive.</div> + <div>You can use underscores instead of dashes (-) in the filter keys.</div> + <div>Filter keys with underscores will take precedence in case of conflict.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + - name: Gather information about all availability zones + amazon.aws.aws_az_info: + + - name: Gather information about a single availability zone + amazon.aws.aws_az_info: + filters: + zone-name: eu-west-1a + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>availability_zones</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>on success</td> + <td> + <div>Availability zones that match the provided filters. Each element consists of a dict with all the information related to that available zone.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">[ { 'messages': [], 'region_name': 'us-west-1', 'state': 'available', 'zone_name': 'us-west-1b' }, { 'messages': [], 'region_name': 'us-west-1', 'state': 'available', 'zone_name': 'us-west-1c' } ]</div> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Henrique Rodrigues (@Sodki) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_caller_info_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_caller_info_module.rst new file mode 100644 index 00000000..5d145142 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_caller_info_module.rst @@ -0,0 +1,343 @@ +.. _amazon.aws.aws_caller_info_module: + + +************************** +amazon.aws.aws_caller_info +************************** + +**Get information about the user and account being used to make AWS calls.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- This module returns information about the account and user / role from which the AWS access tokens originate. +- The primary use of this is to get the account id for templating into ARNs or similar to avoid needing to specify this information in inventory. +- This module was called :ref:`amazon.aws.aws_caller_facts <amazon.aws.aws_caller_facts_module>` before Ansible 2.9. The usage did not change. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- botocore +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + - name: Get the current caller identity information + amazon.aws.aws_caller_info: + register: caller_info + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>account</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>success</td> + <td> + <div>The account id the access credentials are associated with.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">123456789012</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>account_alias</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when caller has the iam:ListAccountAliases permission</td> + <td> + <div>The account alias the access credentials are associated with.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">acme-production</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>arn</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>success</td> + <td> + <div>The arn identifying the user the credentials are associated with.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">arn:aws:sts::123456789012:federated-user/my-federated-user-name</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>user_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>success</td> + <td> + <div>The user id the access credentials are associated with. Note that this may not correspond to + anything you can look up in the case of roles or federated identities.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">123456789012:my-federated-user-name</div> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Ed Costello (@orthanc) +- Stijn Dubrul (@sdubrul) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_ec2_inventory.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_ec2_inventory.rst new file mode 100644 index 00000000..f92cef2f --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_ec2_inventory.rst @@ -0,0 +1,637 @@ +.. _amazon.aws.aws_ec2_inventory: + + +****************** +amazon.aws.aws_ec2 +****************** + +**EC2 inventory source** + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Get inventory hosts from Amazon Web Services EC2. +- Uses a YAML configuration file that ends with ``aws_ec2.(yml|yaml``). + + + +Requirements +------------ +The below requirements are needed on the local Ansible controller node that executes this inventory. + +- boto3 +- botocore + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th>Configuration</th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:EC2_ACCESS_KEY</div> + <div>env:AWS_ACCESS_KEY</div> + <div>env:AWS_ACCESS_KEY_ID</div> + </td> + <td> + <div>The AWS access key to use.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_access_key_id</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:AWS_DEFAULT_PROFILE</div> + <div>env:AWS_PROFILE</div> + </td> + <td> + <div>The AWS profile</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: boto_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:EC2_SECRET_KEY</div> + <div>env:AWS_SECRET_KEY</div> + <div>env:AWS_SECRET_ACCESS_KEY</div> + </td> + <td> + <div>The AWS secret key that corresponds to the access key.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_secret_access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:EC2_SECURITY_TOKEN</div> + <div>env:AWS_SESSION_TOKEN</div> + <div>env:AWS_SECURITY_TOKEN</div> + </td> + <td> + <div>The AWS security token if using temporary access and secret keys.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cache</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div> ini entries: + <p>[inventory]<br>cache = no</p> + </div> + <div>env:ANSIBLE_INVENTORY_CACHE</div> + </td> + <td> + <div>Toggle to enable/disable the caching of the inventory's source data, requires a cache plugin setup to work.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cache_connection</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div> ini entries: + <p>[defaults]<br>fact_caching_connection = VALUE</p> + <p>[inventory]<br>cache_connection = VALUE</p> + </div> + <div>env:ANSIBLE_CACHE_PLUGIN_CONNECTION</div> + <div>env:ANSIBLE_INVENTORY_CACHE_CONNECTION</div> + </td> + <td> + <div>Cache connection data or path, read cache plugin documentation for specifics.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cache_plugin</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"memory"</div> + </td> + <td> + <div> ini entries: + <p>[defaults]<br>fact_caching = memory</p> + <p>[inventory]<br>cache_plugin = memory</p> + </div> + <div>env:ANSIBLE_CACHE_PLUGIN</div> + <div>env:ANSIBLE_INVENTORY_CACHE_PLUGIN</div> + </td> + <td> + <div>Cache plugin to use for the inventory's source data.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cache_prefix</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"ansible_inventory_"</div> + </td> + <td> + <div> ini entries: + <p>[default]<br>fact_caching_prefix = ansible_inventory_</p> + <p>[inventory]<br>cache_prefix = ansible_inventory_</p> + </div> + <div>env:ANSIBLE_CACHE_PLUGIN_PREFIX</div> + <div>env:ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX</div> + </td> + <td> + <div>Prefix to use for cache plugin files/tables</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cache_timeout</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">3600</div> + </td> + <td> + <div> ini entries: + <p>[defaults]<br>fact_caching_timeout = 3600</p> + <p>[inventory]<br>cache_timeout = 3600</p> + </div> + <div>env:ANSIBLE_CACHE_PLUGIN_TIMEOUT</div> + <div>env:ANSIBLE_INVENTORY_CACHE_TIMEOUT</div> + </td> + <td> + <div>Cache duration in seconds</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>compose</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">{}</div> + </td> + <td> + </td> + <td> + <div>Create vars from jinja2 expressions.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>filters</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">{}</div> + </td> + <td> + </td> + <td> + <div>A dictionary of filter value pairs.</div> + <div>Available filters are listed here <a href='http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options'>http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options</a>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>groups</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">{}</div> + </td> + <td> + </td> + <td> + <div>Add hosts to group based on Jinja2 conditionals.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>hostnames</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">[]</div> + </td> + <td> + </td> + <td> + <div>A list in order of precedence for hostname variables.</div> + <div>You can use the options specified in <a href='http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options'>http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options</a>.</div> + <div>To use tags as hostnames use the syntax tag:Name=Value to use the hostname Name_Value, or tag:Name to use the value of the Name tag.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>iam_role_arn</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + </div> + </td> + <td> + </td> + <td> + </td> + <td> + <div>The ARN of the IAM role to assume to perform the inventory lookup. You should still provide AWS credentials with enough privilege to perform the AssumeRole action.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>include_extra_api_calls</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + </td> + <td> + <div>Add two additional API calls for every instance to include 'persistent' and 'events' host variables.</div> + <div>Spot instances may be persistent and instances may have associated events.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>keyed_groups</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">[]</div> + </td> + <td> + </td> + <td> + <div>Add hosts to group based on the values of a variable.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>leading_separator</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 2.11</div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"yes"</div> + </td> + <td> + </td> + <td> + <div>Use in conjunction with keyed_groups.</div> + <div>By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.</div> + <div>This is because the default prefix is "" and the default separator is "_".</div> + <div>Set this option to False to omit the leading underscore (or other separator) if no prefix is given.</div> + <div>If the group name is derived from a mapping the separator is still used to concatenate the items.</div> + <div>To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>plugin</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>aws_ec2</li> + <li>amazon.aws.aws_ec2</li> + </ul> + </td> + <td> + </td> + <td> + <div>Token that ensures this is a source file for the plugin.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>regions</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">[]</div> + </td> + <td> + </td> + <td> + <div>A list of regions in which to describe EC2 instances.</div> + <div>If empty (the default) default this will include all regions, except possibly restricted ones like us-gov-west-1 and cn-north-1.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>strict</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + </td> + <td> + <div>If <code>yes</code> make invalid entries a fatal error, otherwise skip and continue.</div> + <div>Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>strict_permissions</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + </td> + <td> + <div>By default if a 403 (Forbidden) error code is encountered this plugin will fail.</div> + <div>You can set this option to False in the inventory config file which will allow 403 errors to be gracefully skipped.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>use_contrib_script_compatible_sanitization</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + </td> + <td> + <div>By default this plugin is using a general group name sanitization to create safe and usable group names for use in Ansible. This option allows you to override that, in efforts to allow migration from the old inventory script and matches the sanitization of groups when the script's ``replace_dash_in_groups`` option is set to ``False``. To replicate behavior of ``replace_dash_in_groups = True`` with constructed groups, you will need to replace hyphens with underscores via the regex_replace filter for those entries.</div> + <div>For this to work you should also turn off the TRANSFORM_INVALID_GROUP_CHARS setting, otherwise the core engine will just use the standard sanitization on top.</div> + <div>This is not the default as such names break certain functionality as not all characters are valid Python identifiers which group names end up being used as.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>use_extra_vars</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 2.11</div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div> ini entries: + <p>[inventory_plugins]<br>use_extra_vars = no</p> + </div> + <div>env:ANSIBLE_INVENTORY_USE_EXTRA_VARS</div> + </td> + <td> + <div>Merge extra vars into the available variables for composition (highest precedence).</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If no credentials are provided and the control node has an associated IAM instance profile then the role will be used for authentication. + + + +Examples +-------- + +.. code-block:: yaml + + # Minimal example using environment vars or instance role credentials + # Fetch all hosts in us-east-1, the hostname is the public DNS if it exists, otherwise the private IP address + plugin: aws_ec2 + regions: + - us-east-1 + + # Example using filters, ignoring permission errors, and specifying the hostname precedence + plugin: aws_ec2 + boto_profile: aws_profile + # Populate inventory with instances in these regions + regions: + - us-east-1 + - us-east-2 + filters: + # All instances with their `Environment` tag set to `dev` + tag:Environment: dev + # All dev and QA hosts + tag:Environment: + - dev + - qa + instance.group-id: sg-xxxxxxxx + # Ignores 403 errors rather than failing + strict_permissions: False + # Note: I(hostnames) sets the inventory_hostname. To modify ansible_host without modifying + # inventory_hostname use compose (see example below). + hostnames: + - tag:Name=Tag1,Name=Tag2 # Return specific hosts only + - tag:CustomDNSName + - dns-name + - name: 'tag:Name=Tag1,Name=Tag2' + - name: 'private-ip-address' + separator: '_' + prefix: 'tag:Name' + + # Example using constructed features to create groups and set ansible_host + plugin: aws_ec2 + regions: + - us-east-1 + - us-west-1 + # keyed_groups may be used to create custom groups + strict: False + keyed_groups: + # Add e.g. x86_64 hosts to an arch_x86_64 group + - prefix: arch + key: 'architecture' + # Add hosts to tag_Name_Value groups for each Name/Value tag pair + - prefix: tag + key: tags + # Add hosts to e.g. instance_type_z3_tiny + - prefix: instance_type + key: instance_type + # Create security_groups_sg_abcd1234 group for each SG + - key: 'security_groups|json_query("[].group_id")' + prefix: 'security_groups' + # Create a group for each value of the Application tag + - key: tags.Application + separator: '' + # Create a group per region e.g. aws_region_us_east_2 + - key: placement.region + prefix: aws_region + # Create a group (or groups) based on the value of a custom tag "Role" and add them to a metagroup called "project" + - key: tags['Role'] + prefix: foo + parent_group: "project" + # Set individual variables with compose + compose: + # Use the private IP address to connect to the host + # (note: this does not modify inventory_hostname, which is set via I(hostnames)) + ansible_host: private_ip_address + + + + +Status +------ + + +Authors +~~~~~~~ + +- Sloane Hertel (@s-hertel) + + +.. hint:: + Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_rds_inventory.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_rds_inventory.rst new file mode 100644 index 00000000..de00b859 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_rds_inventory.rst @@ -0,0 +1,522 @@ +.. _amazon.aws.aws_rds_inventory: + + +****************** +amazon.aws.aws_rds +****************** + +**rds instance source** + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Get instances and clusters from Amazon Web Services RDS. +- Uses a YAML configuration file that ends with aws_rds.(yml|yaml). + + + +Requirements +------------ +The below requirements are needed on the local Ansible controller node that executes this inventory. + +- boto3 +- botocore + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th>Configuration</th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:EC2_ACCESS_KEY</div> + <div>env:AWS_ACCESS_KEY</div> + <div>env:AWS_ACCESS_KEY_ID</div> + </td> + <td> + <div>The AWS access key to use.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_access_key_id</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:AWS_DEFAULT_PROFILE</div> + <div>env:AWS_PROFILE</div> + </td> + <td> + <div>The AWS profile</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: boto_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:EC2_SECRET_KEY</div> + <div>env:AWS_SECRET_KEY</div> + <div>env:AWS_SECRET_ACCESS_KEY</div> + </td> + <td> + <div>The AWS secret key that corresponds to the access key.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_secret_access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:EC2_SECURITY_TOKEN</div> + <div>env:AWS_SESSION_TOKEN</div> + <div>env:AWS_SECURITY_TOKEN</div> + </td> + <td> + <div>The AWS security token if using temporary access and secret keys.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cache</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div> ini entries: + <p>[inventory]<br>cache = no</p> + </div> + <div>env:ANSIBLE_INVENTORY_CACHE</div> + </td> + <td> + <div>Toggle to enable/disable the caching of the inventory's source data, requires a cache plugin setup to work.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cache_connection</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div> ini entries: + <p>[defaults]<br>fact_caching_connection = VALUE</p> + <p>[inventory]<br>cache_connection = VALUE</p> + </div> + <div>env:ANSIBLE_CACHE_PLUGIN_CONNECTION</div> + <div>env:ANSIBLE_INVENTORY_CACHE_CONNECTION</div> + </td> + <td> + <div>Cache connection data or path, read cache plugin documentation for specifics.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cache_plugin</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"memory"</div> + </td> + <td> + <div> ini entries: + <p>[defaults]<br>fact_caching = memory</p> + <p>[inventory]<br>cache_plugin = memory</p> + </div> + <div>env:ANSIBLE_CACHE_PLUGIN</div> + <div>env:ANSIBLE_INVENTORY_CACHE_PLUGIN</div> + </td> + <td> + <div>Cache plugin to use for the inventory's source data.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cache_prefix</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"ansible_inventory_"</div> + </td> + <td> + <div> ini entries: + <p>[default]<br>fact_caching_prefix = ansible_inventory_</p> + <p>[inventory]<br>cache_prefix = ansible_inventory_</p> + </div> + <div>env:ANSIBLE_CACHE_PLUGIN_PREFIX</div> + <div>env:ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX</div> + </td> + <td> + <div>Prefix to use for cache plugin files/tables</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cache_timeout</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">3600</div> + </td> + <td> + <div> ini entries: + <p>[defaults]<br>fact_caching_timeout = 3600</p> + <p>[inventory]<br>cache_timeout = 3600</p> + </div> + <div>env:ANSIBLE_CACHE_PLUGIN_TIMEOUT</div> + <div>env:ANSIBLE_INVENTORY_CACHE_TIMEOUT</div> + </td> + <td> + <div>Cache duration in seconds</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>compose</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">{}</div> + </td> + <td> + </td> + <td> + <div>Create vars from jinja2 expressions.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>filters</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">{}</div> + </td> + <td> + </td> + <td> + <div>A dictionary of filter value pairs. Available filters are listed here <a href='https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html#options'>https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html#options</a>. If you filter by db-cluster-id and <em>include_clusters</em> is True it will apply to clusters as well.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>groups</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">{}</div> + </td> + <td> + </td> + <td> + <div>Add hosts to group based on Jinja2 conditionals.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>iam_role_arn</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + </div> + </td> + <td> + </td> + <td> + </td> + <td> + <div>The ARN of the IAM role to assume to perform the inventory lookup. You should still provide AWS credentials with enough privilege to perform the AssumeRole action.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>include_clusters</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + </td> + <td> + <div>Whether or not to query for Aurora clusters as well as instances</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>keyed_groups</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">[]</div> + </td> + <td> + </td> + <td> + <div>Add hosts to group based on the values of a variable.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>leading_separator</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 2.11</div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"yes"</div> + </td> + <td> + </td> + <td> + <div>Use in conjunction with keyed_groups.</div> + <div>By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.</div> + <div>This is because the default prefix is "" and the default separator is "_".</div> + <div>Set this option to False to omit the leading underscore (or other separator) if no prefix is given.</div> + <div>If the group name is derived from a mapping the separator is still used to concatenate the items.</div> + <div>To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>regions</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">[]</div> + </td> + <td> + </td> + <td> + <div>A list of regions in which to describe RDS instances and clusters. Available regions are listed here <a href='https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html'>https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html</a></div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>statuses</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">["creating", "available"]</div> + </td> + <td> + </td> + <td> + <div>A list of desired states for instances/clusters to be added to inventory. Set to ['all'] as a shorthand to find everything.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>strict</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + </td> + <td> + <div>If <code>yes</code> make invalid entries a fatal error, otherwise skip and continue.</div> + <div>Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>strict_permissions</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + </td> + <td> + <div>By default if an AccessDenied exception is encountered this plugin will fail. You can set strict_permissions to False in the inventory config file which will allow the restrictions to be gracefully skipped.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>use_extra_vars</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 2.11</div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div> ini entries: + <p>[inventory_plugins]<br>use_extra_vars = no</p> + </div> + <div>env:ANSIBLE_INVENTORY_USE_EXTRA_VARS</div> + </td> + <td> + <div>Merge extra vars into the available variables for composition (highest precedence).</div> + </td> + </tr> + </table> + <br/> + + + + +Examples +-------- + +.. code-block:: yaml + + plugin: aws_rds + regions: + - us-east-1 + - ca-central-1 + keyed_groups: + - key: 'db_parameter_groups|json_query("[].db_parameter_group_name")' + prefix: rds_parameter_group + - key: engine + prefix: rds + - key: tags + - key: region + + + + +Status +------ + + +Authors +~~~~~~~ + +- Sloane Hertel (@s-hertel) + + +.. hint:: + Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_s3_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_s3_module.rst new file mode 100644 index 00000000..642bac91 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_s3_module.rst @@ -0,0 +1,866 @@ +.. _amazon.aws.aws_s3_module: + + +***************** +amazon.aws.aws_s3 +***************** + +**manage objects in S3.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- This module allows the user to manage S3 buckets and the objects within them. Includes support for creating and deleting both objects and buckets, retrieving objects as files or strings and generating download links. This module has a dependency on boto3 and botocore. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- botocore +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>bucket</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + </td> + <td> + <div>Bucket name.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>content</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 1.3.0</div> + </td> + <td> + </td> + <td> + <div>The content to PUT into an object.</div> + <div>The parameter value will be treated as a string and converted to UTF-8 before sending it to S3. To send binary data, use the <em>content_base64</em> parameter instead.</div> + <div>Either <em>content</em>, <em>content_base64</em> or <em>src</em> must be specified for a PUT operation. Ignored otherwise.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>content_base64</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 1.3.0</div> + </td> + <td> + </td> + <td> + <div>The base64-encoded binary data to PUT into an object.</div> + <div>Use this if you need to put raw binary data, and don't forget to encode in base64.</div> + <div>Either <em>content</em>, <em>content_base64</em> or <em>src</em> must be specified for a PUT operation. Ignored otherwise.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>dest</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The destination file path when downloading an object/key with a GET operation.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>dualstack</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Enables Amazon S3 Dual-Stack Endpoints, allowing S3 communications using both IPv4 and IPv6.</div> + <div>Requires at least botocore version 1.4.45.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>encrypt</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set for PUT mode, asks for server-side encryption.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>encryption_kms_key_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>KMS key id to use when encrypting objects using <em>encrypting=aws:kms</em>. Ignored if <em>encryption</em> is not <code>aws:kms</code>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>encryption_mode</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>AES256</b> ←</div></li> + <li>aws:kms</li> + </ul> + </td> + <td> + <div>What encryption mode to use if <em>encrypt=true</em>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>expiry</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">600</div> + </td> + <td> + <div>Time limit (in seconds) for the URL generated and returned by S3/Walrus when performing a <em>mode=put</em> or <em>mode=geturl</em> operation.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: expiration</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>headers</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>Custom headers for PUT operation, as a dictionary of <code>key=value</code> and <code>key=value,key=value</code>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ignore_nonexistent_bucket</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Overrides initial bucket lookups in case bucket or iam policies are restrictive. Example: a user may have the GetObject permission but no other permissions. In this case using the option mode: get will fail without specifying <em>ignore_nonexistent_bucket=true</em>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>marker</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Specifies the key to start with when using list mode. Object keys are returned in alphabetical order, starting with key after the marker in order.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>max_keys</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">1000</div> + </td> + <td> + <div>Max number of results to return in list mode, set this if you want to retrieve fewer than the default 1000 keys.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>metadata</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>Metadata for PUT operation, as a dictionary of <code>key=value</code> and <code>key=value,key=value</code>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>mode</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>get</li> + <li>put</li> + <li>delete</li> + <li>create</li> + <li>geturl</li> + <li>getstr</li> + <li>delobj</li> + <li>list</li> + </ul> + </td> + <td> + <div>Switches the module behaviour between <code>put</code> (upload), <code>get</code> (download), <code>geturl</code> (return download url, Ansible 1.3+), <code>getstr</code> (download object as string (1.3+)), <code>list</code> (list keys, Ansible 2.0+), <code>create</code> (bucket), <code>delete</code> (bucket), and delobj (delete object, Ansible 2.0+).</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>object</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Keyname of the object inside the bucket. Can be used to create "virtual directories", see examples.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>overwrite</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"always"</div> + </td> + <td> + <div>Force overwrite either locally on the filesystem or remotely with the object/key. Used with PUT and GET operations.</div> + <div>Must be a Boolean, <code>always</code>, <code>never</code> or <code>different</code>.</div> + <div><code>true</code> is the same as <code>always</code>.</div> + <div><code>false</code> is equal to <code>never</code>.</div> + <div>When this is set to <code>different</code> the MD5 sum of the local file is compared with the 'ETag' of the object/key in S3. The ETag may or may not be an MD5 digest of the object data. See the ETag response header here <a href='https://docs.aws.amazon.com/AmazonS3/latest/API/RESTCommonResponseHeaders.html'>https://docs.aws.amazon.com/AmazonS3/latest/API/RESTCommonResponseHeaders.html</a>.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: force</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>permission</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">["private"]</div> + </td> + <td> + <div>This option lets the user set the canned permissions on the object/bucket that are created. The permissions that can be set are <code>private</code>, <code>public-read</code>, <code>public-read-write</code>, <code>authenticated-read</code> for a bucket or <code>private</code>, <code>public-read</code>, <code>public-read-write</code>, <code>aws-exec-read</code>, <code>authenticated-read</code>, <code>bucket-owner-read</code>, <code>bucket-owner-full-control</code> for an object. Multiple permissions can be specified as a list.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>prefix</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">""</div> + </td> + <td> + <div>Limits the response to keys that begin with the specified prefix for list mode.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>retries</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">0</div> + </td> + <td> + <div>On recoverable failure, how many times to retry before actually failing.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: retry</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>rgw</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Enable Ceph RGW S3 support. This option requires an explicit url via <em>s3_url</em>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>s3_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>S3 URL endpoint for usage with Ceph, Eucalyptus and fakes3 etc. Otherwise assumes AWS.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: S3_URL</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>src</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The source file path when performing a PUT operation.</div> + <div>Either <em>content</em>, <em>content_base64</em> or <em>src</em> must be specified for a PUT operation. Ignored otherwise.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>version</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Version ID of the object inside the bucket. Can be used to get a specific version of a file if versioning is enabled in the target bucket.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + - name: Simple PUT operation + amazon.aws.aws_s3: + bucket: mybucket + object: /my/desired/key.txt + src: /usr/local/myfile.txt + mode: put + + - name: PUT operation from a rendered template + amazon.aws.aws_s3: + bucket: mybucket + object: /object.yaml + content: "{{ lookup('template', 'templates/object.yaml.j2') }}" + mode: put + + - name: Simple PUT operation in Ceph RGW S3 + amazon.aws.aws_s3: + bucket: mybucket + object: /my/desired/key.txt + src: /usr/local/myfile.txt + mode: put + rgw: true + s3_url: "http://localhost:8000" + + - name: Simple GET operation + amazon.aws.aws_s3: + bucket: mybucket + object: /my/desired/key.txt + dest: /usr/local/myfile.txt + mode: get + + - name: Get a specific version of an object. + amazon.aws.aws_s3: + bucket: mybucket + object: /my/desired/key.txt + version: 48c9ee5131af7a716edc22df9772aa6f + dest: /usr/local/myfile.txt + mode: get + + - name: PUT/upload with metadata + amazon.aws.aws_s3: + bucket: mybucket + object: /my/desired/key.txt + src: /usr/local/myfile.txt + mode: put + metadata: 'Content-Encoding=gzip,Cache-Control=no-cache' + + - name: PUT/upload with custom headers + amazon.aws.aws_s3: + bucket: mybucket + object: /my/desired/key.txt + src: /usr/local/myfile.txt + mode: put + headers: 'x-amz-grant-full-control=emailAddress=owner@example.com' + + - name: List keys simple + amazon.aws.aws_s3: + bucket: mybucket + mode: list + + - name: List keys all options + amazon.aws.aws_s3: + bucket: mybucket + mode: list + prefix: /my/desired/ + marker: /my/desired/0023.txt + max_keys: 472 + + - name: Create an empty bucket + amazon.aws.aws_s3: + bucket: mybucket + mode: create + permission: public-read + + - name: Create a bucket with key as directory, in the EU region + amazon.aws.aws_s3: + bucket: mybucket + object: /my/directory/path + mode: create + region: eu-west-1 + + - name: Delete a bucket and all contents + amazon.aws.aws_s3: + bucket: mybucket + mode: delete + + - name: GET an object but don't download if the file checksums match. New in 2.0 + amazon.aws.aws_s3: + bucket: mybucket + object: /my/desired/key.txt + dest: /usr/local/myfile.txt + mode: get + overwrite: different + + - name: Delete an object from a bucket + amazon.aws.aws_s3: + bucket: mybucket + object: /my/desired/key.txt + mode: delobj + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>contents</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>(for getstr operation)</td> + <td> + <div>Contents of the object as string.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">Hello, world!</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>expiry</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td>(for geturl operation)</td> + <td> + <div>Number of seconds the presigned url is valid for.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">600</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>msg</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>Message indicating the status of the operation.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">PUT operation complete</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>s3_keys</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td>(for list operation)</td> + <td> + <div>List of object keys.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">['prefix1/', 'prefix1/key1', 'prefix1/key2']</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>url</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>(for put and geturl operations)</td> + <td> + <div>URL of the object.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">https://my-bucket.s3.amazonaws.com/my-key.txt?AWSAccessKeyId=<access-key>&Expires=1506888865&Signature=<signature></div> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Lester Wade (@lwade) +- Sloane Hertel (@s-hertel) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_secret_lookup.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_secret_lookup.rst new file mode 100644 index 00000000..dcb22f14 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_secret_lookup.rst @@ -0,0 +1,387 @@ +.. _amazon.aws.aws_secret_lookup: + + +********************* +amazon.aws.aws_secret +********************* + +**Look up secrets stored in AWS Secrets Manager.** + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Look up secrets stored in AWS Secrets Manager provided the caller has the appropriate permissions to read the secret. +- Lookup is based on the secret's *Name* value. +- Optional parameters can be passed into this lookup; *version_id* and *version_stage* + + + +Requirements +------------ +The below requirements are needed on the local Ansible controller node that executes this lookup. + +- boto3 +- botocore>=1.10.0 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th>Configuration</th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>_terms</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + </td> + <td> + </td> + <td> + <div>Name of the secret to look up in AWS Secrets Manager.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:EC2_ACCESS_KEY</div> + <div>env:AWS_ACCESS_KEY</div> + <div>env:AWS_ACCESS_KEY_ID</div> + </td> + <td> + <div>The AWS access key to use.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_access_key_id</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:AWS_DEFAULT_PROFILE</div> + <div>env:AWS_PROFILE</div> + </td> + <td> + <div>The AWS profile</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: boto_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:EC2_SECRET_KEY</div> + <div>env:AWS_SECRET_KEY</div> + <div>env:AWS_SECRET_ACCESS_KEY</div> + </td> + <td> + <div>The AWS secret key that corresponds to the access key.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_secret_access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:EC2_SECURITY_TOKEN</div> + <div>env:AWS_SESSION_TOKEN</div> + <div>env:AWS_SECURITY_TOKEN</div> + </td> + <td> + <div>The AWS security token if using temporary access and secret keys.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>bypath</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 1.4.0</div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"no"</div> + </td> + <td> + </td> + <td> + <div>A boolean to indicate whether the parameter is provided as a hierarchy.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>join</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"no"</div> + </td> + <td> + </td> + <td> + <div>Join two or more entries to form an extended secret.</div> + <div>This is useful for overcoming the 4096 character limit imposed by AWS.</div> + <div>No effect when used with <em>bypath</em>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>nested</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 1.4.0</div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"no"</div> + </td> + <td> + </td> + <td> + <div>A boolean to indicate the secret contains nested values.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>on_denied</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>error</b> ←</div></li> + <li>skip</li> + <li>warn</li> + </ul> + </td> + <td> + </td> + <td> + <div>Action to take if access to the secret is denied.</div> + <div><code>error</code> will raise a fatal error when access to the secret is denied.</div> + <div><code>skip</code> will silently ignore the denied secret.</div> + <div><code>warn</code> will skip over the denied secret but issue a warning.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>on_missing</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>error</b> ←</div></li> + <li>skip</li> + <li>warn</li> + </ul> + </td> + <td> + </td> + <td> + <div>Action to take if the secret is missing.</div> + <div><code>error</code> will raise a fatal error when the secret is missing.</div> + <div><code>skip</code> will silently ignore the missing secret.</div> + <div><code>warn</code> will skip over the missing secret but issue a warning.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>env:EC2_REGION</div> + <div>env:AWS_REGION</div> + </td> + <td> + <div>The region for which to create the connection.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>version_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + </div> + </td> + <td> + </td> + <td> + </td> + <td> + <div>Version of the secret(s).</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>version_stage</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + </div> + </td> + <td> + </td> + <td> + </td> + <td> + <div>Stage of the secret version.</div> + </td> + </tr> + </table> + <br/> + + + + +Examples +-------- + +.. code-block:: yaml + + - name: lookup secretsmanager secret in the current region + debug: msg="{{ lookup('amazon.aws.aws_secret', '/path/to/secrets', bypath=true) }}" + + - name: Create RDS instance with aws_secret lookup for password param + rds: + command: create + instance_name: app-db + db_engine: MySQL + size: 10 + instance_type: db.m1.small + username: dbadmin + password: "{{ lookup('amazon.aws.aws_secret', 'DbSecret') }}" + tags: + Environment: staging + + - name: skip if secret does not exist + debug: msg="{{ lookup('amazon.aws.aws_secret', 'secret-not-exist', on_missing='skip')}}" + + - name: warn if access to the secret is denied + debug: msg="{{ lookup('amazon.aws.aws_secret', 'secret-denied', on_denied='warn')}}" + + - name: lookup secretsmanager secret in the current region using the nested feature + debug: msg="{{ lookup('amazon.aws.aws_secret', 'secrets.environments.production.password', nested=true) }}" + # The secret can be queried using the following syntax: `aws_secret_object_name.key1.key2.key3`. + # If an object is of the form `{"key1":{"key2":{"key3":1}}}` the query would return the value `1`. + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this lookup: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>_raw</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + </div> + </td> + <td></td> + <td> + <div>Returns the value of the secret stored in AWS Secrets Manager.</div> + <br/> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Aaron Smith <ajsmith10381@gmail.com> + + +.. hint:: + Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_service_ip_ranges_lookup.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_service_ip_ranges_lookup.rst new file mode 100644 index 00000000..194929b4 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_service_ip_ranges_lookup.rst @@ -0,0 +1,144 @@ +.. _amazon.aws.aws_service_ip_ranges_lookup: + + +******************************** +amazon.aws.aws_service_ip_ranges +******************************** + +**Look up the IP ranges for services provided in AWS such as EC2 and S3.** + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- AWS publishes IP ranges used on the public internet by EC2, S3, CloudFront, CodeBuild, Route53, and Route53 Health Checking. +- This module produces a list of all the ranges (by default) or can narrow down the list to the specified region or service. + + + +Requirements +------------ +The below requirements are needed on the local Ansible controller node that executes this lookup. + +- must have public internet connectivity + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th>Configuration</th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + </div> + </td> + <td> + </td> + <td> + </td> + <td> + <div>The AWS region to narrow the ranges to. Examples: us-east-1, eu-west-2, ap-southeast-1</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>service</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + </div> + </td> + <td> + </td> + <td> + </td> + <td> + <div>The service to filter ranges by. Options: EC2, S3, CLOUDFRONT, CODEbUILD, ROUTE53, ROUTE53_HEALTHCHECKS</div> + </td> + </tr> + </table> + <br/> + + + + +Examples +-------- + +.. code-block:: yaml + + vars: + ec2_ranges: "{{ lookup('aws_service_ip_ranges', region='ap-southeast-2', service='EC2', wantlist=True) }}" + tasks: + + - name: "use list return option and iterate as a loop" + debug: msg="{% for cidr in ec2_ranges %}{{ cidr }} {% endfor %}" + # "52.62.0.0/15 52.64.0.0/17 52.64.128.0/17 52.65.0.0/16 52.95.241.0/24 52.95.255.16/28 54.66.0.0/16 " + + - name: "Pull S3 IP ranges, and print the default return style" + debug: msg="{{ lookup('aws_service_ip_ranges', region='us-east-1', service='S3') }}" + # "52.92.16.0/20,52.216.0.0/15,54.231.0.0/17" + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this lookup: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>_raw</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">-</span> + </div> + </td> + <td></td> + <td> + <div>comma-separated list of CIDR ranges</div> + <br/> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- James Turner <turnerjsm@gmail.com> + + +.. hint:: + Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_ssm_lookup.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_ssm_lookup.rst new file mode 100644 index 00000000..522bf4b9 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.aws_ssm_lookup.rst @@ -0,0 +1,192 @@ +.. _amazon.aws.aws_ssm_lookup: + + +****************** +amazon.aws.aws_ssm +****************** + +**Get the value for a SSM parameter or all parameters under a path.** + + + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Get the value for an Amazon Simple Systems Manager parameter or a hierarchy of parameters. The first argument you pass the lookup can either be a parameter name or a hierarchy of parameters. Hierarchies start with a forward slash and end with the parameter name. Up to 5 layers may be specified. +- If looking up an explicitly listed parameter by name which does not exist then the lookup will return a None value which will be interpreted by Jinja2 as an empty string. You can use the ```default``` filter to give a default value in this case but must set the second parameter to true (see examples below) +- When looking up a path for parameters under it a dictionary will be returned for each path. If there is no parameter under that path then the return will be successful but the dictionary will be empty. +- If the lookup fails due to lack of permissions or due to an AWS client error then the aws_ssm will generate an error, normally crashing the current ansible task. This is normally the right thing since ignoring a value that IAM isn't giving access to could cause bigger problems and wrong behaviour or loss of data. If you want to continue in this case then you will have to set up two ansible tasks, one which sets a variable and ignores failures one which uses the value of that variable with a default. See the examples below. + + + +Requirements +------------ +The below requirements are needed on the local Ansible controller node that executes this lookup. + +- boto3 +- botocore + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th>Configuration</th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>bypath</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"no"</div> + </td> + <td> + </td> + <td> + <div>A boolean to indicate whether the parameter is provided as a hierarchy.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>decrypt</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"yes"</div> + </td> + <td> + </td> + <td> + <div>A boolean to indicate whether to decrypt the parameter.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>recursive</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"no"</div> + </td> + <td> + </td> + <td> + <div>A boolean to indicate whether to retrieve all parameters within a hierarchy.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>shortnames</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"no"</div> + </td> + <td> + </td> + <td> + <div>Indicates whether to return the name only without path if using a parameter hierarchy.</div> + </td> + </tr> + </table> + <br/> + + + + +Examples +-------- + +.. code-block:: yaml + + # lookup sample: + - name: lookup ssm parameter store in the current region + debug: msg="{{ lookup('aws_ssm', 'Hello' ) }}" + + - name: lookup ssm parameter store in nominated region + debug: msg="{{ lookup('aws_ssm', 'Hello', region='us-east-2' ) }}" + + - name: lookup ssm parameter store without decrypted + debug: msg="{{ lookup('aws_ssm', 'Hello', decrypt=False ) }}" + + - name: lookup ssm parameter store in nominated aws profile + debug: msg="{{ lookup('aws_ssm', 'Hello', aws_profile='myprofile' ) }}" + + - name: lookup ssm parameter store using explicit aws credentials + debug: msg="{{ lookup('aws_ssm', 'Hello', aws_access_key=my_aws_access_key, aws_secret_key=my_aws_secret_key, aws_security_token=my_security_token ) }}" + + - name: lookup ssm parameter store with all options. + debug: msg="{{ lookup('aws_ssm', 'Hello', decrypt=false, region='us-east-2', aws_profile='myprofile') }}" + + - name: lookup a key which doesn't exist, returns "" + debug: msg="{{ lookup('aws_ssm', 'NoKey') }}" + + - name: lookup a key which doesn't exist, returning a default ('root') + debug: msg="{{ lookup('aws_ssm', 'AdminID') | default('root', true) }}" + + - name: lookup a key which doesn't exist failing to store it in a fact + set_fact: + temp_secret: "{{ lookup('aws_ssm', '/NoAccess/hiddensecret') }}" + ignore_errors: true + + - name: show fact default to "access failed" if we don't have access + debug: msg="{{ 'the secret was:' ~ temp_secret | default('could not access secret') }}" + + - name: return a dictionary of ssm parameters from a hierarchy path + debug: msg="{{ lookup('aws_ssm', '/PATH/to/params', region='ap-southeast-2', bypath=true, recursive=true ) }}" + + - name: return a dictionary of ssm parameters from a hierarchy path with shortened names (param instead of /PATH/to/param) + debug: msg="{{ lookup('aws_ssm', '/PATH/to/params', region='ap-southeast-2', shortnames=true, bypath=true, recursive=true ) }}" + + - name: Iterate over a parameter hierarchy (one iteration per parameter) + debug: msg='Key contains {{ item.key }} , with value {{ item.value }}' + loop: '{{ lookup("aws_ssm", "/demo/", region="ap-southeast-2", bypath=True) | dict2items }}' + + - name: Iterate over multiple paths as dictionaries (one iteration per path) + debug: msg='Path contains {{ item }}' + loop: '{{ lookup("aws_ssm", "/demo/", "/demo1/", bypath=True)}}' + + + + +Status +------ + + +Authors +~~~~~~~ + +- Bill Wang <ozbillwang(at)gmail.com> +- Marat Bakeev <hawara(at)gmail.com> +- Michael De La Rue <siblemitcom.mddlr@spamgourmet.com> + + +.. hint:: + Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.cloudformation_info_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.cloudformation_info_module.rst new file mode 100644 index 00000000..e7dc6c8c --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.cloudformation_info_module.rst @@ -0,0 +1,585 @@ +.. _amazon.aws.cloudformation_info_module: + + +****************************** +amazon.aws.cloudformation_info +****************************** + +**Obtain information about an AWS CloudFormation stack** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Gets information about an AWS CloudFormation stack. +- This module was called ``amazon.aws.cloudformation_facts`` before Ansible 2.9, returning ``ansible_facts``. Note that the :ref:`amazon.aws.cloudformation_info <amazon.aws.cloudformation_info_module>` module no longer returns ``ansible_facts``! + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 >= 1.0.0 +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>all_facts</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Get all stack information for the stack.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>stack_change_sets</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Get stack change sets for the stack</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>stack_events</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Get stack events for the stack.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>stack_name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The name or id of the CloudFormation stack. Gathers information on all stacks by default.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>stack_policy</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Get stack policy for the stack.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>stack_resources</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Get stack resources for the stack.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>stack_template</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Get stack template body for the stack.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + - name: Get summary information about a stack + amazon.aws.cloudformation_info: + stack_name: my-cloudformation-stack + register: output + + - debug: + msg: "{{ output['cloudformation']['my-cloudformation-stack'] }}" + + # When the module is called as cloudformation_facts, return values are published + # in ansible_facts['cloudformation'][<stack_name>] and can be used as follows. + # Note that this is deprecated and will stop working in Ansible after 2021-12-01. + + - amazon.aws.cloudformation_facts: + stack_name: my-cloudformation-stack + + - debug: + msg: "{{ ansible_facts['cloudformation']['my-cloudformation-stack'] }}" + + # Get stack outputs, when you have the stack name available as a fact + - set_fact: + stack_name: my-awesome-stack + + - amazon.aws.cloudformation_info: + stack_name: "{{ stack_name }}" + register: my_stack + + - debug: + msg: "{{ my_stack.cloudformation[stack_name].stack_outputs }}" + + # Get all stack information about a stack + - amazon.aws.cloudformation_info: + stack_name: my-cloudformation-stack + all_facts: true + + # Get stack resource and stack policy information about a stack + - amazon.aws.cloudformation_info: + stack_name: my-cloudformation-stack + stack_resources: true + stack_policy: true + + # Fail if the stack doesn't exist + - name: try to get facts about a stack but fail if it doesn't exist + amazon.aws.cloudformation_info: + stack_name: nonexistent-stack + all_facts: yes + failed_when: cloudformation['nonexistent-stack'] is undefined + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>stack_change_sets</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>only if all_facts or stack_change_sets is true and the stack exists</td> + <td> + <div>A list of stack change sets. Each item in the list represents the details of a specific changeset</div> + <br/> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>stack_description</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>if the stack exists</td> + <td> + <div>Summary facts about the stack</div> + <br/> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>stack_events</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>only if all_facts or stack_events is true and the stack exists</td> + <td> + <div>All stack events for the stack</div> + <br/> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>stack_outputs</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>if the stack exists</td> + <td> + <div>Dictionary of stack outputs keyed by the value of each output 'OutputKey' parameter and corresponding value of each output 'OutputValue' parameter</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'ApplicationDatabaseName': 'dazvlpr01xj55a.ap-southeast-2.rds.amazonaws.com'}</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>stack_parameters</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>if the stack exists</td> + <td> + <div>Dictionary of stack parameters keyed by the value of each parameter 'ParameterKey' parameter and corresponding value of each parameter 'ParameterValue' parameter</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'DatabaseEngine': 'mysql', 'DatabasePassword': '***'}</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>stack_policy</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>only if all_facts or stack_policy is true and the stack exists</td> + <td> + <div>Describes the stack policy for the stack</div> + <br/> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>stack_resource_list</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>only if all_facts or stack_resources is true and the stack exists</td> + <td> + <div>Describes stack resources for the stack</div> + <br/> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>stack_resources</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>only if all_facts or stack_resources is true and the stack exists</td> + <td> + <div>Dictionary of stack resources keyed by the value of each resource 'LogicalResourceId' parameter and corresponding value of each resource 'PhysicalResourceId' parameter</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'AutoScalingGroup': 'dev-someapp-AutoscalingGroup-1SKEXXBCAN0S7', 'AutoScalingSecurityGroup': 'sg-abcd1234', 'ApplicationDatabase': 'dazvlpr01xj55a'}</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>stack_template</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>only if all_facts or stack_template is true and the stack exists</td> + <td> + <div>Describes the stack template for the stack</div> + <br/> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Justin Menga (@jmenga) +- Kevin Coming (@waffie1) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.cloudformation_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.cloudformation_module.rst new file mode 100644 index 00000000..57059af5 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.cloudformation_module.rst @@ -0,0 +1,839 @@ +.. _amazon.aws.cloudformation_module: + + +************************* +amazon.aws.cloudformation +************************* + +**Create or delete an AWS CloudFormation stack** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Launches or updates an AWS CloudFormation stack and waits for it complete. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- botocore>=1.5.45 +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>backoff_delay</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">3</div> + </td> + <td> + <div>Number of seconds to wait for the next retry.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>backoff_max_delay</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">30</div> + </td> + <td> + <div>Maximum amount of time to wait between retries.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>backoff_retries</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">10</div> + </td> + <td> + <div>Number of times to retry operation.</div> + <div>AWS API throttling mechanism fails CloudFormation module so we have to retry a couple of times.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>capabilities</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">["CAPABILITY_IAM", "CAPABILITY_NAMED_IAM"]</div> + </td> + <td> + <div>Specify capabilities that stack template contains.</div> + <div>Valid values are <code>CAPABILITY_IAM</code>, <code>CAPABILITY_NAMED_IAM</code> and <code>CAPABILITY_AUTO_EXPAND</code>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>changeset_name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Name given to the changeset when creating a changeset.</div> + <div>Only used when <em>create_changeset=true</em>.</div> + <div>By default a name prefixed with Ansible-STACKNAME is generated based on input parameters. See the AWS Change Sets docs for more information <a href='https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html'>https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html</a></div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>create_changeset</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>If stack already exists create a changeset instead of directly applying changes. See the AWS Change Sets docs <a href='https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html'>https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html</a>.</div> + <div>WARNING: if the stack does not exist, it will be created without changeset. If <em>state=absent</em>, the stack will be deleted immediately with no changeset.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>create_timeout</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>The amount of time (in minutes) that can pass before the stack status becomes CREATE_FAILED</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>disable_rollback</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>If a stacks fails to form, rollback will remove the stack.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>events_limit</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">200</div> + </td> + <td> + <div>Maximum number of CloudFormation events to fetch from a stack when creating or updating it.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>notification_arns</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>A comma separated list of Simple Notification Service (SNS) topic ARNs to publish stack related events.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>on_create_failure</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>DO_NOTHING</li> + <li>ROLLBACK</li> + <li>DELETE</li> + </ul> + </td> + <td> + <div>Action to take upon failure of stack creation. Incompatible with the <em>disable_rollback</em> option.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>role_arn</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The role that AWS CloudFormation assumes to create the stack. See the AWS CloudFormation Service Role docs <a href='https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-servicerole.html'>https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-servicerole.html</a></div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>stack_name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + </td> + <td> + <div>Name of the CloudFormation stack.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>stack_policy</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The path of the CloudFormation stack policy. A policy cannot be removed once placed, but it can be modified. for instance, allow all updates <a href='https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/protect-stack-resources.html#d0e9051'>https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/protect-stack-resources.html#d0e9051</a></div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>present</b> ←</div></li> + <li>absent</li> + </ul> + </td> + <td> + <div>If <em>state=present</em>, stack will be created.</div> + <div>If <em>state=present</em> and if stack exists and template has changed, it will be updated.</div> + <div>If <em>state=absent</em>, stack will be removed.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>Dictionary of tags to associate with stack and its resources during stack creation.</div> + <div>Can be updated later, updating tags removes previous entries.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>template</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The local path of the CloudFormation template.</div> + <div>This must be the full path to the file, relative to the working directory. If using roles this may look like <code>roles/cloudformation/files/cloudformation-example.json</code>.</div> + <div>If <em>state=present</em> and the stack does not exist yet, either <em>template</em>, <em>template_body</em> or <em>template_url</em> must be specified (but only one of them).</div> + <div>If <em>state=present</em>, the stack does exist, and neither <em>template</em>, <em>template_body</em> nor <em>template_url</em> are specified, the previous template will be reused.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>template_body</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Template body. Use this to pass in the actual body of the CloudFormation template.</div> + <div>If <em>state=present</em> and the stack does not exist yet, either <em>template</em>, <em>template_body</em> or <em>template_url</em> must be specified (but only one of them).</div> + <div>If <em>state=present</em>, the stack does exist, and neither <em>template</em>, <em>template_body</em> nor <em>template_url</em> are specified, the previous template will be reused.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>template_format</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>This parameter is ignored since Ansible 2.3 and will be removed after 2022-06-01.</div> + <div>Templates are now passed raw to CloudFormation regardless of format.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>template_parameters</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">{}</div> + </td> + <td> + <div>A list of hashes of all the template variables for the stack. The value can be a string or a dict.</div> + <div>Dict can be used to set additional template parameter attributes like UsePreviousValue (see example).</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>template_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Location of file containing the template body. The URL must point to a template (max size 307,200 bytes) located in an S3 bucket in the same region as the stack.</div> + <div>If <em>state=present</em> and the stack does not exist yet, either <em>template</em>, <em>template_body</em> or <em>template_url</em> must be specified (but only one of them).</div> + <div>If <em>state=present</em>, the stack does exist, and neither <em>template</em>, <em>template_body</em> nor <em>template_url</em> are specified, the previous template will be reused.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>termination_protection</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + </td> + <td> + <div>Enable or disable termination protection on the stack. Only works with botocore >= 1.7.18.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - CloudFormation features change often, and this module tries to keep up. That means your botocore version should be fresh. The version listed in the requirements is the oldest version that works with the module as a whole. Some features may require recent versions, and we do not pinpoint a minimum version for each feature. Instead of relying on the minimum version, keep botocore up to date. AWS is always releasing features and fixing bugs. + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + - name: create a cloudformation stack + amazon.aws.cloudformation: + stack_name: "ansible-cloudformation" + state: "present" + region: "us-east-1" + disable_rollback: true + template: "files/cloudformation-example.json" + template_parameters: + KeyName: "jmartin" + DiskType: "ephemeral" + InstanceType: "m1.small" + ClusterSize: 3 + tags: + Stack: "ansible-cloudformation" + + # Basic role example + - name: create a stack, specify role that cloudformation assumes + amazon.aws.cloudformation: + stack_name: "ansible-cloudformation" + state: "present" + region: "us-east-1" + disable_rollback: true + template: "roles/cloudformation/files/cloudformation-example.json" + role_arn: 'arn:aws:iam::123456789012:role/cloudformation-iam-role' + + - name: delete a stack + amazon.aws.cloudformation: + stack_name: "ansible-cloudformation-old" + state: "absent" + + # Create a stack, pass in template from a URL, disable rollback if stack creation fails, + # pass in some parameters to the template, provide tags for resources created + - name: create a stack, pass in the template via an URL + amazon.aws.cloudformation: + stack_name: "ansible-cloudformation" + state: present + region: us-east-1 + disable_rollback: true + template_url: https://s3.amazonaws.com/my-bucket/cloudformation.template + template_parameters: + KeyName: jmartin + DiskType: ephemeral + InstanceType: m1.small + ClusterSize: 3 + tags: + Stack: ansible-cloudformation + + # Create a stack, passing in template body using lookup of Jinja2 template, disable rollback if stack creation fails, + # pass in some parameters to the template, provide tags for resources created + - name: create a stack, pass in the template body via lookup template + amazon.aws.cloudformation: + stack_name: "ansible-cloudformation" + state: present + region: us-east-1 + disable_rollback: true + template_body: "{{ lookup('template', 'cloudformation.j2') }}" + template_parameters: + KeyName: jmartin + DiskType: ephemeral + InstanceType: m1.small + ClusterSize: 3 + tags: + Stack: ansible-cloudformation + + # Pass a template parameter which uses CloudFormation's UsePreviousValue attribute + # When use_previous_value is set to True, the given value will be ignored and + # CloudFormation will use the value from a previously submitted template. + # If use_previous_value is set to False (default) the given value is used. + - amazon.aws.cloudformation: + stack_name: "ansible-cloudformation" + state: "present" + region: "us-east-1" + template: "files/cloudformation-example.json" + template_parameters: + DBSnapshotIdentifier: + use_previous_value: True + value: arn:aws:rds:es-east-1:000000000000:snapshot:rds:my-db-snapshot + DBName: + use_previous_value: True + tags: + Stack: "ansible-cloudformation" + + # Enable termination protection on a stack. + # If the stack already exists, this will update its termination protection + - name: enable termination protection during stack creation + amazon.aws.cloudformation: + stack_name: my_stack + state: present + template_url: https://s3.amazonaws.com/my-bucket/cloudformation.template + termination_protection: yes + + # Configure TimeoutInMinutes before the stack status becomes CREATE_FAILED + # In this case, if disable_rollback is not set or is set to false, the stack will be rolled back. + - name: enable termination protection during stack creation + amazon.aws.cloudformation: + stack_name: my_stack + state: present + template_url: https://s3.amazonaws.com/my-bucket/cloudformation.template + create_timeout: 5 + + # Configure rollback behaviour on the unsuccessful creation of a stack allowing + # CloudFormation to clean up, or do nothing in the event of an unsuccessful + # deployment + # In this case, if on_create_failure is set to "DELETE", it will clean up the stack if + # it fails to create + - name: create stack which will delete on creation failure + amazon.aws.cloudformation: + stack_name: my_stack + state: present + template_url: https://s3.amazonaws.com/my-bucket/cloudformation.template + on_create_failure: DELETE + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>change_set_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td><em>state=present</em> and <em>create_changeset=true</em></td> + <td> + <div>The ID of the stack change set if one was created</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">arn:aws:cloudformation:us-east-1:012345678901:changeSet/Ansible-StackName-f4496805bd1b2be824d1e315c6884247ede41eb0</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>events</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>always</td> + <td> + <div>Most recent events in CloudFormation's event log. This may be from a previous run in some cases.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">['StackEvent AWS::CloudFormation::Stack stackname UPDATE_COMPLETE', 'StackEvent AWS::CloudFormation::Stack stackname UPDATE_COMPLETE_CLEANUP_IN_PROGRESS']</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>log</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>always</td> + <td> + <div>Debugging logs. Useful when modifying or finding an error.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">['updating stack']</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>stack_outputs</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>state == present</td> + <td> + <div>A key:value dictionary of all the stack outputs currently defined. If there are no stack outputs, it is an empty dictionary.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'MySg': 'AnsibleModuleTestYAML-CFTestSg-C8UVS567B6NS'}</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>stack_resources</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>state == present</td> + <td> + <div>AWS stack resources and their status. List of dictionaries, one dict per resource.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">[{'last_updated_time': '2016-10-11T19:40:14.979000+00:00', 'logical_resource_id': 'CFTestSg', 'physical_resource_id': 'cloudformation2-CFTestSg-16UQ4CYQ57O9F', 'resource_type': 'AWS::EC2::SecurityGroup', 'status': 'UPDATE_COMPLETE', 'status_reason': None}]</div> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- James S. Martin (@jsmartin) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_ami_info_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_ami_info_module.rst new file mode 100644 index 00000000..ff8702ff --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_ami_info_module.rst @@ -0,0 +1,801 @@ +.. _amazon.aws.ec2_ami_info_module: + + +*********************** +amazon.aws.ec2_ami_info +*********************** + +**Gather information about ec2 AMIs** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Gather information about ec2 AMIs +- This module was called ``amazon.aws.ec2_ami_facts`` before Ansible 2.9. The usage did not change. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>describe_image_attributes</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Describe attributes (like launchPermission) of the images found.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>executable_users</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>Filter images by users with explicit launch permissions. Valid options are an AWS account ID, self, or all (public AMIs).</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: executable_user</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>filters</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dict of filters to apply. Each dict item consists of a filter key and a filter value.</div> + <div>See <a href='https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html'>https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html</a> for possible filters.</div> + <div>Filter names and values are case sensitive.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>image_ids</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>One or more image IDs.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: image_id</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>owners</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>Filter the images by the owner. Valid options are an AWS account ID, self, or an AWS owner alias ( amazon | aws-marketplace | microsoft ).</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: owner</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + - name: gather information about an AMI using ami-id + amazon.aws.ec2_ami_info: + image_ids: ami-5b488823 + + - name: gather information about all AMIs with tag key Name and value webapp + amazon.aws.ec2_ami_info: + filters: + "tag:Name": webapp + + - name: gather information about an AMI with 'AMI Name' equal to foobar + amazon.aws.ec2_ami_info: + filters: + name: foobar + + - name: gather information about Ubuntu 17.04 AMIs published by Canonical (099720109477) + amazon.aws.ec2_ami_info: + owners: 099720109477 + filters: + name: "ubuntu/images/ubuntu-zesty-17.04-*" + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="3">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>images</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>A list of images.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>architecture</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The architecture of the image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">x86_64</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>block_device_mappings</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>Any block device mapping entries.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>device_name</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The device name exposed to the instance.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">/dev/sda1</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ebs</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">complex</span> + </div> + </td> + <td>always</td> + <td> + <div>EBS volumes</div> + <br/> + </td> + </tr> + + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>creation_date</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The date and time the image was created.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">2017-10-16T19:22:13.000Z</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>description</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The description of the AMI.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ena_support</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>Whether enhanced networking with ENA is enabled.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">True</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>hypervisor</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The hypervisor type of the image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">xen</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>image_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The ID of the AMI.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">ami-5b466623</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>image_location</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The location of the AMI.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">408466080000/Webapp</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>image_type</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The type of image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">machine</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>launch_permissions</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=dictionary</span> + </div> + </td> + <td>When image is owned by calling account and <em>describe_image_attributes</em> is yes.</td> + <td> + <div>A List of AWS accounts may launch the AMI.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">[{'group': 'all'}, {'user_id': '408466080000'}]</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>group</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>A value of 'all' means the AMI is public.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>user_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>An AWS account ID with permissions to launch the AMI.</div> + <br/> + </td> + </tr> + + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>name</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The name of the AMI that was provided during image creation.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">Webapp</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>owner_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The AWS account ID of the image owner.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">408466080000</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>public</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>Whether the image has public launch permissions.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">True</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>root_device_name</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The device name of the root device.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">/dev/sda1</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>root_device_type</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The type of root device used by the AMI.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">ebs</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>sriov_net_support</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>Whether enhanced networking is enabled.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">simple</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The current state of the AMI.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">available</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>Any tags assigned to the image.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>virtualization_type</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The type of virtualization of the AMI.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">hvm</div> + </td> + </tr> + + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Prasad Katti (@prasadkatti) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_ami_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_ami_module.rst new file mode 100644 index 00000000..1edb5d24 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_ami_module.rst @@ -0,0 +1,1176 @@ +.. _amazon.aws.ec2_ami_module: + + +****************** +amazon.aws.ec2_ami +****************** + +**Create or destroy an image (AMI) in ec2** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Registers or deregisters ec2 images. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.6 +- boto + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="2">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>architecture</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"x86_64"</div> + </td> + <td> + <div>The target architecture of the image to register</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>billing_products</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>A list of valid billing codes. To be used with valid accounts by aws marketplace vendors.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>delete_snapshot</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Delete snapshots when deregistering the AMI.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>description</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Human-readable string describing the contents and purpose of the AMI.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>device_mapping</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>List of device hashes/dictionaries with custom configurations (same block-device-mapping parameters).</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>delete_on_termination</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + </td> + <td> + <div>Whether the device should be automatically deleted when the Instance is terminated.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>device_name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + </td> + <td> + <div>The device name. For example <code>/dev/sda</code>.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: DeviceName</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>encrypted</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + </td> + <td> + <div>Whether the volume should be encrypted.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>iops</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>When using an <code>io1</code> <em>volume_type</em> this sets the number of IOPS provisioned for the volume</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>no_device</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + </td> + <td> + <div>Suppresses the specified device included in the block device mapping of the AMI.</div> + <div>Alias <code>NoDevice</code> has been deprecated and will be removed after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: NoDevice</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>snapshot_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The ID of the Snapshot.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>virtual_name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The virtual name for the device.</div> + <div>See the AWS documentation for more detail <a href='https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html'>https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html</a>.</div> + <div>Alias <code>VirtualName</code> has been deprecated and will be removed after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: VirtualName</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>volume_size</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>The size of the volume (in GiB)</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: size</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>volume_type</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The volume type. Defaults to <code>gp2</code> when not set.</div> + </td> + </tr> + + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>enhanced_networking</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + </td> + <td> + <div>A boolean representing whether enhanced networking with ENA is enabled or not.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>image_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Image ID to be deregistered.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>image_location</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The s3 location of an image to use for the AMI.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>instance_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Instance ID to create the AMI from.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>kernel_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The target kernel id of the image to register.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>launch_permissions</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>Users and groups that should be able to launch the AMI. Expects dictionary with a key of user_ids and/or group_names. user_ids should be a list of account ids. group_name should be a list of groups, "all" is the only acceptable value currently.</div> + <div>You must pass all desired launch permissions if you wish to modify existing launch permissions (passing just groups will remove all users)</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The name of the new AMI.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>no_reboot</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Flag indicating that the bundling process should not attempt to shutdown the instance before bundling. If this flag is True, the responsibility of maintaining file system integrity is left to the owner of the instance.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>purge_tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Whether to remove existing tags that aren't passed in the <code>tags</code> parameter</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ramdisk_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The ID of the RAM disk.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>root_device_name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The root device name of the image to register.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>sriov_net_support</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Set to simple to enable enhanced networking with the Intel 82599 Virtual Function interface for the AMI and any instances that you launch from the AMI.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>absent</li> + <li><div style="color: blue"><b>present</b> ←</div></li> + </ul> + </td> + <td> + <div>Register or deregister an AMI.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary of tags to add to the new image; '{"key":"value"}' and '{"key":"value","key":"value"}'</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>virtualization_type</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">"hvm"</div> + </td> + <td> + <div>The virtualization type of the image to register.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>wait</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Wait for the AMI to be in state 'available' before returning.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>wait_timeout</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">1200</div> + </td> + <td> + <div>How long before wait gives up, in seconds.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + - name: Basic AMI Creation + amazon.aws.ec2_ami: + instance_id: i-xxxxxx + wait: yes + name: newtest + tags: + Name: newtest + Service: TestService + + - name: Basic AMI Creation, without waiting + amazon.aws.ec2_ami: + instance_id: i-xxxxxx + wait: no + name: newtest + + - name: AMI Registration from EBS Snapshot + amazon.aws.ec2_ami: + name: newtest + state: present + architecture: x86_64 + virtualization_type: hvm + root_device_name: /dev/xvda + device_mapping: + - device_name: /dev/xvda + volume_size: 8 + snapshot_id: snap-xxxxxxxx + delete_on_termination: true + volume_type: gp2 + + - name: AMI Creation, with a custom root-device size and another EBS attached + amazon.aws.ec2_ami: + instance_id: i-xxxxxx + name: newtest + device_mapping: + - device_name: /dev/sda1 + size: XXX + delete_on_termination: true + volume_type: gp2 + - device_name: /dev/sdb + size: YYY + delete_on_termination: false + volume_type: gp2 + + - name: AMI Creation, excluding a volume attached at /dev/sdb + amazon.aws.ec2_ami: + instance_id: i-xxxxxx + name: newtest + device_mapping: + - device_name: /dev/sda1 + size: XXX + delete_on_termination: true + volume_type: gp2 + - device_name: /dev/sdb + no_device: yes + + - name: Deregister/Delete AMI (keep associated snapshots) + amazon.aws.ec2_ami: + image_id: "{{ instance.image_id }}" + delete_snapshot: False + state: absent + + - name: Deregister AMI (delete associated snapshots too) + amazon.aws.ec2_ami: + image_id: "{{ instance.image_id }}" + delete_snapshot: True + state: absent + + - name: Update AMI Launch Permissions, making it public + amazon.aws.ec2_ami: + image_id: "{{ instance.image_id }}" + state: present + launch_permissions: + group_names: ['all'] + + - name: Allow AMI to be launched by another account + amazon.aws.ec2_ami: + image_id: "{{ instance.image_id }}" + state: present + launch_permissions: + user_ids: ['123456789012'] + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>architecture</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>Architecture of image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">x86_64</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>block_device_mapping</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>Block device mapping associated with image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'/dev/sda1': {'delete_on_termination': True, 'encrypted': False, 'size': 10, 'snapshot_id': 'snap-1a03b80e7', 'volume_type': 'standard'}}</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>creationDate</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>Creation date of image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">2015-10-15T22:43:44.000Z</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>description</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>Description of image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">nat-server</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>hypervisor</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>Type of hypervisor.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">xen</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>image_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>ID of the image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">ami-1234abcd</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>is_public</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>Whether image is public.</div> + <br/> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>launch_permission</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>Permissions allowing other accounts to access the AMI.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">[{'group': 'all'}]</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>location</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>Location of image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">315210894379/nat-server</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>name</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>AMI name of image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">nat-server</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ownerId</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>Owner of image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">435210894375</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>platform</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>Platform of image.</div> + <br/> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>root_device_name</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>Root device name of image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">/dev/sda1</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>root_device_type</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>Root device type of image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">ebs</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>snapshots_deleted</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>after AMI is deregistered, if <em>delete_snapshot=true</em></td> + <td> + <div>A list of snapshot ids deleted after deregistering image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">['snap-fbcccb8f', 'snap-cfe7cdb4']</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>State of image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">available</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>A dictionary of tags assigned to image.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'Env': 'devel', 'Name': 'nat-server'}</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>virtualization_type</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when AMI is created or already exists</td> + <td> + <div>Image virtualization type.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">hvm</div> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Evan Duffield (@scicoin-project) <eduffield@iacquire.com> +- Constantin Bugneac (@Constantin07) <constantin.bugneac@endava.com> +- Ross Williams (@gunzy83) <gunzy83au@gmail.com> +- Willem van Ketwich (@wilvk) <willvk@gmail.com> diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_elb_lb_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_elb_lb_module.rst new file mode 100644 index 00000000..0f26de99 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_elb_lb_module.rst @@ -0,0 +1,829 @@ +.. _amazon.aws.ec2_elb_lb_module: + + +********************* +amazon.aws.ec2_elb_lb +********************* + +**Creates, updates or destroys an Amazon ELB.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Returns information about the load balancer. +- Will be marked changed when called only if state is changed. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.6 +- boto + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>access_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>An associative array of access logs configuration settings (see examples).</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>connection_draining_timeout</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>Wait a specified timeout allowing connections to drain before terminating an instance.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cross_az_load_balancing</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + </td> + <td> + <div>Distribute load across all configured Availability Zones.</div> + <div>Defaults to <code>false</code>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>health_check</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>An associative array of health check configuration settings (see examples).</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>idle_timeout</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>ELB connections from clients and to servers are timed out after this amount of time.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>instance_ids</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>List of instance ids to attach to this ELB.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>listeners</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>List of ports/protocols for this ELB to listen on (see examples).</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + </td> + <td> + <div>The name of the ELB.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>purge_instance_ids</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Purge existing instance ids on ELB that are not found in instance_ids.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>purge_listeners</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>Purge existing listeners on ELB that are not found in listeners.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>purge_subnets</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Purge existing subnet on ELB that are not found in subnets.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>purge_zones</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Purge existing availability zones on ELB that are not found in zones.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>scheme</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>internal</li> + <li><div style="color: blue"><b>internet-facing</b> ←</div></li> + </ul> + </td> + <td> + <div>The scheme to use when creating the ELB. For a private VPC-visible ELB use <code>internal</code>.</div> + <div>If you choose to update your scheme with a different value the ELB will be destroyed and recreated. To update scheme you must use the option <em>wait</em>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_group_ids</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>A list of security groups to apply to the ELB.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_group_names</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>A list of security group names to apply to the ELB.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>absent</li> + <li>present</li> + </ul> + </td> + <td> + <div>Create or destroy the ELB.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>stickiness</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>An associative array of stickiness policy settings. Policy will be applied to all listeners (see examples).</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>subnets</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>A list of VPC subnets to use when creating ELB. Zones should be empty if using this.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>An associative array of tags. To delete all tags, supply an empty dict (<code>{}</code>).</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to <code>no</code>, SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>wait</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>When specified, Ansible will check the status of the load balancer to ensure it has been successfully removed from AWS.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>wait_timeout</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">60</div> + </td> + <td> + <div>Used in conjunction with wait. Number of seconds to wait for the ELB to be terminated.</div> + <div>A maximum of 600 seconds (10 minutes) is allowed.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>zones</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>List of availability zones to enable on this ELB.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: None of these examples set aws_access_key, aws_secret_key, or region. + # It is assumed that their matching environment variables are set. + + # Basic provisioning example (non-VPC) + + - amazon.aws.ec2_elb_lb: + name: "test-please-delete" + state: present + zones: + - us-east-1a + - us-east-1d + listeners: + - protocol: http # options are http, https, ssl, tcp + load_balancer_port: 80 + instance_port: 80 + proxy_protocol: True + - protocol: https + load_balancer_port: 443 + instance_protocol: http # optional, defaults to value of protocol setting + instance_port: 80 + # ssl certificate required for https or ssl + ssl_certificate_id: "arn:aws:iam::123456789012:server-certificate/company/servercerts/ProdServerCert" + + # Internal ELB example + + - amazon.aws.ec2_elb_lb: + name: "test-vpc" + scheme: internal + state: present + instance_ids: + - i-abcd1234 + purge_instance_ids: true + subnets: + - subnet-abcd1234 + - subnet-1a2b3c4d + listeners: + - protocol: http # options are http, https, ssl, tcp + load_balancer_port: 80 + instance_port: 80 + + # Configure a health check and the access logs + - amazon.aws.ec2_elb_lb: + name: "test-please-delete" + state: present + zones: + - us-east-1d + listeners: + - protocol: http + load_balancer_port: 80 + instance_port: 80 + health_check: + ping_protocol: http # options are http, https, ssl, tcp + ping_port: 80 + ping_path: "/index.html" # not required for tcp or ssl + response_timeout: 5 # seconds + interval: 30 # seconds + unhealthy_threshold: 2 + healthy_threshold: 10 + access_logs: + interval: 5 # minutes (defaults to 60) + s3_location: "my-bucket" # This value is required if access_logs is set + s3_prefix: "logs" + + # Ensure ELB is gone + - amazon.aws.ec2_elb_lb: + name: "test-please-delete" + state: absent + + # Ensure ELB is gone and wait for check (for default timeout) + - amazon.aws.ec2_elb_lb: + name: "test-please-delete" + state: absent + wait: yes + + # Ensure ELB is gone and wait for check with timeout value + - amazon.aws.ec2_elb_lb: + name: "test-please-delete" + state: absent + wait: yes + wait_timeout: 600 + + # Normally, this module will purge any listeners that exist on the ELB + # but aren't specified in the listeners parameter. If purge_listeners is + # false it leaves them alone + - amazon.aws.ec2_elb_lb: + name: "test-please-delete" + state: present + zones: + - us-east-1a + - us-east-1d + listeners: + - protocol: http + load_balancer_port: 80 + instance_port: 80 + purge_listeners: no + + # Normally, this module will leave availability zones that are enabled + # on the ELB alone. If purge_zones is true, then any extraneous zones + # will be removed + - amazon.aws.ec2_elb_lb: + name: "test-please-delete" + state: present + zones: + - us-east-1a + - us-east-1d + listeners: + - protocol: http + load_balancer_port: 80 + instance_port: 80 + purge_zones: yes + + # Creates a ELB and assigns a list of subnets to it. + - amazon.aws.ec2_elb_lb: + state: present + name: 'New ELB' + security_group_ids: 'sg-123456, sg-67890' + region: us-west-2 + subnets: 'subnet-123456,subnet-67890' + purge_subnets: yes + listeners: + - protocol: http + load_balancer_port: 80 + instance_port: 80 + + # Create an ELB with connection draining, increased idle timeout and cross availability + # zone load balancing + - amazon.aws.ec2_elb_lb: + name: "New ELB" + state: present + connection_draining_timeout: 60 + idle_timeout: 300 + cross_az_load_balancing: "yes" + region: us-east-1 + zones: + - us-east-1a + - us-east-1d + listeners: + - protocol: http + load_balancer_port: 80 + instance_port: 80 + + # Create an ELB with load balancer stickiness enabled + - amazon.aws.ec2_elb_lb: + name: "New ELB" + state: present + region: us-east-1 + zones: + - us-east-1a + - us-east-1d + listeners: + - protocol: http + load_balancer_port: 80 + instance_port: 80 + stickiness: + type: loadbalancer + enabled: yes + expiration: 300 + + # Create an ELB with application stickiness enabled + - amazon.aws.ec2_elb_lb: + name: "New ELB" + state: present + region: us-east-1 + zones: + - us-east-1a + - us-east-1d + listeners: + - protocol: http + load_balancer_port: 80 + instance_port: 80 + stickiness: + type: application + enabled: yes + cookie: SESSIONID + + # Create an ELB and add tags + - amazon.aws.ec2_elb_lb: + name: "New ELB" + state: present + region: us-east-1 + zones: + - us-east-1a + - us-east-1d + listeners: + - protocol: http + load_balancer_port: 80 + instance_port: 80 + tags: + Name: "New ELB" + stack: "production" + client: "Bob" + + # Delete all tags from an ELB + - amazon.aws.ec2_elb_lb: + name: "New ELB" + state: present + region: us-east-1 + zones: + - us-east-1a + - us-east-1d + listeners: + - protocol: http + load_balancer_port: 80 + instance_port: 80 + tags: {} + + + + +Status +------ + + +Authors +~~~~~~~ + +- Jim Dalton (@jsdalton) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_eni_info_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_eni_info_module.rst new file mode 100644 index 00000000..b075c2cb --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_eni_info_module.rst @@ -0,0 +1,724 @@ +.. _amazon.aws.ec2_eni_info_module: + + +*********************** +amazon.aws.ec2_eni_info +*********************** + +**Gather information about ec2 ENI interfaces in AWS** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Gather information about ec2 ENI interfaces in AWS. +- This module was called ``ec2_eni_facts`` before Ansible 2.9. The usage did not change. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>eni_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 1.3.0</div> + </td> + <td> + </td> + <td> + <div>The ID of the ENI.</div> + <div>This option is mutually exclusive of <em>filters</em>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>filters</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dict of filters to apply. Each dict item consists of a filter key and a filter value. See <a href='https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeNetworkInterfaces.html'>https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeNetworkInterfaces.html</a> for possible filters.</div> + <div>This option is mutually exclusive of <em>eni_id</em>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + # Gather information about all ENIs + - amazon.aws.ec2_eni_info: + + # Gather information about a particular ENI + - amazon.aws.ec2_eni_info: + filters: + network-interface-id: eni-xxxxxxx + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="2">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>network_interfaces</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">complex</span> + </div> + </td> + <td>always</td> + <td> + <div>List of matching elastic network interfaces</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>association</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>When an ENI is associated with an EIP</td> + <td> + <div>Info of associated elastic IP (EIP)</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'allocation_id': 'eipalloc-5sdf123', 'association_id': 'eipassoc-8sdf123', 'ip_owner_id': '4415120123456', 'public_dns_name': 'ec2-52-1-0-63.compute-1.amazonaws.com', 'public_ip': '52.1.0.63'}</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>attachment</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>When an ENI is attached to an ec2 instance</td> + <td> + <div>Info about attached ec2 instance</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'attach_time': '2017-08-05T15:25:47+00:00', 'attachment_id': 'eni-attach-149d21234', 'delete_on_termination': False, 'device_index': 1, 'instance_id': 'i-15b8d3cadbafa1234', 'instance_owner_id': '4415120123456', 'status': 'attached'}</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>availability_zone</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>Availability zone of ENI</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">us-east-1b</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>description</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>Description text for ENI</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">My favourite network interface</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>groups</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>always</td> + <td> + <div>List of attached security groups</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">[{'group_id': 'sg-26d0f1234', 'group_name': 'my_ec2_security_group'}]</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The id of the ENI (alias for network_interface_id)</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">eni-392fsdf</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>interface_type</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>Type of the network interface</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">interface</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ipv6_addresses</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>always</td> + <td> + <div>List of IPv6 addresses for this interface</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>mac_address</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>MAC address of the network interface</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">0a:f8:10:2f:ab:a1</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>name</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 1.3.0</div> </td> + <td>When a Name tag has been set</td> + <td> + <div>The Name tag of the ENI, often displayed in the AWS UIs as Name</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>network_interface_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The id of the ENI</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">eni-392fsdf</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>owner_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>AWS account id of the owner of the ENI</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">4415120123456</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>private_dns_name</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>Private DNS name for the ENI</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">ip-172-16-1-180.ec2.internal</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>private_ip_address</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>Private IP address for the ENI</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">172.16.1.180</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>private_ip_addresses</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>always</td> + <td> + <div>List of private IP addresses attached to the ENI</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>requester_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The ID of the entity that launched the ENI</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">AIDAIONYVJQNIAZFT3ABC</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>requester_managed</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>Indicates whether the network interface is being managed by an AWS service.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>source_dest_check</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>Indicates whether the network interface performs source/destination checking.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>status</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>Indicates if the network interface is attached to an instance or not</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">in-use</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>subnet_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>Subnet ID the ENI is in</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">subnet-7bbf01234</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>tag_set</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>Dictionary of tags added to the ENI</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 1.3.0</div> </td> + <td>always</td> + <td> + <div>Dictionary of tags added to the ENI</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>vpc_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>ID of the VPC the network interface it part of</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">vpc-b3f1f123</div> + </td> + </tr> + + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Rob White (@wimnat) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_eni_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_eni_module.rst new file mode 100644 index 00000000..bc50a90e --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_eni_module.rst @@ -0,0 +1,932 @@ +.. _amazon.aws.ec2_eni_module: + + +****************** +amazon.aws.ec2_eni +****************** + +**Create and optionally attach an Elastic Network Interface (ENI) to an instance** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Create and optionally attach an Elastic Network Interface (ENI) to an instance. If an ENI ID or private_ip is provided, the existing ENI (if any) will be modified. The 'attached' parameter controls the attachment status of the network interface. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.6 +- boto + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>allow_reassignment</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Indicates whether to allow an IP address that is already assigned to another network interface or instance to be reassigned to the specified network interface.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>attached</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + </td> + <td> + <div>Specifies if network interface should be attached or detached from instance. If omitted, attachment status won't change</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>delete_on_termination</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + </td> + <td> + <div>Delete the interface when the instance it is attached to is terminated. You can only specify this flag when the interface is being modified, not on creation.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>description</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Optional description of the ENI.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>device_index</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">0</div> + </td> + <td> + <div>The index of the device for the network interface attachment on the instance.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>eni_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The ID of the ENI (to modify).</div> + <div>If <em>eni_id=None</em> and <em>state=present</em>, a new eni will be created.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>force_detach</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Force detachment of the interface. This applies either when explicitly detaching the interface by setting <em>instance_id=None</em> or when deleting an interface with <em>state=absent</em>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>instance_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Instance ID that you wish to attach ENI to.</div> + <div>Since version 2.2, use the <em>attached</em> parameter to attach or detach an ENI. Prior to 2.2, to detach an ENI from an instance, use <code>None</code>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Name for the ENI. This will create a tag called "Name" with the value assigned here.</div> + <div>This can be used in conjunction with <em>subnet_id</em> as another means of identifiying a network interface.</div> + <div>AWS does not enforce unique Name tags, so duplicate names are possible if you configure it that way. If that is the case, you will need to provide other identifying information such as <em>private_ip_address</em> or <em>eni_id</em>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>private_ip_address</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Private IP address.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>purge_secondary_private_ip_addresses</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>To be used with <em>secondary_private_ip_addresses</em> to determine whether or not to remove any secondary IP addresses other than those specified.</div> + <div>Set <em>secondary_private_ip_addresses=[]</em> to purge all secondary addresses.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>purge_tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 1.3.0</div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>Indicates whether to remove tags not specified in <em>tags</em> or <em>name</em>. This means you have to specify all the desired tags on each task affecting a network interface.</div> + <div>If <em>tags</em> is omitted or None this option is disregarded.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>secondary_private_ip_address_count</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>The number of secondary IP addresses to assign to the network interface. This option is mutually exclusive of <em>secondary_private_ip_addresses</em></div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>secondary_private_ip_addresses</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>A list of IP addresses to assign as secondary IP addresses to the network interface. This option is mutually exclusive of <em>secondary_private_ip_address_count</em></div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_groups</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>List of security groups associated with the interface. Only used when <em>state=present</em>.</div> + <div>Since version 2.2, you can specify security groups by ID or by name or a combination of both. Prior to 2.2, you can specify only by ID.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>source_dest_check</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + </td> + <td> + <div>By default, interfaces perform source/destination checks. NAT instances however need this check to be disabled. You can only specify this flag when the interface is being modified, not on creation.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>present</b> ←</div></li> + <li>absent</li> + </ul> + </td> + <td> + <div>Create or delete ENI.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>subnet_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>ID of subnet in which to create the ENI.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 1.3.0</div> + </td> + <td> + </td> + <td> + <div>A hash/dictionary of tags to add to the new ENI or to add/remove from an existing one. Please note that the name field sets the "Name" tag.</div> + <div>To clear all tags, set this option to an empty dictionary to use in conjunction with <em>purge_tags</em>. If you provide <em>name</em>, that tag will not be removed.</div> + <div>To prevent removing any tags set <em>purge_tags</em> to false.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - This module identifies and ENI based on either the *eni_id*, a combination of *private_ip_address* and *subnet_id*, or a combination of *instance_id* and *device_id*. Any of these options will let you specify a particular ENI. + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + # Create an ENI. As no security group is defined, ENI will be created in default security group + - amazon.aws.ec2_eni: + private_ip_address: 172.31.0.20 + subnet_id: subnet-xxxxxxxx + state: present + + # Create an ENI and attach it to an instance + - amazon.aws.ec2_eni: + instance_id: i-xxxxxxx + device_index: 1 + private_ip_address: 172.31.0.20 + subnet_id: subnet-xxxxxxxx + state: present + + # Create an ENI with two secondary addresses + - amazon.aws.ec2_eni: + subnet_id: subnet-xxxxxxxx + state: present + secondary_private_ip_address_count: 2 + + # Assign a secondary IP address to an existing ENI + # This will purge any existing IPs + - amazon.aws.ec2_eni: + subnet_id: subnet-xxxxxxxx + eni_id: eni-yyyyyyyy + state: present + secondary_private_ip_addresses: + - 172.16.1.1 + + # Remove any secondary IP addresses from an existing ENI + - amazon.aws.ec2_eni: + subnet_id: subnet-xxxxxxxx + eni_id: eni-yyyyyyyy + state: present + secondary_private_ip_address_count: 0 + + # Destroy an ENI, detaching it from any instance if necessary + - amazon.aws.ec2_eni: + eni_id: eni-xxxxxxx + force_detach: true + state: absent + + # Update an ENI + - amazon.aws.ec2_eni: + eni_id: eni-xxxxxxx + description: "My new description" + state: present + + # Update an ENI using name and subnet_id + - amazon.aws.ec2_eni: + name: eni-20 + subnet_id: subnet-xxxxxxx + description: "My new description" + state: present + + # Update an ENI identifying it by private_ip_address and subnet_id + - amazon.aws.ec2_eni: + subnet_id: subnet-xxxxxxx + private_ip_address: 172.16.1.1 + description: "My new description" + + # Detach an ENI from an instance + - amazon.aws.ec2_eni: + eni_id: eni-xxxxxxx + instance_id: None + state: present + + ### Delete an interface on termination + # First create the interface + - amazon.aws.ec2_eni: + instance_id: i-xxxxxxx + device_index: 1 + private_ip_address: 172.31.0.20 + subnet_id: subnet-xxxxxxxx + state: present + register: eni + + # Modify the interface to enable the delete_on_terminaton flag + - amazon.aws.ec2_eni: + eni_id: "{{ eni.interface.id }}" + delete_on_termination: true + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="2">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>interface</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">complex</span> + </div> + </td> + <td>when state != absent</td> + <td> + <div>Network interface attributes</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>description</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>interface description</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">Firewall network interface</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>groups</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=dictionary</span> + </div> + </td> + <td></td> + <td> + <div>list of security groups</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">[{'sg-f8a8a9da': 'default'}]</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>network interface id</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">eni-1d889198</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>mac_address</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>interface's physical address</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">00:00:5E:00:53:23</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>name</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The name of the ENI</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">my-eni-20</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>owner_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>aws account id</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">812381371</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>private_ip_address</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>primary ip address of this interface</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">10.20.30.40</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>private_ip_addresses</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=dictionary</span> + </div> + </td> + <td></td> + <td> + <div>list of all private ip addresses associated to this interface</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">[{'primary_address': True, 'private_ip_address': '10.20.30.40'}]</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>source_dest_check</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td></td> + <td> + <div>value of source/dest check flag</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">True</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>status</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>network interface status</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">pending</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>subnet_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>which vpc subnet the interface is bound</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">subnet-b0a0393c</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td></td> + <td> + <div>The dictionary of tags associated with the ENI</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'Name': 'my-eni', 'group': 'Finance'}</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>vpc_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>which vpc this network interface is bound</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">vpc-9a9a9da</div> + </td> + </tr> + + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Rob White (@wimnat) +- Mike Healey (@healem) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_group_info_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_group_info_module.rst new file mode 100644 index 00000000..0c4f7f9c --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_group_info_module.rst @@ -0,0 +1,342 @@ +.. _amazon.aws.ec2_group_info_module: + + +************************* +amazon.aws.ec2_group_info +************************* + +**Gather information about ec2 security groups in AWS.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Gather information about ec2 security groups in AWS. +- This module was called ``amazon.aws.ec2_group_facts`` before Ansible 2.9. The usage did not change. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>filters</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">{}</div> + </td> + <td> + <div>A dict of filters to apply. Each dict item consists of a filter key and a filter value. See <a href='https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSecurityGroups.html'>https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSecurityGroups.html</a> for possible filters. Filter names and values are case sensitive. You can also use underscores (_) instead of dashes (-) in the filter keys, which will take precedence in case of conflict.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - By default, the module will return all security groups. To limit results use the appropriate filters. + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + # Gather information about all security groups + - amazon.aws.ec2_group_info: + + # Gather information about all security groups in a specific VPC + - amazon.aws.ec2_group_info: + filters: + vpc-id: vpc-12345678 + + # Gather information about all security groups in a specific VPC + - amazon.aws.ec2_group_info: + filters: + vpc-id: vpc-12345678 + + # Gather information about a security group + - amazon.aws.ec2_group_info: + filters: + group-name: example-1 + + # Gather information about a security group by id + - amazon.aws.ec2_group_info: + filters: + group-id: sg-12345678 + + # Gather information about a security group with multiple filters, also mixing the use of underscores as filter keys + - amazon.aws.ec2_group_info: + filters: + group_id: sg-12345678 + vpc-id: vpc-12345678 + + # Gather information about various security groups + - amazon.aws.ec2_group_info: + filters: + group-name: + - example-1 + - example-2 + - example-3 + + # Gather information about any security group with a tag key Name and value Example. + # The quotes around 'tag:name' are important because of the colon in the value + - amazon.aws.ec2_group_info: + filters: + "tag:Name": Example + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>security_groups</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>always</td> + <td> + <div>Security groups that match the provided filters. Each element consists of a dict with all the information related to that security group.</div> + <br/> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Henrique Rodrigues (@Sodki) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_group_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_group_module.rst new file mode 100644 index 00000000..6472f309 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_group_module.rst @@ -0,0 +1,1042 @@ +.. _amazon.aws.ec2_group_module: + + +******************** +amazon.aws.ec2_group +******************** + +**maintain an ec2 VPC security group.** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Maintains ec2 security groups. This module has a dependency on python-boto >= 2.5. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="2">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>description</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Description of the security group. Required when <code>state</code> is <code>present</code>.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>group_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Id of group to delete (works only with absent).</div> + <div>One of and only one of <em>name</em> or <em>group_id</em> is required.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Name of the security group.</div> + <div>One of and only one of <em>name</em> or <em>group_id</em> is required.</div> + <div>Required if <em>state=present</em>.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>purge_rules</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + <b>Default:</b><br/><div style="color: blue">"true"</div> + </td> + <td> + <div>Purge existing rules on security group that are not found in rules.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>purge_rules_egress</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + <b>Default:</b><br/><div style="color: blue">"true"</div> + </td> + <td> + <div>Purge existing rules_egress on security group that are not found in rules_egress.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>purge_tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>If yes, existing tags will be purged from the resource to match exactly what is defined by <em>tags</em> parameter. If the <em>tags</em> parameter is not set then tags will not be modified.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>rules</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>List of firewall inbound rules to enforce in this group (see example). If none are supplied, no inbound rules will be enabled. Rules list may include its own name in `group_name`. This allows idempotent loopback additions (e.g. allow group to access itself). Rule sources list support was added in version 2.4. This allows to define multiple sources per source type as well as multiple source types per rule. Prior to 2.4 an individual source is allowed. In version 2.5 support for rule descriptions was added.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cidr_ip</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The IPv4 CIDR range traffic is coming from.</div> + <div>You can specify only one of <em>cidr_ip</em>, <em>cidr_ipv6</em>, <em>ip_prefix</em>, <em>group_id</em> and <em>group_name</em>.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cidr_ipv6</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The IPv6 CIDR range traffic is coming from.</div> + <div>You can specify only one of <em>cidr_ip</em>, <em>cidr_ipv6</em>, <em>ip_prefix</em>, <em>group_id</em> and <em>group_name</em>.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>from_port</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>The start of the range of ports that traffic is coming from. A value of <code>-1</code> indicates all ports.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>group_desc</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>If the <em>group_name</em> is set and the Security Group doesn't exist a new Security Group will be created with <em>group_desc</em> as the description.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>group_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The ID of the Security Group that traffic is coming from.</div> + <div>You can specify only one of <em>cidr_ip</em>, <em>cidr_ipv6</em>, <em>ip_prefix</em>, <em>group_id</em> and <em>group_name</em>.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>group_name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Name of the Security Group that traffic is coming from.</div> + <div>If the Security Group doesn't exist a new Security Group will be created with <em>group_desc</em> as the description.</div> + <div>You can specify only one of <em>cidr_ip</em>, <em>cidr_ipv6</em>, <em>ip_prefix</em>, <em>group_id</em> and <em>group_name</em>.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ip_prefix</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The IP Prefix <a href='https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-prefix-lists.html'>https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-prefix-lists.html</a> that traffic is coming from.</div> + <div>You can specify only one of <em>cidr_ip</em>, <em>cidr_ipv6</em>, <em>ip_prefix</em>, <em>group_id</em> and <em>group_name</em>.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>proto</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The IP protocol name (<code>tcp</code>, <code>udp</code>, <code>icmp</code>, <code>icmpv6</code>) or number (<a href='https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers'>https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers</a>)</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>rule_desc</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>A description for the rule.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>to_port</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>The end of the range of ports that traffic is coming from. A value of <code>-1</code> indicates all ports.</div> + </td> + </tr> + + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>rules_egress</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>List of firewall outbound rules to enforce in this group (see example). If none are supplied, a default all-out rule is assumed. If an empty list is supplied, no outbound rules will be enabled. Rule Egress sources list support was added in version 2.4. In version 2.5 support for rule descriptions was added.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cidr_ip</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The IPv4 CIDR range traffic is going to.</div> + <div>You can specify only one of <em>cidr_ip</em>, <em>cidr_ipv6</em>, <em>ip_prefix</em>, <em>group_id</em> and <em>group_name</em>.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cidr_ipv6</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The IPv6 CIDR range traffic is going to.</div> + <div>You can specify only one of <em>cidr_ip</em>, <em>cidr_ipv6</em>, <em>ip_prefix</em>, <em>group_id</em> and <em>group_name</em>.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>from_port</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>The start of the range of ports that traffic is going to. A value of <code>-1</code> indicates all ports.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>group_desc</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>If the <em>group_name</em> is set and the Security Group doesn't exist a new Security Group will be created with <em>group_desc</em> as the description.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>group_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The ID of the Security Group that traffic is going to.</div> + <div>You can specify only one of <em>cidr_ip</em>, <em>cidr_ipv6</em>, <em>ip_prefix</em>, <em>group_id</em> and <em>group_name</em>.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>group_name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Name of the Security Group that traffic is going to.</div> + <div>If the Security Group doesn't exist a new Security Group will be created with <em>group_desc</em> as the description.</div> + <div>You can specify only one of <em>cidr_ip</em>, <em>cidr_ipv6</em>, <em>ip_prefix</em>, <em>group_id</em> and <em>group_name</em>.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ip_prefix</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The IP Prefix <a href='https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-prefix-lists.html'>https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-prefix-lists.html</a> that traffic is going to.</div> + <div>You can specify only one of <em>cidr_ip</em>, <em>cidr_ipv6</em>, <em>ip_prefix</em>, <em>group_id</em> and <em>group_name</em>.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>proto</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The IP protocol name (<code>tcp</code>, <code>udp</code>, <code>icmp</code>, <code>icmpv6</code>) or number (<a href='https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers'>https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers</a>)</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>rule_desc</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>A description for the rule.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>to_port</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>The end of the range of ports that traffic is going to. A value of <code>-1</code> indicates all ports.</div> + </td> + </tr> + + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>present</b> ←</div></li> + <li>absent</li> + </ul> + </td> + <td> + <div>Create or delete a security group.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary of one or more tags to assign to the security group.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: resource_tags</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>vpc_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>ID of the VPC to create the group in.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If a rule declares a group_name and that group doesn't exist, it will be automatically created. In that case, group_desc should be provided as well. The module will refuse to create a depended-on group without a description. + - Preview diff mode support is added in version 2.7. + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + - name: example using security group rule descriptions + amazon.aws.ec2_group: + name: "{{ name }}" + description: sg with rule descriptions + vpc_id: vpc-xxxxxxxx + profile: "{{ aws_profile }}" + region: us-east-1 + rules: + - proto: tcp + ports: + - 80 + cidr_ip: 0.0.0.0/0 + rule_desc: allow all on port 80 + + - name: example ec2 group + amazon.aws.ec2_group: + name: example + description: an example EC2 group + vpc_id: 12345 + region: eu-west-1 + aws_secret_key: SECRET + aws_access_key: ACCESS + rules: + - proto: tcp + from_port: 80 + to_port: 80 + cidr_ip: 0.0.0.0/0 + - proto: tcp + from_port: 22 + to_port: 22 + cidr_ip: 10.0.0.0/8 + - proto: tcp + from_port: 443 + to_port: 443 + # this should only be needed for EC2 Classic security group rules + # because in a VPC an ELB will use a user-account security group + group_id: amazon-elb/sg-87654321/amazon-elb-sg + - proto: tcp + from_port: 3306 + to_port: 3306 + group_id: 123412341234/sg-87654321/exact-name-of-sg + - proto: udp + from_port: 10050 + to_port: 10050 + cidr_ip: 10.0.0.0/8 + - proto: udp + from_port: 10051 + to_port: 10051 + group_id: sg-12345678 + - proto: icmp + from_port: 8 # icmp type, -1 = any type + to_port: -1 # icmp subtype, -1 = any subtype + cidr_ip: 10.0.0.0/8 + - proto: all + # the containing group name may be specified here + group_name: example + - proto: all + # in the 'proto' attribute, if you specify -1, all, or a protocol number other than tcp, udp, icmp, or 58 (ICMPv6), + # traffic on all ports is allowed, regardless of any ports you specify + from_port: 10050 # this value is ignored + to_port: 10050 # this value is ignored + cidr_ip: 10.0.0.0/8 + + rules_egress: + - proto: tcp + from_port: 80 + to_port: 80 + cidr_ip: 0.0.0.0/0 + cidr_ipv6: 64:ff9b::/96 + group_name: example-other + # description to use if example-other needs to be created + group_desc: other example EC2 group + + - name: example2 ec2 group + amazon.aws.ec2_group: + name: example2 + description: an example2 EC2 group + vpc_id: 12345 + region: eu-west-1 + rules: + # 'ports' rule keyword was introduced in version 2.4. It accepts a single port value or a list of values including ranges (from_port-to_port). + - proto: tcp + ports: 22 + group_name: example-vpn + - proto: tcp + ports: + - 80 + - 443 + - 8080-8099 + cidr_ip: 0.0.0.0/0 + # Rule sources list support was added in version 2.4. This allows to define multiple sources per source type as well as multiple source types per rule. + - proto: tcp + ports: + - 6379 + - 26379 + group_name: + - example-vpn + - example-redis + - proto: tcp + ports: 5665 + group_name: example-vpn + cidr_ip: + - 172.16.1.0/24 + - 172.16.17.0/24 + cidr_ipv6: + - 2607:F8B0::/32 + - 64:ff9b::/96 + group_id: + - sg-edcd9784 + diff: True + + - name: "Delete group by its id" + amazon.aws.ec2_group: + region: eu-west-1 + group_id: sg-33b4ee5b + state: absent + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>description</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>on create/update</td> + <td> + <div>Description of security group</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">My Security Group</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>group_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>on create/update</td> + <td> + <div>Security group id</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">sg-abcd1234</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>group_name</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>on create/update</td> + <td> + <div>Security group name</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">My Security Group</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ip_permissions</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>on create/update</td> + <td> + <div>Inbound rules associated with the security group.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">[{'from_port': 8182, 'ip_protocol': 'tcp', 'ip_ranges': [{'cidr_ip': '198.51.100.1/32'}], 'ipv6_ranges': [], 'prefix_list_ids': [], 'to_port': 8182, 'user_id_group_pairs': []}]</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ip_permissions_egress</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>on create/update</td> + <td> + <div>Outbound rules associated with the security group.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">[{'ip_protocol': -1, 'ip_ranges': [{'cidr_ip': '0.0.0.0/0', 'ipv6_ranges': [], 'prefix_list_ids': [], 'user_id_group_pairs': []}]}]</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>owner_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td>on create/update</td> + <td> + <div>AWS Account ID of the security group</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">123456789012</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>on create/update</td> + <td> + <div>Tags associated with the security group</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'Name': 'My Security Group', 'Purpose': 'protecting stuff'}</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>vpc_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>on create/update</td> + <td> + <div>ID of VPC to which the security group belongs</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">vpc-abcd1234</div> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Andrew de Quincey (@adq) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_key_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_key_module.rst new file mode 100644 index 00000000..f05e37c5 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_key_module.rst @@ -0,0 +1,501 @@ +.. _amazon.aws.ec2_key_module: + + +****************** +amazon.aws.ec2_key +****************** + +**create or delete an ec2 key pair** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- create or delete an ec2 key pair. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>force</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>Force overwrite of already existing key pair if key has changed.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>key_material</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Public key material.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + </td> + <td> + <div>Name of the key pair.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>present</b> ←</div></li> + <li>absent</li> + </ul> + </td> + <td> + <div>create or delete keypair</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>wait</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + </td> + <td> + <div>This option has no effect since version 2.5 and will be removed after 2022-06-01.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>wait_timeout</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>This option has no effect since version 2.5 and will be removed after 2022-06-01.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + - name: create a new ec2 key pair, returns generated private key + amazon.aws.ec2_key: + name: my_keypair + + - name: create key pair using provided key_material + amazon.aws.ec2_key: + name: my_keypair + key_material: 'ssh-rsa AAAAxyz...== me@example.com' + + - name: create key pair using key_material obtained using 'file' lookup plugin + amazon.aws.ec2_key: + name: my_keypair + key_material: "{{ lookup('file', '/path/to/public_key/id_rsa.pub') }}" + + # try creating a key pair with the name of an already existing keypair + # but don't overwrite it even if the key is different (force=false) + - name: try creating a key pair with name of an already existing keypair + amazon.aws.ec2_key: + name: my_existing_keypair + key_material: 'ssh-rsa AAAAxyz...== me@example.com' + force: false + + - name: remove key pair by name + amazon.aws.ec2_key: + name: my_keypair + state: absent + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="2">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>changed</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>whether a keypair was created/deleted</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">True</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>key</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">complex</span> + </div> + </td> + <td>always</td> + <td> + <div>details of the keypair (this is set to null when state is absent)</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>fingerprint</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when state is present</td> + <td> + <div>fingerprint of the key</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">b0:22:49:61:d9:44:9d:0c:7e:ac:8a:32:93:21:6c:e8:fb:59:62:43</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>name</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when state is present</td> + <td> + <div>name of the keypair</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">my_keypair</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>private_key</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when a new keypair is created by AWS (key_material is not provided)</td> + <td> + <div>private key of a newly created keypair</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">-----BEGIN RSA PRIVATE KEY----- MIIEowIBAAKC... -----END RSA PRIVATE KEY-----</div> + </td> + </tr> + + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>msg</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>short message describing the action taken</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">key pair created</div> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Vincent Viallet (@zbal) +- Prasad Katti (@prasadkatti) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_metadata_facts_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_metadata_facts_module.rst new file mode 100644 index 00000000..56197455 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_metadata_facts_module.rst @@ -0,0 +1,1609 @@ +.. _amazon.aws.ec2_metadata_facts_module: + + +***************************** +amazon.aws.ec2_metadata_facts +***************************** + +**Gathers facts (instance metadata) about remote hosts within ec2** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- This module fetches data from the instance metadata endpoint in ec2 as per https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html. +- The module must be called from within the EC2 instance itself. + + + + + +Notes +----- + +.. note:: + - Parameters to filter on ec2_metadata_facts may be added later. + + + +Examples +-------- + +.. code-block:: yaml + + # Gather EC2 metadata facts + - amazon.aws.ec2_metadata_facts: + + - debug: + msg: "This instance is a t1.micro" + when: ansible_ec2_instance_type == "t1.micro" + + +Returned Facts +-------------- +Facts returned by this module are added/updated in the ``hostvars`` host facts and can be referenced by name just like any other host fact. They do not need to be registered in order to use them. + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="2">Fact</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_ami_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The AMI ID used to launch the instance. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">ami-XXXXXXXX</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_ami_launch_index</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>If you started more than one instance at the same time, this value indicates the order in which the instance was launched. + </div> + <div>The value of the first instance launched is 0. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">0</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_ami_manifest_path</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The path to the AMI manifest file in Amazon S3. + </div> + <div>If you used an Amazon EBS-backed AMI to launch the instance, the returned result is unknown. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">(unknown)</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_ancestor_ami_ids</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The AMI IDs of any instances that were rebundled to create this AMI. + </div> + <div>This value will only exist if the AMI manifest file contained an ancestor-amis key. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">(unknown)</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_block_device_mapping_ami</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The virtual device that contains the root/boot file system. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">/dev/sda1</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_block_device_mapping_ebsN</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The virtual devices associated with Amazon EBS volumes, if any are present. + </div> + <div>Amazon EBS volumes are only available in metadata if they were present at launch time or when the instance was last started. + </div> + <div>The N indicates the index of the Amazon EBS volume (such as ebs1 or ebs2). + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">/dev/xvdb</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_block_device_mapping_ephemeralN</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The virtual devices associated with ephemeral devices, if any are present. The N indicates the index of the ephemeral volume. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">/dev/xvdc</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_block_device_mapping_root</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The virtual devices or partitions associated with the root devices, or partitions on the virtual device, where the root (/ or C) file system is associated with the given instance. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">/dev/sda1</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_block_device_mapping_swap</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The virtual devices associated with swap. Not always present. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">/dev/sda2</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_fws_instance_monitoring</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>Value showing whether the customer has enabled detailed one-minute monitoring in CloudWatch. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">enabled</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_hostname</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The private IPv4 DNS hostname of the instance. + </div> + <div>In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">ip-10-0-0-1.ec2.internal</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_iam_info</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">complex</span> + </div> + </td> + <td></td> + <td> + <div>If there is an IAM role associated with the instance, contains information about the last time the instance profile was updated, including the instance's LastUpdated date, InstanceProfileArn, and InstanceProfileId. Otherwise, not present. + </div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1" colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>InstanceProfileArn</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The ARN of the InstanceProfile associated with the Instance. + </div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1" colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>InstanceProfileId</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The Id of the InstanceProfile associated with the Instance. + </div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1" colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>LastUpdated</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The last time which InstanceProfile is associated with the Instance changed. + </div> + <br/> + </td> + </tr> + + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_iam_info_instanceprofilearn</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The IAM instance profile ARN. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">arn:aws:iam::<account id>:instance-profile/<role name></div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_iam_info_instanceprofileid</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>IAM instance profile ID. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_iam_info_lastupdated</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>IAM info last updated time. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">2017-05-12T02:42:27Z</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_iam_instance_profile_role</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>IAM instance role. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">role_name</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_iam_security_credentials_<role name></b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>If there is an IAM role associated with the instance, role-name is the name of the role, and role-name contains the temporary security credentials associated with the role. Otherwise, not present. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_iam_security_credentials_<role name>_accesskeyid</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>IAM role access key ID. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_iam_security_credentials_<role name>_code</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>IAM code. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">Success</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_iam_security_credentials_<role name>_expiration</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>IAM role credentials expiration time. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">2017-05-12T09:11:41Z</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_iam_security_credentials_<role name>_lastupdated</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>IAM role last updated time. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">2017-05-12T02:40:44Z</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_iam_security_credentials_<role name>_secretaccesskey</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>IAM role secret access key. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_iam_security_credentials_<role name>_token</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>IAM role token. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_iam_security_credentials_<role name>_type</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>IAM role type. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">AWS-HMAC</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_action</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>Notifies the instance that it should reboot in preparation for bundling. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">none</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The ID of this instance. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">i-XXXXXXXXXXXXXXXXX</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_document</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>JSON containing instance attributes, such as instance-id, private IP address, etc. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_document_accountid</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div> + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">012345678901</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_document_architecture</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>Instance system architecture. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">x86_64</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_document_availabilityzone</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The Availability Zone in which the instance launched. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">us-east-1a</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_document_billingproducts</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>Billing products for this instance. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_document_devpayproductcodes</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>Product codes for the launched AMI. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_document_imageid</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The AMI ID used to launch the instance. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">ami-01234567</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_document_instanceid</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The ID of this instance. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">i-0123456789abcdef0</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_document_instancetype</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The type of instance. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">m4.large</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_document_kernelid</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The ID of the kernel launched with this instance, if applicable. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_document_pendingtime</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The instance pending time. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">2017-05-11T20:51:20Z</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_document_privateip</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The private IPv4 address of the instance. + </div> + <div>In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">10.0.0.1</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_document_ramdiskid</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The ID of the RAM disk specified at launch time, if applicable. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_document_region</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The Region in which the instance launched. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">us-east-1</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_document_version</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>Identity document version. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">2010-08-31</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_pkcs7</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>Used to verify the document's authenticity and content against the signature. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_rsa2048</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>Used to verify the document's authenticity and content against the signature. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_identity_signature</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>Data that can be used by other parties to verify its origin and authenticity. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_life_cycle</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The purchasing option of the instance. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">on-demand</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_instance_type</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The type of the instance. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">m4.large</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_local_hostname</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The private IPv4 DNS hostname of the instance. + </div> + <div>In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">ip-10-0-0-1.ec2.internal</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_local_ipv4</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The private IPv4 address of the instance. + </div> + <div>In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">10.0.0.1</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_mac</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The instance's media access control (MAC) address. + </div> + <div>In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">00:11:22:33:44:55</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_metrics_vhostmd</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>Metrics. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_device_number</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The unique device number associated with that interface. The device number corresponds to the device name; for example, a device-number of 2 is for the eth2 device. + </div> + <div>This category corresponds to the DeviceIndex and device-index fields that are used by the Amazon EC2 API and the EC2 commands for the AWS CLI. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">0</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_interface_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The elastic network interface ID. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">eni-12345678</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_ipv4_associations_<ip address></b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The private IPv4 addresses that are associated with each public-ip address and assigned to that interface. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_ipv6s</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The IPv6 addresses associated with the interface. Returned only for instances launched into a VPC. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_local_hostname</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The interface's local hostname. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_local_ipv4s</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The private IPv4 addresses associated with the interface. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_mac</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The instance's MAC address. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">00:11:22:33:44:55</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_owner_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The ID of the owner of the network interface. + </div> + <div>In multiple-interface environments, an interface can be attached by a third party, such as Elastic Load Balancing. + </div> + <div>Traffic on an interface is always billed to the interface owner. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">01234567890</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_public_hostname</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The interface's public DNS (IPv4). If the instance is in a VPC, this category is only returned if the enableDnsHostnames attribute is set to true. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">ec2-1-2-3-4.compute-1.amazonaws.com</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_public_ipv4s</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The Elastic IP addresses associated with the interface. There may be multiple IPv4 addresses on an instance. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">1.2.3.4</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_security_group_ids</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The IDs of the security groups to which the network interface belongs. Returned only for instances launched into a VPC. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">sg-01234567,sg-01234568</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_security_groups</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>Security groups to which the network interface belongs. Returned only for instances launched into a VPC. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">secgroup1,secgroup2</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_subnet_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The ID of the subnet in which the interface resides. Returned only for instances launched into a VPC. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">subnet-01234567</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_subnet_ipv4_cidr_block</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The IPv4 CIDR block of the subnet in which the interface resides. Returned only for instances launched into a VPC. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">10.0.1.0/24</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_subnet_ipv6_cidr_blocks</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The IPv6 CIDR block of the subnet in which the interface resides. Returned only for instances launched into a VPC. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_vpc_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The ID of the VPC in which the interface resides. Returned only for instances launched into a VPC. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">vpc-0123456</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_vpc_ipv4_cidr_block</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The IPv4 CIDR block of the VPC in which the interface resides. Returned only for instances launched into a VPC. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">10.0.0.0/16</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_vpc_ipv4_cidr_blocks</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The IPv4 CIDR block of the VPC in which the interface resides. Returned only for instances launched into a VPC. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">10.0.0.0/16</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_network_interfaces_macs_<mac address>_vpc_ipv6_cidr_blocks</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The IPv6 CIDR block of the VPC in which the interface resides. Returned only for instances launched into a VPC. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_placement_availability_zone</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The Availability Zone in which the instance launched. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">us-east-1a</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_placement_region</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The Region in which the instance launched. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">us-east-1</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_product_codes</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>Product codes associated with the instance, if any. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">aw0evgkw8e5c1q413zgy5pjce</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_profile</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>EC2 instance hardware profile. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">default-hvm</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_public_hostname</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The instance's public DNS. If the instance is in a VPC, this category is only returned if the enableDnsHostnames attribute is set to true. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">ec2-1-2-3-4.compute-1.amazonaws.com</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_public_ipv4</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The public IPv4 address. If an Elastic IP address is associated with the instance, the value returned is the Elastic IP address. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">1.2.3.4</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_public_key</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>Public key. Only available if supplied at instance launch time. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_ramdisk_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The ID of the RAM disk specified at launch time, if applicable. + </div> + <br/> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_reservation_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The ID of the reservation. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">r-0123456789abcdef0</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_security_groups</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The names of the security groups applied to the instance. After launch, you can only change the security groups of instances running in a VPC. + </div> + <div>Such changes are reflected here and in network/interfaces/macs/mac/security-groups. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">securitygroup1,securitygroup2</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_services_domain</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The domain for AWS resources for the region; for example, amazonaws.com for us-east-1. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">amazonaws.com</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_services_partition</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The partition that the resource is in. For standard AWS regions, the partition is aws. + </div> + <div>If you have resources in other partitions, the partition is aws-partitionname. + </div> + <div>For example, the partition for resources in the China (Beijing) region is aws-cn. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">aws</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_spot_termination_time</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The approximate time, in UTC, that the operating system for your Spot instance will receive the shutdown signal. + </div> + <div>This item is present and contains a time value only if the Spot instance has been marked for termination by Amazon EC2. + </div> + <div>The termination-time item is not set to a time if you terminated the Spot instance yourself. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">2015-01-05T18:02:00Z</div> + </td> + </tr> + <tr> + <td colspan="2" colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ansible_ec2_user_data</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this fact"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The instance user data. + </div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">#!/bin/bash</div> + </td> + </tr> + </table> + <br/><br/> + + + +Status +------ + + +Authors +~~~~~~~ + +- Silviu Dicu (@silviud) +- Vinay Dandekar (@roadmapper) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_module.rst new file mode 100644 index 00000000..6ba2ab4d --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_module.rst @@ -0,0 +1,1305 @@ +.. _amazon.aws.ec2_module: + + +************** +amazon.aws.ec2 +************** + +**create, terminate, start or stop an instance in ec2** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Creates or terminates ec2 instances. +- Note: This module uses the older boto Python module to interact with the EC2 API. :ref:`amazon.aws.ec2 <amazon.aws.ec2_module>` will still receive bug fixes, but no new features. Consider using the :ref:`amazon.aws.ec2_instance <amazon.aws.ec2_instance_module>` module instead. If :ref:`amazon.aws.ec2_instance <amazon.aws.ec2_instance_module>` does not support a feature you need that is available in :ref:`amazon.aws.ec2 <amazon.aws.ec2_module>`, please file a feature request. + + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.6 +- boto + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="2">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>assign_public_ip</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + </td> + <td> + <div>When provisioning within vpc, assign a public IP address. Boto library must be 2.13.0+.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>count</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">1</div> + </td> + <td> + <div>Number of instances to launch.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>count_tag</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">raw</span> + </div> + </td> + <td> + </td> + <td> + <div>Used with <em>exact_count</em> to determine how many nodes based on a specific tag criteria should be running. This can be expressed in multiple ways and is shown in the EXAMPLES section. For instance, one can request 25 servers that are tagged with <code>class=webserver</code>. The specified tag must already exist or be passed in as the <em>instance_tags</em> option.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ebs_optimized</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Whether instance is using optimized EBS volumes, see <a href='https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html'>https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html</a>.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>exact_count</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>An integer value which indicates how many instances that match the 'count_tag' parameter should be running. Instances are either created or terminated based on this value.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>group</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>Security group (or list of groups) to use with the instance.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: groups</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>group_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>Security group id (or list of ids) to use with the instance.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Identifier for this instance or set of instances, so that the module will be idempotent with respect to EC2 instances.</div> + <div>This identifier is valid for at least 24 hours after the termination of the instance, and should not be reused for another call later on.</div> + <div>For details, see the description of client token at <a href='https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Run_Instance_Idempotency.html'>https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Run_Instance_Idempotency.html</a>.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>image</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div><em>ami</em> ID to use for the instance.</div> + <div>Required when <em>state=present</em>.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>instance_ids</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>list of instance ids, currently used for states: absent, running, stopped</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: instance_id</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>instance_initiated_shutdown_behavior</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>stop</b> ←</div></li> + <li>terminate</li> + </ul> + </td> + <td> + <div>Set whether AWS will Stop or Terminate an instance on shutdown. This parameter is ignored when using instance-store. images (which require termination on shutdown).</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>instance_profile_name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Name of the IAM instance profile (i.e. what the EC2 console refers to as an "IAM Role") to use. Boto library must be 2.5.0+.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>instance_tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A hash/dictionary of tags to add to the new instance or for instances to start/stop by tag. For example <code>{"key":"value"}</code> or <code>{"key":"value","key2":"value2"}</code>.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>instance_type</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Instance type to use for the instance, see <a href='https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html'>https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html</a>.</div> + <div>Required when creating a new instance.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: type</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>kernel</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Kernel eki to use for the instance.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>key_name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Key pair to use on the instance.</div> + <div>The SSH key must already exist in AWS in order to use this argument.</div> + <div>Keys can be created / deleted using the <span class='module'>amazon.aws.ec2_key</span> module.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: keypair</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>monitoring</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Enable detailed monitoring (CloudWatch) for the instance.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>network_interfaces</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>A list of existing network interfaces to attach to the instance at launch. When specifying existing network interfaces, none of the <em>assign_public_ip</em>, <em>private_ip</em>, <em>vpc_subnet_id</em>, <em>group</em>, or <em>group_id</em> parameters may be used. (Those parameters are for creating a new network interface at launch.)</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: network_interface</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>placement_group</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Placement group for the instance when using EC2 Clustered Compute.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>private_ip</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The private ip address to assign the instance (from the vpc subnet).</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ramdisk</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Ramdisk eri to use for the instance.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>source_dest_check</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + </td> + <td> + <div>Enable or Disable the Source/Destination checks (for NAT instances and Virtual Routers). When initially creating an instance the EC2 API defaults this to <code>True</code>.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>spot_launch_group</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Launch group for spot requests, see <a href='https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/how-spot-instances-work.html#spot-launch-group'>https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/how-spot-instances-work.html#spot-launch-group</a>.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>spot_price</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Maximum spot price to bid. If not set, a regular on-demand instance is requested.</div> + <div>A spot request is made with this maximum bid. When it is filled, the instance is started.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>spot_type</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>one-time</b> ←</div></li> + <li>persistent</li> + </ul> + </td> + <td> + <div>The type of spot request.</div> + <div>After being interrupted a <code>persistent</code> spot instance will be started once there is capacity to fill the request again.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>spot_wait_timeout</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">600</div> + </td> + <td> + <div>How long to wait for the spot instance request to be fulfilled. Affects 'Request valid until' for setting spot request lifespan.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>absent</li> + <li><div style="color: blue"><b>present</b> ←</div></li> + <li>restarted</li> + <li>running</li> + <li>stopped</li> + </ul> + </td> + <td> + <div>Create, terminate, start, stop or restart instances. The state 'restarted' was added in Ansible 2.2.</div> + <div>When <em>state=absent</em>, <em>instance_ids</em> is required.</div> + <div>When <em>state=running</em>, <em>state=stopped</em> or <em>state=restarted</em> then either <em>instance_ids</em> or <em>instance_tags</em> is required.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>tenancy</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>default</b> ←</div></li> + <li>dedicated</li> + </ul> + </td> + <td> + <div>An instance with a tenancy of <code>dedicated</code> runs on single-tenant hardware and can only be launched into a VPC.</div> + <div>Note that to use dedicated tenancy you MUST specify a <em>vpc_subnet_id</em> as well.</div> + <div>Dedicated tenancy is not available for EC2 "micro" instances.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>termination_protection</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + </td> + <td> + <div>Enable or Disable the Termination Protection.</div> + <div>Defaults to <code>false</code>.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>user_data</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Opaque blob of data which is made available to the EC2 instance.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>volumes</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A list of hash/dictionaries of volumes to add to the new instance.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>delete_on_termination</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Whether the volume should be automatically deleted when the instance is terminated.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>device_name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + </td> + <td> + <div>A name for the device (For example <code>/dev/sda</code>).</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>encrypted</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Whether the volume should be encrypted using the 'aws/ebs' KMS CMK.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ephemeral</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Whether the volume should be ephemeral.</div> + <div>Data on ephemeral volumes is lost when the instance is stopped.</div> + <div>Mutually exclusive with the <em>snapshot</em> parameter.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>iops</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>The number of IOPS per second to provision for the volume.</div> + <div>Required when <em>volume_type=io1</em>.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>snapshot</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The ID of an EBS snapshot to copy when creating the volume.</div> + <div>Mutually exclusive with the <em>ephemeral</em> parameter.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>volume_size</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>The size of the volume (in GiB).</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>volume_type</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The type of volume to create.</div> + <div>See <a href='https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html'>https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html</a> for more information on the available volume types.</div> + </td> + </tr> + + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>vpc_subnet_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The subnet ID in which to launch the instance (VPC).</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>wait</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Wait for the instance to reach its desired state before returning.</div> + <div>Does not wait for SSH, see the 'wait_for_connection' example for details.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>wait_timeout</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">300</div> + </td> + <td> + <div>How long before wait gives up, in seconds.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>zone</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS availability zone in which to launch the instance.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_zone, ec2_zone</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + # Basic provisioning example + - amazon.aws.ec2: + key_name: mykey + instance_type: t2.micro + image: ami-123456 + wait: yes + group: webserver + count: 3 + vpc_subnet_id: subnet-29e63245 + assign_public_ip: yes + + # Advanced example with tagging and CloudWatch + - amazon.aws.ec2: + key_name: mykey + group: databases + instance_type: t2.micro + image: ami-123456 + wait: yes + wait_timeout: 500 + count: 5 + instance_tags: + db: postgres + monitoring: yes + vpc_subnet_id: subnet-29e63245 + assign_public_ip: yes + + # Single instance with additional IOPS volume from snapshot and volume delete on termination + - amazon.aws.ec2: + key_name: mykey + group: webserver + instance_type: c3.medium + image: ami-123456 + wait: yes + wait_timeout: 500 + volumes: + - device_name: /dev/sdb + snapshot: snap-abcdef12 + volume_type: io1 + iops: 1000 + volume_size: 100 + delete_on_termination: true + monitoring: yes + vpc_subnet_id: subnet-29e63245 + assign_public_ip: yes + + # Single instance with ssd gp2 root volume + - amazon.aws.ec2: + key_name: mykey + group: webserver + instance_type: c3.medium + image: ami-123456 + wait: yes + wait_timeout: 500 + volumes: + - device_name: /dev/xvda + volume_type: gp2 + volume_size: 8 + vpc_subnet_id: subnet-29e63245 + assign_public_ip: yes + count_tag: + Name: dbserver + exact_count: 1 + + # Multiple groups example + - amazon.aws.ec2: + key_name: mykey + group: ['databases', 'internal-services', 'sshable', 'and-so-forth'] + instance_type: m1.large + image: ami-6e649707 + wait: yes + wait_timeout: 500 + count: 5 + instance_tags: + db: postgres + monitoring: yes + vpc_subnet_id: subnet-29e63245 + assign_public_ip: yes + + # Multiple instances with additional volume from snapshot + - amazon.aws.ec2: + key_name: mykey + group: webserver + instance_type: m1.large + image: ami-6e649707 + wait: yes + wait_timeout: 500 + count: 5 + volumes: + - device_name: /dev/sdb + snapshot: snap-abcdef12 + volume_size: 10 + monitoring: yes + vpc_subnet_id: subnet-29e63245 + assign_public_ip: yes + + # Dedicated tenancy example + - amazon.aws.ec2: + assign_public_ip: yes + group_id: sg-1dc53f72 + key_name: mykey + image: ami-6e649707 + instance_type: m1.small + tenancy: dedicated + vpc_subnet_id: subnet-29e63245 + wait: yes + + # Spot instance example + - amazon.aws.ec2: + spot_price: 0.24 + spot_wait_timeout: 600 + keypair: mykey + group_id: sg-1dc53f72 + instance_type: m1.small + image: ami-6e649707 + wait: yes + vpc_subnet_id: subnet-29e63245 + assign_public_ip: yes + spot_launch_group: report_generators + instance_initiated_shutdown_behavior: terminate + + # Examples using pre-existing network interfaces + - amazon.aws.ec2: + key_name: mykey + instance_type: t2.small + image: ami-f005ba11 + network_interface: eni-deadbeef + + - amazon.aws.ec2: + key_name: mykey + instance_type: t2.small + image: ami-f005ba11 + network_interfaces: ['eni-deadbeef', 'eni-5ca1ab1e'] + + # Launch instances, runs some tasks + # and then terminate them + + - name: Create a sandbox instance + hosts: localhost + gather_facts: False + vars: + keypair: my_keypair + instance_type: m1.small + security_group: my_securitygroup + image: my_ami_id + region: us-east-1 + tasks: + - name: Launch instance + amazon.aws.ec2: + key_name: "{{ keypair }}" + group: "{{ security_group }}" + instance_type: "{{ instance_type }}" + image: "{{ image }}" + wait: true + region: "{{ region }}" + vpc_subnet_id: subnet-29e63245 + assign_public_ip: yes + register: ec2 + + - name: Add new instance to host group + add_host: + hostname: "{{ item.public_ip }}" + groupname: launched + loop: "{{ ec2.instances }}" + + - name: Wait for SSH to come up + delegate_to: "{{ item.public_dns_name }}" + wait_for_connection: + delay: 60 + timeout: 320 + loop: "{{ ec2.instances }}" + + - name: Configure instance(s) + hosts: launched + become: True + gather_facts: True + roles: + - my_awesome_role + - my_awesome_test + + - name: Terminate instances + hosts: localhost + tasks: + - name: Terminate instances that were previously launched + amazon.aws.ec2: + state: 'absent' + instance_ids: '{{ ec2.instance_ids }}' + + # Start a few existing instances, run some tasks + # and stop the instances + + - name: Start sandbox instances + hosts: localhost + gather_facts: false + vars: + instance_ids: + - 'i-xxxxxx' + - 'i-xxxxxx' + - 'i-xxxxxx' + region: us-east-1 + tasks: + - name: Start the sandbox instances + amazon.aws.ec2: + instance_ids: '{{ instance_ids }}' + region: '{{ region }}' + state: running + wait: True + vpc_subnet_id: subnet-29e63245 + assign_public_ip: yes + roles: + - do_neat_stuff + - do_more_neat_stuff + + - name: Stop sandbox instances + hosts: localhost + gather_facts: false + vars: + instance_ids: + - 'i-xxxxxx' + - 'i-xxxxxx' + - 'i-xxxxxx' + region: us-east-1 + tasks: + - name: Stop the sandbox instances + amazon.aws.ec2: + instance_ids: '{{ instance_ids }}' + region: '{{ region }}' + state: stopped + wait: True + vpc_subnet_id: subnet-29e63245 + assign_public_ip: yes + + # + # Start stopped instances specified by tag + # + - amazon.aws.ec2: + instance_tags: + Name: ExtraPower + state: running + + # + # Restart instances specified by tag + # + - amazon.aws.ec2: + instance_tags: + Name: ExtraPower + state: restarted + + # + # Enforce that 5 instances with a tag "foo" are running + # (Highly recommended!) + # + + - amazon.aws.ec2: + key_name: mykey + instance_type: c1.medium + image: ami-40603AD1 + wait: yes + group: webserver + instance_tags: + foo: bar + exact_count: 5 + count_tag: foo + vpc_subnet_id: subnet-29e63245 + assign_public_ip: yes + + # + # Enforce that 5 running instances named "database" with a "dbtype" of "postgres" + # + + - amazon.aws.ec2: + key_name: mykey + instance_type: c1.medium + image: ami-40603AD1 + wait: yes + group: webserver + instance_tags: + Name: database + dbtype: postgres + exact_count: 5 + count_tag: + Name: database + dbtype: postgres + vpc_subnet_id: subnet-29e63245 + assign_public_ip: yes + + # + # count_tag complex argument examples + # + + # instances with tag foo + - amazon.aws.ec2: + count_tag: + foo: + + # instances with tag foo=bar + - amazon.aws.ec2: + count_tag: + foo: bar + + # instances with tags foo=bar & baz + - amazon.aws.ec2: + count_tag: + foo: bar + baz: + + # instances with tags foo & bar & baz=bang + - amazon.aws.ec2: + count_tag: + - foo + - bar + - baz: bang + + + + +Status +------ + + +Authors +~~~~~~~ + +- Tim Gerla (@tgerla) +- Lester Wade (@lwade) +- Seth Vidal (@skvidal) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_snapshot_info_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_snapshot_info_module.rst new file mode 100644 index 00000000..67456665 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_snapshot_info_module.rst @@ -0,0 +1,604 @@ +.. _amazon.aws.ec2_snapshot_info_module: + + +**************************** +amazon.aws.ec2_snapshot_info +**************************** + +**Gather information about ec2 volume snapshots in AWS** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Gather information about ec2 volume snapshots in AWS. +- This module was called ``ec2_snapshot_facts`` before Ansible 2.9. The usage did not change. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>filters</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">{}</div> + </td> + <td> + <div>A dict of filters to apply. Each dict item consists of a filter key and a filter value. See <a href='https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSnapshots.html'>https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSnapshots.html</a> for possible filters. Filter names and values are case sensitive.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>owner_ids</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">[]</div> + </td> + <td> + <div>If you specify one or more snapshot owners, only snapshots from the specified owners and for which you have access are returned.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>restorable_by_user_ids</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">[]</div> + </td> + <td> + <div>If you specify a list of restorable users, only snapshots with create snapshot permissions for those users are returned.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>snapshot_ids</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">[]</div> + </td> + <td> + <div>If you specify one or more snapshot IDs, only snapshots that have the specified IDs are returned.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - By default, the module will return all snapshots, including public ones. To limit results to snapshots owned by the account use the filter 'owner-id'. + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + # Gather information about all snapshots, including public ones + - amazon.aws.ec2_snapshot_info: + + # Gather information about all snapshots owned by the account 0123456789 + - amazon.aws.ec2_snapshot_info: + filters: + owner-id: 0123456789 + + # Or alternatively... + - amazon.aws.ec2_snapshot_info: + owner_ids: + - 0123456789 + + # Gather information about a particular snapshot using ID + - amazon.aws.ec2_snapshot_info: + filters: + snapshot-id: snap-00112233 + + # Or alternatively... + - amazon.aws.ec2_snapshot_info: + snapshot_ids: + - snap-00112233 + + # Gather information about any snapshot with a tag key Name and value Example + - amazon.aws.ec2_snapshot_info: + filters: + "tag:Name": Example + + # Gather information about any snapshot with an error status + - amazon.aws.ec2_snapshot_info: + filters: + status: error + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>data_encryption_key_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The data encryption key identifier for the snapshot. This value is a unique identifier that corresponds to the data encryption key that was used to encrypt the original volume or snapshot copy.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">arn:aws:kms:ap-southeast-2:012345678900:key/74c9742a-a1b2-45cb-b3fe-abcdef123456</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>description</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The description for the snapshot.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">My important backup</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>encrypted</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>Indicates whether the snapshot is encrypted.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">True</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>kms_key_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The full ARN of the AWS Key Management Service (AWS KMS) customer master key (CMK) that was used to protect the volume encryption key for the parent volume.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">74c9742a-a1b2-45cb-b3fe-abcdef123456</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>owner_alias</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The AWS account alias (for example, amazon, self) or AWS account ID that owns the snapshot.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">033440102211</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>owner_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The AWS account ID of the EBS snapshot owner.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">099720109477</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>progress</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The progress of the snapshot, as a percentage.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">100%</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>snapshot_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The ID of the snapshot. Each snapshot receives a unique identifier when it is created.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">snap-01234567</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>start_time</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The time stamp when the snapshot was initiated.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">2015-02-12T02:14:02+00:00</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The snapshot state (completed, pending or error).</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">completed</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>state_message</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>Encrypted Amazon EBS snapshots are copied asynchronously. If a snapshot copy operation fails (for example, if the proper AWS Key Management Service (AWS KMS) permissions are not obtained) this field displays error state details to help you diagnose why the error occurred.</div> + <br/> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>Any tags assigned to the snapshot.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{ 'my_tag_key': 'my_tag_value' }</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>volume_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The ID of the volume that was used to create the snapshot.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">vol-01234567</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>volume_size</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td>always</td> + <td> + <div>The size of the volume, in GiB.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">8</div> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Rob White (@wimnat) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_snapshot_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_snapshot_module.rst new file mode 100644 index 00000000..1e97ed05 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_snapshot_module.rst @@ -0,0 +1,521 @@ +.. _amazon.aws.ec2_snapshot_module: + + +*********************** +amazon.aws.ec2_snapshot +*********************** + +**Creates a snapshot from an existing volume** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Creates an EC2 snapshot from an existing EBS volume. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.6 +- boto + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>description</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Description to be applied to the snapshot.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>device_name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Device name of a mounted volume to be snapshotted.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>instance_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Instance that has the required volume to snapshot mounted.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>last_snapshot_min_age</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">0</div> + </td> + <td> + <div>If the volume's most recent snapshot has started less than `last_snapshot_min_age' minutes ago, a new snapshot will not be created.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>snapshot_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Snapshot id to remove.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>snapshot_tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary of tags to add to the snapshot.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>absent</li> + <li><div style="color: blue"><b>present</b> ←</div></li> + </ul> + </td> + <td> + <div>Whether to add or create a snapshot.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>volume_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Volume from which to take the snapshot.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>wait</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>Wait for the snapshot to be ready.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>wait_timeout</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">0</div> + </td> + <td> + <div>How long before wait gives up, in seconds.</div> + <div>Specify 0 to wait forever.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Simple snapshot of volume using volume_id + - amazon.aws.ec2_snapshot: + volume_id: vol-abcdef12 + description: snapshot of /data from DB123 taken 2013/11/28 12:18:32 + + # Snapshot of volume mounted on device_name attached to instance_id + - amazon.aws.ec2_snapshot: + instance_id: i-12345678 + device_name: /dev/sdb1 + description: snapshot of /data from DB123 taken 2013/11/28 12:18:32 + + # Snapshot of volume with tagging + - amazon.aws.ec2_snapshot: + instance_id: i-12345678 + device_name: /dev/sdb1 + snapshot_tags: + frequency: hourly + source: /data + + # Remove a snapshot + - amazon.aws.ec2_snapshot: + snapshot_id: snap-abcd1234 + state: absent + + # Create a snapshot only if the most recent one is older than 1 hour + - amazon.aws.ec2_snapshot: + volume_id: vol-abcdef12 + last_snapshot_min_age: 60 + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>snapshot_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The ID of the snapshot. Each snapshot receives a unique identifier when it is created.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">snap-01234567</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>Any tags assigned to the snapshot.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{ 'Name': 'instance-name' }</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>volume_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The ID of the volume that was used to create the snapshot.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">vol-01234567</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>volume_size</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td>always</td> + <td> + <div>The size of the volume, in GiB.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">8</div> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Will Thames (@willthames) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_tag_info_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_tag_info_module.rst new file mode 100644 index 00000000..896d4f78 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_tag_info_module.rst @@ -0,0 +1,310 @@ +.. _amazon.aws.ec2_tag_info_module: + + +*********************** +amazon.aws.ec2_tag_info +*********************** + +**list tags on ec2 resources** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Lists tags for any EC2 resource. +- Resources are referenced by their resource id (e.g. an instance being i-XXXXXXX, a vpc being vpc-XXXXXX). +- Resource tags can be managed using the :ref:`amazon.aws.ec2_tag <amazon.aws.ec2_tag_module>` module. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- botocore +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>resource</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + </td> + <td> + <div>The EC2 resource id (for example i-XXXXXX or vpc-XXXXXX).</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + - name: Retrieve all tags on an instance + amazon.aws.ec2_tag_info: + region: eu-west-1 + resource: i-xxxxxxxxxxxxxxxxx + register: instance_tags + + - name: Retrieve all tags on a VPC + amazon.aws.ec2_tag_info: + region: eu-west-1 + resource: vpc-xxxxxxxxxxxxxxxxx + register: vpc_tags + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>A dict containing the tags on the resource</div> + <br/> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Mark Chappell (@tremble) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_tag_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_tag_module.rst new file mode 100644 index 00000000..d2f1bda7 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_tag_module.rst @@ -0,0 +1,431 @@ +.. _amazon.aws.ec2_tag_module: + + +****************** +amazon.aws.ec2_tag +****************** + +**create and remove tags on ec2 resources** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Creates, modifies and removes tags for any EC2 resource. +- Resources are referenced by their resource id (for example, an instance being i-XXXXXXX, a VPC being vpc-XXXXXXX). +- This module is designed to be used with complex args (tags), see the examples. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- botocore +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>purge_tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Whether unspecified tags should be removed from the resource.</div> + <div>Note that when combined with <em>state=absent</em>, specified tags with non-matching values are not purged.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>resource</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + </td> + <td> + <div>The EC2 resource id.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>present</b> ←</div></li> + <li>absent</li> + <li>list</li> + </ul> + </td> + <td> + <div>Whether the tags should be present or absent on the resource.</div> + <div>The use of <em>state=list</em> to interrogate the tags of an instance has been deprecated and will be removed after 2022-06-01. The 'list' functionality has been moved to a dedicated module <span class='module'>amazon.aws.ec2_tag_info</span>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary of tags to add or remove from the resource.</div> + <div>If the value provided for a key is not set and <em>state=absent</em>, the tag will be removed regardless of its current value.</div> + <div>Required when <em>state=present</em> or <em>state=absent</em>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + - name: Ensure tags are present on a resource + amazon.aws.ec2_tag: + region: eu-west-1 + resource: vol-XXXXXX + state: present + tags: + Name: ubervol + env: prod + + - name: Ensure all volumes are tagged + amazon.aws.ec2_tag: + region: eu-west-1 + resource: '{{ item.id }}' + state: present + tags: + Name: dbserver + Env: production + loop: '{{ ec2_vol.volumes }}' + + - name: Remove the Env tag + amazon.aws.ec2_tag: + region: eu-west-1 + resource: i-xxxxxxxxxxxxxxxxx + tags: + Env: + state: absent + + - name: Remove the Env tag if it's currently 'development' + amazon.aws.ec2_tag: + region: eu-west-1 + resource: i-xxxxxxxxxxxxxxxxx + tags: + Env: development + state: absent + + - name: Remove all tags except for Name from an instance + amazon.aws.ec2_tag: + region: eu-west-1 + resource: i-xxxxxxxxxxxxxxxxx + tags: + Name: '' + state: absent + purge_tags: true + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>added_tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>If tags were added</td> + <td> + <div>A dict of tags that were added to the resource</div> + <br/> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>removed_tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>If tags were removed</td> + <td> + <div>A dict of tags that were removed from the resource</div> + <br/> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>A dict containing the tags on the resource</div> + <br/> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Lester Wade (@lwade) +- Paul Arthur (@flowerysong) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vol_info_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vol_info_module.rst new file mode 100644 index 00000000..d1f0c2d3 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vol_info_module.rst @@ -0,0 +1,510 @@ +.. _amazon.aws.ec2_vol_info_module: + + +*********************** +amazon.aws.ec2_vol_info +*********************** + +**Gather information about ec2 volumes in AWS** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Gather information about ec2 volumes in AWS. +- This module was called ``ec2_vol_facts`` before Ansible 2.9. The usage did not change. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>filters</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dict of filters to apply. Each dict item consists of a filter key and a filter value.</div> + <div>See <a href='https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeVolumes.html'>https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeVolumes.html</a> for possible filters.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + # Gather information about all volumes + - amazon.aws.ec2_vol_info: + + # Gather information about a particular volume using volume ID + - amazon.aws.ec2_vol_info: + filters: + volume-id: vol-00112233 + + # Gather information about any volume with a tag key Name and value Example + - amazon.aws.ec2_vol_info: + filters: + "tag:Name": Example + + # Gather information about any volume that is attached + - amazon.aws.ec2_vol_info: + filters: + attachment.status: attached + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="2">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>volumes</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>Volumes that match the provided filters. Each element consists of a dict with all the information related to that volume.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>attachment_set</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td></td> + <td> + <div>Information about the volume attachments.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'attach_time': '2015-10-23T00:22:29.000Z', 'deleteOnTermination': 'false', 'device': '/dev/sdf', 'instance_id': 'i-8356263c', 'status': 'attached'}</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>create_time</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The time stamp when volume creation was initiated.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">2015-10-21T14:36:08.870Z</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>encrypted</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td></td> + <td> + <div>Indicates whether the volume is encrypted.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The ID of the volume.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">vol-35b333d9</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>iops</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td></td> + <td> + <div>The number of I/O operations per second (IOPS) that the volume supports.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>size</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td></td> + <td> + <div>The size of the volume, in GiBs.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">1</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>snapshot_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The snapshot from which the volume was created, if applicable.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>status</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The volume state.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">in-use</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td></td> + <td> + <div>Any tags assigned to the volume.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'env': 'dev'}</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>type</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The volume type. This can be gp2, io1, st1, sc1, or standard.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">standard</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>zone</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td></td> + <td> + <div>The Availability Zone of the volume.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">us-east-1b</div> + </td> + </tr> + + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Rob White (@wimnat) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vol_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vol_module.rst new file mode 100644 index 00000000..06533b86 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vol_module.rst @@ -0,0 +1,693 @@ +.. _amazon.aws.ec2_vol_module: + + +****************** +amazon.aws.ec2_vol +****************** + +**Create and attach a volume, return volume id and device map** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Creates an EBS volume and optionally attaches it to an instance. +- If both *instance* and *name* are given and the instance has a device at the device name, then no volume is created and no attachment is made. +- This module has a dependency on python-boto. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3>=1.16.33 +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>delete_on_termination</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>When set to <code>true</code>, the volume will be deleted upon instance termination.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>device_name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Device id to override device mapping. Assumes /dev/sdf for Linux/UNIX and /dev/xvdf for Windows.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>encrypted</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Enable encryption at rest for this volume.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Volume id if you wish to attach an existing volume (requires instance) or remove an existing volume</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>instance</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Instance ID if you wish to attach the volume. Since 1.9 you can set to None to detach.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>iops</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>The provisioned IOPs you want to associate with this volume (integer).</div> + <div>By default AWS will set this to 100.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>kms_key_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Specify the id of the KMS key to use.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>modify_volume</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 1.4.0</div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>The volume won't be modify unless this key is <code>true</code>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Volume Name tag if you wish to attach an existing volume (requires instance)</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>snapshot</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Snapshot ID on which to base the volume.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>absent</li> + <li><div style="color: blue"><b>present</b> ←</div></li> + <li>list</li> + </ul> + </td> + <td> + <div>Whether to ensure the volume is present or absent.</div> + <div>The use of <em>state=list</em> to interrogate the volume has been deprecated and will be removed after 2022-06-01. The 'list' functionality has been moved to a dedicated module <span class='module'>amazon.aws.ec2_vol_info</span>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">{}</div> + </td> + <td> + <div>tag:value pairs to add to the volume after creation.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>throughput</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 1.4.0</div> + </td> + <td> + </td> + <td> + <div>Volume throughput in MB/s.</div> + <div>This parameter is only valid for gp3 volumes.</div> + <div>Valid range is from 125 to 1000.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>volume_size</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>Size of volume (in GiB) to create.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>volume_type</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>standard</b> ←</div></li> + <li>gp2</li> + <li>io1</li> + <li>st1</li> + <li>sc1</li> + <li>gp3</li> + <li>io2</li> + </ul> + </td> + <td> + <div>Type of EBS volume; standard (magnetic), gp2 (SSD), gp3 (SSD), io1 (Provisioned IOPS), io2 (Provisioned IOPS), st1 (Throughput Optimized HDD), sc1 (Cold HDD). "Standard" is the old EBS default and continues to remain the Ansible default for backwards compatibility.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>zone</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Zone in which to create the volume, if unset uses the zone the instance is in (if set).</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: availability_zone, aws_zone, ec2_zone</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Simple attachment action + - amazon.aws.ec2_vol: + instance: XXXXXX + volume_size: 5 + device_name: sdd + region: us-west-2 + + # Example using custom iops params + - amazon.aws.ec2_vol: + instance: XXXXXX + volume_size: 5 + iops: 100 + device_name: sdd + region: us-west-2 + + # Example using snapshot id + - amazon.aws.ec2_vol: + instance: XXXXXX + snapshot: "{{ snapshot }}" + + # Playbook example combined with instance launch + - amazon.aws.ec2: + keypair: "{{ keypair }}" + image: "{{ image }}" + wait: yes + count: 3 + register: ec2 + - amazon.aws.ec2_vol: + instance: "{{ item.id }}" + volume_size: 5 + loop: "{{ ec2.instances }}" + register: ec2_vol + + # Example: Launch an instance and then add a volume if not already attached + # * Volume will be created with the given name if not already created. + # * Nothing will happen if the volume is already attached. + # * Requires Ansible 2.0 + + - amazon.aws.ec2: + keypair: "{{ keypair }}" + image: "{{ image }}" + zone: YYYYYY + id: my_instance + wait: yes + count: 1 + register: ec2 + + - amazon.aws.ec2_vol: + instance: "{{ item.id }}" + name: my_existing_volume_Name_tag + device_name: /dev/xvdf + loop: "{{ ec2.instances }}" + register: ec2_vol + + # Remove a volume + - amazon.aws.ec2_vol: + id: vol-XXXXXXXX + state: absent + + # Detach a volume (since 1.9) + - amazon.aws.ec2_vol: + id: vol-XXXXXXXX + instance: None + region: us-west-2 + + # List volumes for an instance + - amazon.aws.ec2_vol: + instance: i-XXXXXX + state: list + region: us-west-2 + + # Create new volume using SSD storage + - amazon.aws.ec2_vol: + instance: XXXXXX + volume_size: 50 + volume_type: gp2 + device_name: /dev/xvdf + + # Attach an existing volume to instance. The volume will be deleted upon instance termination. + - amazon.aws.ec2_vol: + instance: XXXXXX + id: XXXXXX + device_name: /dev/sdf + delete_on_termination: yes + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>device</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when success</td> + <td> + <div>device name of attached volume</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">/def/sdf</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>volume</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when success</td> + <td> + <div>a dictionary containing detailed attributes of the volume</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'attachment_set': {'attach_time': '2015-10-23T00:22:29.000Z', 'deleteOnTermination': 'false', 'device': '/dev/sdf', 'instance_id': 'i-8356263c', 'status': 'attached'}, 'create_time': '2015-10-21T14:36:08.870Z', 'encrypted': False, 'id': 'vol-35b333d9', 'iops': None, 'size': 1, 'snapshot_id': '', 'status': 'in-use', 'tags': {'env': 'dev'}, 'type': 'standard', 'zone': 'us-east-1b'}</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>volume_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when success</td> + <td> + <div>the id of volume</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">vol-35b333d9</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>volume_type</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when success</td> + <td> + <div>the volume type</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">standard</div> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Lester Wade (@lwade) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_dhcp_option_info_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_dhcp_option_info_module.rst new file mode 100644 index 00000000..38926339 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_dhcp_option_info_module.rst @@ -0,0 +1,370 @@ +.. _amazon.aws.ec2_vpc_dhcp_option_info_module: + + +*********************************** +amazon.aws.ec2_vpc_dhcp_option_info +*********************************** + +**Gather information about dhcp options sets in AWS** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Gather information about dhcp options sets in AWS. +- This module was called ``ec2_vpc_dhcp_option_facts`` before Ansible 2.9. The usage did not change. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>dhcp_options_ids</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>Get details of specific DHCP Option IDs.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: DhcpOptionIds</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>dry_run</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Checks whether you have the required permissions to view the DHCP Options.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: DryRun</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>filters</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dict of filters to apply. Each dict item consists of a filter key and a filter value. See <a href='https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeDhcpOptions.html'>https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeDhcpOptions.html</a> for possible filters.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # # Note: These examples do not set authentication details, see the AWS Guide for details. + + - name: Gather information about all DHCP Option sets for an account or profile + amazon.aws.ec2_vpc_dhcp_option_info: + region: ap-southeast-2 + profile: production + register: dhcp_info + + - name: Gather information about a filtered list of DHCP Option sets + amazon.aws.ec2_vpc_dhcp_option_info: + region: ap-southeast-2 + profile: production + filters: + "tag:Name": "abc-123" + register: dhcp_info + + - name: Gather information about a specific DHCP Option set by DhcpOptionId + amazon.aws.ec2_vpc_dhcp_option_info: + region: ap-southeast-2 + profile: production + DhcpOptionsIds: dopt-123fece2 + register: dhcp_info + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>changed</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>True if listing the dhcp options succeeds</div> + <br/> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>dhcp_options</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>always</td> + <td> + <div>The dhcp option sets for the account</div> + <br/> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Nick Aslanidis (@naslanidis) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_dhcp_option_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_dhcp_option_module.rst new file mode 100644 index 00000000..70f255be --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_dhcp_option_module.rst @@ -0,0 +1,551 @@ +.. _amazon.aws.ec2_vpc_dhcp_option_module: + + +****************************** +amazon.aws.ec2_vpc_dhcp_option +****************************** + +**Manages DHCP Options, and can ensure the DHCP options for the given VPC match what's requested** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- This module removes, or creates DHCP option sets, and can associate them to a VPC. Optionally, a new DHCP Options set can be created that converges a VPC's existing DHCP option set with values provided. When dhcp_options_id is provided, the module will 1. remove (with state='absent') 2. ensure tags are applied (if state='present' and tags are provided 3. attach it to a VPC (if state='present' and a vpc_id is provided. If any of the optional values are missing, they will either be treated as a no-op (i.e., inherit what already exists for the VPC) To remove existing options while inheriting, supply an empty value (e.g. set ntp_servers to [] if you want to remove them from the VPC's options) Most of the options should be self-explanatory. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>delete_old</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>Whether to delete the old VPC DHCP option set when associating a new one. This is primarily useful for debugging/development purposes when you want to quickly roll back to the old option set. Note that this setting will be ignored, and the old DHCP option set will be preserved, if it is in use by any other VPC. (Otherwise, AWS will return an error.)</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>dhcp_options_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The resource_id of an existing DHCP options set. If this is specified, then it will override other settings, except tags (which will be updated to match)</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>dns_servers</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>A list of hosts to set the DNS servers for the VPC to. (Should be a list of IP addresses rather than host names.)</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>domain_name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The domain name to set in the DHCP option sets</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>inherit_existing</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>For any DHCP options not specified in these parameters, whether to inherit them from the options set already applied to vpc_id, or to reset them to be empty.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>netbios_name_servers</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>List of hosts to advertise as NetBIOS servers.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>netbios_node_type</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + </td> + <td> + <div>NetBIOS node type to advertise in the DHCP options. The AWS recommendation is to use 2 (when using netbios name services) <a href='https://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_DHCP_Options.html'>https://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_DHCP_Options.html</a></div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ntp_servers</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>List of hosts to advertise as NTP servers for the VPC.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>absent</li> + <li><div style="color: blue"><b>present</b> ←</div></li> + </ul> + </td> + <td> + <div>create/assign or remove the DHCP options. If state is set to absent, then a DHCP options set matched either by id, or tags and options will be removed if possible.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>Tags to be applied to a VPC options set if a new one is created, or if the resource_id is provided. (options must match)</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: resource_tags</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>vpc_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>VPC ID to associate with the requested DHCP option set. If no vpc id is provided, and no matching option set is found then a new DHCP option set is created.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Completely overrides the VPC DHCP options associated with VPC vpc-123456 and deletes any existing + # DHCP option set that may have been attached to that VPC. + - amazon.aws.ec2_vpc_dhcp_option: + domain_name: "foo.example.com" + region: us-east-1 + dns_servers: + - 10.0.0.1 + - 10.0.1.1 + ntp_servers: + - 10.0.0.2 + - 10.0.1.2 + netbios_name_servers: + - 10.0.0.1 + - 10.0.1.1 + netbios_node_type: 2 + vpc_id: vpc-123456 + delete_old: True + inherit_existing: False + + + # Ensure the DHCP option set for the VPC has 10.0.0.4 and 10.0.1.4 as the specified DNS servers, but + # keep any other existing settings. Also, keep the old DHCP option set around. + - amazon.aws.ec2_vpc_dhcp_option: + region: us-east-1 + dns_servers: + - "{{groups['dns-primary']}}" + - "{{groups['dns-secondary']}}" + vpc_id: vpc-123456 + inherit_existing: True + delete_old: False + + + ## Create a DHCP option set with 4.4.4.4 and 8.8.8.8 as the specified DNS servers, with tags + ## but do not assign to a VPC + - amazon.aws.ec2_vpc_dhcp_option: + region: us-east-1 + dns_servers: + - 4.4.4.4 + - 8.8.8.8 + tags: + Name: google servers + Environment: Test + + ## Delete a DHCP options set that matches the tags and options specified + - amazon.aws.ec2_vpc_dhcp_option: + region: us-east-1 + dns_servers: + - 4.4.4.4 + - 8.8.8.8 + tags: + Name: google servers + Environment: Test + state: absent + + ## Associate a DHCP options set with a VPC by ID + - amazon.aws.ec2_vpc_dhcp_option: + region: us-east-1 + dhcp_options_id: dopt-12345678 + vpc_id: vpc-123456 + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>changed</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>Whether the dhcp options were changed</div> + <br/> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>dhcp_options_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>when available</td> + <td> + <div>The aws resource id of the primary DCHP options set created, found or removed</div> + <br/> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>new_options</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>when appropriate</td> + <td> + <div>The DHCP options created, associated or found</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'domain-name-servers': ['10.0.0.1', '10.0.1.1'], 'netbois-name-servers': ['10.0.0.1', '10.0.1.1'], 'netbios-node-type': 2, 'domain-name': 'my.example.com'}</div> + </td> + </tr> + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Joel Thompson (@joelthompson) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_net_info_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_net_info_module.rst new file mode 100644 index 00000000..87e599d7 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_net_info_module.rst @@ -0,0 +1,713 @@ +.. _amazon.aws.ec2_vpc_net_info_module: + + +*************************** +amazon.aws.ec2_vpc_net_info +*************************** + +**Gather information about ec2 VPCs in AWS** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Gather information about ec2 VPCs in AWS +- This module was called ``ec2_vpc_net_facts`` before Ansible 2.9. The usage did not change. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- botocore +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>filters</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dict of filters to apply. Each dict item consists of a filter key and a filter value. See <a href='https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeVpcs.html'>https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeVpcs.html</a> for possible filters.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>vpc_ids</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>A list of VPC IDs that exist in your account.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + # Gather information about all VPCs + - amazon.aws.ec2_vpc_net_info: + + # Gather information about a particular VPC using VPC ID + - amazon.aws.ec2_vpc_net_info: + vpc_ids: vpc-00112233 + + # Gather information about any VPC with a tag key Name and value Example + - amazon.aws.ec2_vpc_net_info: + filters: + "tag:Name": Example + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="4">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="4"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>vpcs</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">complex</span> + </div> + </td> + <td>success</td> + <td> + <div>Returns an array of complex objects as described below.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>cidr_block</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The IPv4 CIDR block assigned to the VPC.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>cidr_block_association_set</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">complex</span> + </div> + </td> + <td>always</td> + <td> + <div>An array of IPv4 cidr block association set information.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>association_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The association ID</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>cidr_block</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The IPv4 CIDR block that is associated with the VPC.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>cidr_block_state</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>A hash/dict that contains a single item. The state of the cidr block association.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The CIDR block association state.</div> + <br/> + </td> + </tr> + + + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>classic_link_dns_supported</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>True/False depending on attribute setting for classic link DNS support.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>classic_link_enabled</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>True/False depending on if classic link support is enabled.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>dhcp_options_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The ID of the DHCP options associated with this VPC.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">dopt-12345678</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>enable_dns_hostnames</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>True/False depending on attribute setting for DNS hostnames support.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>enable_dns_support</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>True/False depending on attribute setting for DNS support.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The ID of the VPC (for backwards compatibility).</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>instance_tenancy</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The instance tenancy setting for the VPC.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ipv6_cidr_block_association_set</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">complex</span> + </div> + </td> + <td>always</td> + <td> + <div>An array of IPv6 cidr block association set information.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>association_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The association ID</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ipv6_cidr_block</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The IPv6 CIDR block that is associated with the VPC.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ipv6_cidr_block_state</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>A hash/dict that contains a single item. The state of the cidr block association.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The CIDR block association state.</div> + <br/> + </td> + </tr> + + + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>is_default</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>True if this is the default VPC for account.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>owner_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The AWS account which owns the VPC.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">123456789012</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The state of the VPC.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>A dict of tags associated with the VPC.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>vpc_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The ID of the VPC .</div> + <br/> + </td> + </tr> + + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Rob White (@wimnat) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_net_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_net_module.rst new file mode 100644 index 00000000..864646f8 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_net_module.rst @@ -0,0 +1,711 @@ +.. _amazon.aws.ec2_vpc_net_module: + + +********************** +amazon.aws.ec2_vpc_net +********************** + +**Configure AWS virtual private clouds** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Create, modify, and terminate AWS virtual private clouds. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- botocore +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cidr_block</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + </td> + <td> + <div>The primary CIDR of the VPC. After 2.5 a list of CIDRs can be provided. The first in the list will be used as the primary CIDR and is used in conjunction with the <code>name</code> to ensure idempotence.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>dhcp_opts_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The id of the DHCP options to use for this VPC.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>dns_hostnames</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>Whether to enable AWS hostname support.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>dns_support</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>Whether to enable AWS DNS support.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ipv6_cidr</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Request an Amazon-provided IPv6 CIDR block with /56 prefix length. You cannot specify the range of IPv6 addresses, or the size of the CIDR block.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>multi_ok</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>By default the module will not create another VPC if there is another VPC with the same name and CIDR block. Specify this as true if you want duplicate VPCs created.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + </td> + <td> + <div>The name to give your VPC. This is used in combination with <code>cidr_block</code> to determine if a VPC already exists.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>purge_cidrs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Remove CIDRs that are associated with the VPC and are not specified in <code>cidr_block</code>.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>present</b> ←</div></li> + <li>absent</li> + </ul> + </td> + <td> + <div>The state of the VPC. Either absent or present.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>The tags you want attached to the VPC. This is independent of the name value, note if you pass a 'Name' key it would override the Name of the VPC if it's different.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: resource_tags</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>tenancy</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>default</b> ←</div></li> + <li>dedicated</li> + </ul> + </td> + <td> + <div>Whether to be default or dedicated tenancy. This cannot be changed after the VPC has been created.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + - name: create a VPC with dedicated tenancy and a couple of tags + amazon.aws.ec2_vpc_net: + name: Module_dev2 + cidr_block: 10.10.0.0/16 + region: us-east-1 + tags: + module: ec2_vpc_net + this: works + tenancy: dedicated + + - name: create a VPC with dedicated tenancy and request an IPv6 CIDR + amazon.aws.ec2_vpc_net: + name: Module_dev2 + cidr_block: 10.10.0.0/16 + ipv6_cidr: True + region: us-east-1 + tenancy: dedicated + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="3">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>vpc</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">complex</span> + </div> + </td> + <td>always</td> + <td> + <div>info about the VPC that was created or deleted</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>cidr_block</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The CIDR of the VPC</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">10.0.0.0/16</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>cidr_block_association_set</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>success</td> + <td> + <div>IPv4 CIDR blocks associated with the VPC</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'cidr_block_association_set': [{'association_id': 'vpc-cidr-assoc-97aeeefd', 'cidr_block': '10.0.0.0/24', 'cidr_block_state': {'state': 'associated'}}]}</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>classic_link_enabled</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>indicates whether ClassicLink is enabled</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>dhcp_options_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>the id of the DHCP options associated with this VPC</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">dopt-12345678</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>VPC resource id</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">vpc-12345678</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>instance_tenancy</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>indicates whether VPC uses default or dedicated tenancy</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">default</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ipv6_cidr_block_association_set</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + </div> + </td> + <td>success</td> + <td> + <div>IPv6 CIDR blocks associated with the VPC</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'ipv6_cidr_block_association_set': [{'association_id': 'vpc-cidr-assoc-97aeeefd', 'ipv6_cidr_block': '2001:db8::/56', 'ipv6_cidr_block_state': {'state': 'associated'}}]}</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>is_default</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>indicates whether this is the default VPC</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>owner_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The AWS account which owns the VPC.</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">123456789012</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>state of the VPC</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">available</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">complex</span> + </div> + </td> + <td>always</td> + <td> + <div>tags attached to the VPC, includes name</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>Name</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>name tag for the VPC</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">pk_vpc4</div> + </td> + </tr> + + + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Jonathan Davila (@defionscode) +- Sloane Hertel (@s-hertel) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_subnet_info_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_subnet_info_module.rst new file mode 100644 index 00000000..c537c4e6 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_subnet_info_module.rst @@ -0,0 +1,613 @@ +.. _amazon.aws.ec2_vpc_subnet_info_module: + + +****************************** +amazon.aws.ec2_vpc_subnet_info +****************************** + +**Gather information about ec2 VPC subnets in AWS** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Gather information about ec2 VPC subnets in AWS +- This module was called ``ec2_vpc_subnet_facts`` before Ansible 2.9. The usage did not change. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- botocore +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>filters</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dict of filters to apply. Each dict item consists of a filter key and a filter value. See <a href='https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSubnets.html'>https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSubnets.html</a> for possible filters.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>subnet_ids</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">list</span> + / <span style="color: purple">elements=string</span> + </div> + </td> + <td> + </td> + <td> + <div>A list of subnet IDs to gather information for.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: subnet_id</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + # Gather information about all VPC subnets + - amazon.aws.ec2_vpc_subnet_info: + + # Gather information about a particular VPC subnet using ID + - amazon.aws.ec2_vpc_subnet_info: + subnet_ids: subnet-00112233 + + # Gather information about any VPC subnet with a tag key Name and value Example + - amazon.aws.ec2_vpc_subnet_info: + filters: + "tag:Name": Example + + # Gather information about any VPC subnet within VPC with ID vpc-abcdef00 + - amazon.aws.ec2_vpc_subnet_info: + filters: + vpc-id: vpc-abcdef00 + + # Gather information about a set of VPC subnets, publicA, publicB and publicC within a + # VPC with ID vpc-abcdef00 and then use the jinja map function to return the + # subnet_ids as a list. + + - amazon.aws.ec2_vpc_subnet_info: + filters: + vpc-id: vpc-abcdef00 + "tag:Name": "{{ item }}" + loop: + - publicA + - publicB + - publicC + register: subnet_info + + - set_fact: + subnet_ids: "{{ subnet_info.subnets|map(attribute='id')|list }}" + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="4">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="4"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>subnets</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">complex</span> + </div> + </td> + <td>success</td> + <td> + <div>Returns an array of complex objects as described below.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>assign_ipv6_address_on_creation</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>True/False depending on attribute setting for IPv6 address assignment.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>availability_zone</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The availability zone where the subnet exists.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>available_ip_address_count</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>Count of available IPs in subnet.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>cidr_block</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The IPv4 CIDR block assigned to the subnet.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>default_for_az</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>True if this is the default subnet for AZ.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The ID of the Subnet (for backwards compatibility).</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ipv6_cidr_block_association_set</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">complex</span> + </div> + </td> + <td>always</td> + <td> + <div>An array of IPv6 cidr block association set information.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>association_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The association ID</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ipv6_cidr_block</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The IPv6 CIDR block that is associated with the subnet.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ipv6_cidr_block_state</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>A hash/dict that contains a single item. The state of the cidr block association.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The CIDR block association state.</div> + <br/> + </td> + </tr> + + + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>map_public_ip_on_launch</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td>always</td> + <td> + <div>True/False depending on attribute setting for public IP mapping.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The state of the subnet.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>subnet_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The ID of the Subnet.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>A dict of tags associated with the Subnet.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>vpc_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The ID of the VPC .</div> + <br/> + </td> + </tr> + + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Rob White (@wimnat) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_subnet_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_subnet_module.rst new file mode 100644 index 00000000..a15e3e03 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.ec2_vpc_subnet_module.rst @@ -0,0 +1,799 @@ +.. _amazon.aws.ec2_vpc_subnet_module: + + +************************* +amazon.aws.ec2_vpc_subnet +************************* + +**Manage subnets in AWS virtual private clouds** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manage subnets in AWS virtual private clouds. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="1">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>assign_instances_ipv6</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Specify <code>yes</code> to indicate that instances launched into the subnet should be automatically assigned an IPv6 address.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>az</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The availability zone for the subnet.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>cidr</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + </td> + <td> + <div>The CIDR block for the subnet. E.g. 192.0.2.0/24.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ipv6_cidr</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The IPv6 CIDR block for the subnet. The VPC must have a /56 block assigned and this value must be a valid IPv6 /64 that falls in the VPC range.</div> + <div>Required if <em>assign_instances_ipv6=true</em></div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>map_public</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Specify <code>yes</code> to indicate that instances launched into the subnet should be assigned public IP address by default.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>purge_tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>Whether or not to remove tags that do not appear in the <em>tags</em> list.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>present</b> ←</div></li> + <li>absent</li> + </ul> + </td> + <td> + <div>Create or remove the subnet.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dict of tags to apply to the subnet. Any tags currently applied to the subnet and not present here will be removed.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: resource_tags</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>vpc_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + </td> + <td> + <div>VPC ID of the VPC in which to create or delete the subnet.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>wait</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When <em>wait=true</em> and <em>state=present</em>, module will wait for subnet to be in available state before continuing.</div> + </td> + </tr> + <tr> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>wait_timeout</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">integer</span> + </div> + </td> + <td> + <b>Default:</b><br/><div style="color: blue">300</div> + </td> + <td> + <div>Number of seconds to wait for subnet to become available <em>wait=True</em>.</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + - name: Create subnet for database servers + amazon.aws.ec2_vpc_subnet: + state: present + vpc_id: vpc-123456 + cidr: 10.0.1.16/28 + tags: + Name: Database Subnet + register: database_subnet + + - name: Remove subnet for database servers + amazon.aws.ec2_vpc_subnet: + state: absent + vpc_id: vpc-123456 + cidr: 10.0.1.16/28 + + - name: Create subnet with IPv6 block assigned + amazon.aws.ec2_vpc_subnet: + state: present + vpc_id: vpc-123456 + cidr: 10.1.100.0/24 + ipv6_cidr: 2001:db8:0:102::/64 + + - name: Remove IPv6 block assigned to subnet + amazon.aws.ec2_vpc_subnet: + state: present + vpc_id: vpc-123456 + cidr: 10.1.100.0/24 + ipv6_cidr: '' + + + +Return Values +------------- +Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="4">Key</th> + <th>Returned</th> + <th width="100%">Description</th> + </tr> + <tr> + <td colspan="4"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>subnet</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">complex</span> + </div> + </td> + <td><em>state=present</em></td> + <td> + <div>Dictionary of subnet values</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>assign_ipv6_address_on_creation</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td><em>state=present</em></td> + <td> + <div>whether IPv6 address is auto-assigned to new instances</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>availability_zone</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td><em>state=present</em></td> + <td> + <div>Availability zone of the Subnet</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">us-east-1a</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>available_ip_address_count</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td><em>state=present</em></td> + <td> + <div>number of available IPv4 addresses</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">251</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>cidr_block</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td><em>state=present</em></td> + <td> + <div>The IPv4 CIDR of the Subnet</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">10.0.0.0/16</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>default_for_az</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td><em>state=present</em></td> + <td> + <div>indicates whether this is the default Subnet for this Availability Zone</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td><em>state=present</em></td> + <td> + <div>Subnet resource id</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">subnet-b883b2c4</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ipv6_association_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td><em>state=present</em></td> + <td> + <div>The IPv6 association ID for the currently associated CIDR</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">subnet-cidr-assoc-b85c74d2</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ipv6_cidr_block</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td><em>state=present</em></td> + <td> + <div>The IPv6 CIDR block actively associated with the Subnet</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">2001:db8:0:102::/64</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ipv6_cidr_block_association_set</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">complex</span> + </div> + </td> + <td><em>state=present</em></td> + <td> + <div>An array of IPv6 cidr block association set information.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>association_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The association ID</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ipv6_cidr_block</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The IPv6 CIDR block that is associated with the subnet.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>ipv6_cidr_block_state</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td>always</td> + <td> + <div>A hash/dict that contains a single item. The state of the cidr block association.</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td class="elbow-placeholder"> </td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td>always</td> + <td> + <div>The CIDR block association state.</div> + <br/> + </td> + </tr> + + + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>map_public_ip_on_launch</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td><em>state=present</em></td> + <td> + <div>whether public IP is auto-assigned to new instances</div> + <br/> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td><em>state=present</em></td> + <td> + <div>state of the Subnet</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">available</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td><em>state=present</em></td> + <td> + <div>tags attached to the Subnet, includes name</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'Name': 'My Subnet', 'env': 'staging'}</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"> </td> + <td colspan="3"> + <div class="ansibleOptionAnchor" id="return-"></div> + <b>vpc_id</b> + <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td><em>state=present</em></td> + <td> + <div>the id of the VPC where this Subnet exists</div> + <br/> + <div style="font-size: smaller"><b>Sample:</b></div> + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">vpc-67236184</div> + </td> + </tr> + + </table> + <br/><br/> + + +Status +------ + + +Authors +~~~~~~~ + +- Robert Estelle (@erydo) +- Brad Davidson (@brandond) diff --git a/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.s3_bucket_module.rst b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.s3_bucket_module.rst new file mode 100644 index 00000000..794a0125 --- /dev/null +++ b/collections-debian-merged/ansible_collections/amazon/aws/docs/amazon.aws.s3_bucket_module.rst @@ -0,0 +1,652 @@ +.. _amazon.aws.s3_bucket_module: + + +******************** +amazon.aws.s3_bucket +******************** + +**Manage S3 buckets in AWS, DigitalOcean, Ceph, Walrus, FakeS3 and StorageGRID** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manage S3 buckets in AWS, DigitalOcean, Ceph, Walrus, FakeS3 and StorageGRID. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- boto +- boto3 +- python >= 2.6 + + +Parameters +---------- + +.. raw:: html + + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th colspan="2">Parameter</th> + <th>Choices/<font color="blue">Defaults</font></th> + <th width="100%">Comments</th> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_access_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_access_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_access_key, access_key</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_ca_bundle</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">path</span> + </div> + </td> + <td> + </td> + <td> + <div>The location of a CA Bundle to use when validating SSL certificates.</div> + <div>Only used for boto3 based modules.</div> + <div>Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_config</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>A dictionary to modify the botocore configuration.</div> + <div>Parameters can be found at <a href='https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config'>https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config</a>.</div> + <div>Only the 'user_agent' key is used for boto modules. See <a href='http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto'>http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto</a> for more boto configuration.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>aws_secret_key</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>aws_secret_key</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: ec2_secret_key, secret_key</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ceph</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Enable API compatibility with Ceph. It takes into account the S3 API subset working with Ceph in order to provide the same module behaviour where possible.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>debug_botocore_endpoint_logs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>delete_public_access</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 1.3.0</div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Delete public access block configuration from bucket.</div> + <div>This option cannot be used together with a <em>public_access</em> definition.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ec2_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_endpoint_url, endpoint_url</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>encryption</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>none</li> + <li>AES256</li> + <li>aws:kms</li> + </ul> + </td> + <td> + <div>Describes the default server-side encryption to apply to new objects in the bucket. In order to remove the server-side encryption, the encryption needs to be set to 'none' explicitly.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>encryption_key_id</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>KMS master key ID to use for the default encryption. This parameter is allowed if <em>encryption</em> is <code>aws:kms</code>. If not specified then it will default to the AWS provided KMS key.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>force</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>When trying to delete a bucket, delete all keys (including versions and delete markers) in the bucket first (an S3 bucket must be empty for a successful deletion).</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>name</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + / <span style="color: red">required</span> + </div> + </td> + <td> + </td> + <td> + <div>Name of the S3 bucket.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>policy</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">json</span> + </div> + </td> + <td> + </td> + <td> + <div>The JSON policy as a string.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>profile</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>Uses a boto profile. Only works with boto >= 2.24.0.</div> + <div>Using <em>profile</em> will override <em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> and support for passing them at the same time as <em>profile</em> has been deprecated.</div> + <div><em>aws_access_key</em>, <em>aws_secret_key</em> and <em>security_token</em> will be made mutually exclusive with <em>profile</em> after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_profile</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>public_access</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + <div style="font-style: italic; font-size: small; color: darkgreen">added in 1.3.0</div> + </td> + <td> + </td> + <td> + <div>Configure public access block for S3 bucket.</div> + <div>This option cannot be used together with <em>delete_public_access</em>.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>block_public_acls</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Sets BlockPublicAcls value.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>block_public_policy</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Sets BlockPublicPolicy value.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>ignore_public_acls</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Sets IgnorePublicAcls value.</div> + </td> + </tr> + <tr> + <td class="elbow-placeholder"></td> + <td colspan="1"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>restrict_public_buckets</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>no</b> ←</div></li> + <li>yes</li> + </ul> + </td> + <td> + <div>Sets RestrictPublicAcls value.</div> + </td> + </tr> + + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>purge_tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>Whether to remove tags that aren't present in the <em>tags</em> parameter.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>region</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See <a href='http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region'>http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region</a></div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_region, ec2_region</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>requester_pays</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + </td> + <td> + <div>With Requester Pays buckets, the requester instead of the bucket owner pays the cost of the request and the data download from the bucket.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>s3_url</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>S3 URL endpoint for usage with DigitalOcean, Ceph, Eucalyptus and FakeS3 etc.</div> + <div>Assumes AWS if not specified.</div> + <div>For Walrus, use FQDN of the endpoint without scheme nor path.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: S3_URL</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>security_token</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + </td> + <td> + <div>AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.</div> + <div>If <em>profile</em> is set this parameter is ignored.</div> + <div>Passing the <em>security_token</em> and <em>profile</em> options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01.</div> + <div style="font-size: small; color: darkgreen"><br/>aliases: aws_security_token, access_token</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>state</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">string</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li><div style="color: blue"><b>present</b> ←</div></li> + <li>absent</li> + </ul> + </td> + <td> + <div>Create or remove the S3 bucket.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>tags</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">dictionary</span> + </div> + </td> + <td> + </td> + <td> + <div>Tags dict to apply to bucket.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>validate_certs</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li><div style="color: blue"><b>yes</b> ←</div></li> + </ul> + </td> + <td> + <div>When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.</div> + </td> + </tr> + <tr> + <td colspan="2"> + <div class="ansibleOptionAnchor" id="parameter-"></div> + <b>versioning</b> + <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> + <div style="font-size: small"> + <span style="color: purple">boolean</span> + </div> + </td> + <td> + <ul style="margin: 0; padding: 0"><b>Choices:</b> + <li>no</li> + <li>yes</li> + </ul> + </td> + <td> + <div>Whether versioning is enabled or disabled (note that once versioning is enabled, it can only be suspended).</div> + </td> + </tr> + </table> + <br/> + + +Notes +----- + +.. note:: + - If ``requestPayment``, ``policy``, ``tagging`` or ``versioning`` operations/API aren't implemented by the endpoint, module doesn't fail if each parameter satisfies the following condition. *requester_pays* is ``False``, *policy*, *tags*, and *versioning* are ``None``. + - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` + - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html + - ``AWS_REGION`` or ``EC2_REGION`` can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file + + + +Examples +-------- + +.. code-block:: yaml + + # Note: These examples do not set authentication details, see the AWS Guide for details. + + # Create a simple S3 bucket + - amazon.aws.s3_bucket: + name: mys3bucket + state: present + + # Create a simple S3 bucket on Ceph Rados Gateway + - amazon.aws.s3_bucket: + name: mys3bucket + s3_url: http://your-ceph-rados-gateway-server.xxx + ceph: true + + # Remove an S3 bucket and any keys it contains + - amazon.aws.s3_bucket: + name: mys3bucket + state: absent + force: yes + + # Create a bucket, add a policy from a file, enable requester pays, enable versioning and tag + - amazon.aws.s3_bucket: + name: mys3bucket + policy: "{{ lookup('file','policy.json') }}" + requester_pays: yes + versioning: yes + tags: + example: tag1 + another: tag2 + + # Create a simple DigitalOcean Spaces bucket using their provided regional endpoint + - amazon.aws.s3_bucket: + name: mydobucket + s3_url: 'https://nyc3.digitaloceanspaces.com' + + # Create a bucket with AES256 encryption + - amazon.aws.s3_bucket: + name: mys3bucket + state: present + encryption: "AES256" + + # Create a bucket with aws:kms encryption, KMS key + - amazon.aws.s3_bucket: + name: mys3bucket + state: present + encryption: "aws:kms" + encryption_key_id: "arn:aws:kms:us-east-1:1234/5678example" + + # Create a bucket with aws:kms encryption, default key + - amazon.aws.s3_bucket: + name: mys3bucket + state: present + encryption: "aws:kms" + + # Create a bucket with public policy block configuration + - amazon.aws.s3_bucket: + name: mys3bucket + state: present + public_access: + BlockPublicAcls: true + IgnorePublicAcls: true + ## keys == 'false' can be ommited, undefined keys defaults to 'false' + # BlockPublicPolicy: false + # RestrictPublicBuckets: false + + # Delete public policy block from bucket + - amazon.aws.s3_bucket: + name: mys3bucket + state: present + delete_public_access: true + + + + +Status +------ + + +Authors +~~~~~~~ + +- Rob White (@wimnat) |