community.aws.aws_s3_bucket_info module – lists S3 buckets in AWS
Note
This module is part of the community.aws collection (version 3.6.0).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install community.aws
.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.aws.aws_s3_bucket_info
.
New in community.aws 1.0.0
Synopsis
Lists S3 buckets and details about those buckets.
Requirements
The below requirements are needed on the host that executes this module.
python >= 3.6
boto3 >= 1.16.0
botocore >= 1.19.0
Parameters
Parameter |
Comments |
---|---|
If profile is set this parameter is ignored. Passing the aws_access_key and profile options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. |
|
The location of a CA Bundle to use when validating SSL certificates. Not used by boto 2 based modules. Note: The CA Bundle is read ‘module’ side and may need to be explicitly copied from the controller if not run locally. |
|
A dictionary to modify the botocore configuration. Parameters can be found at https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config. Only the ‘user_agent’ key is used for boto modules. See http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto for more boto configuration. |
|
If profile is set this parameter is ignored. Passing the aws_secret_key and profile options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. |
|
Retrieve requested S3 bucket detailed information Each bucket_X option executes one API call, hence many options being set to You can limit buckets by using the name or name_filter option. |
|
Retrive S3 accelerate configuration. Choices:
|
|
Retrive S3 bucket ACLs. Choices:
|
|
Retrive S3 bucket CORS configuration. Choices:
|
|
Retrive S3 bucket encryption. Choices:
|
|
Retrive S3 bucket lifecycle configuration. Choices:
|
|
Retrive S3 bucket location. Choices:
|
|
Retrive S3 bucket logging. Choices:
|
|
Retrive S3 bucket notification configuration. Choices:
|
|
Retrive S3 ownership controls. Choices:
|
|
Retrive S3 bucket policy. Choices:
|
|
Retrive S3 bucket policy status. Choices:
|
|
Retrive S3 bucket replication. Choices:
|
|
Retrive S3 bucket request payment. Choices:
|
|
Retrive S3 bucket tagging. Choices:
|
|
Retrive S3 bucket website. Choices:
|
|
Retrive S3 bucket public access block. Choices:
|
|
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. Choices:
|
|
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. |
|
Name of bucket to query. Default: |
|
Limits buckets to only buckets who’s name contain the string in name_filter. Default: |
|
Using profile will override aws_access_key, aws_secret_key and security_token and support for passing them at the same time as profile has been deprecated. aws_access_key, aws_secret_key and security_token will be made mutually exclusive with profile after 2022-06-01. |
|
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 http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region |
|
If profile is set this parameter is ignored. Passing the security_token and profile options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. Aliases aws_session_token and session_token have been added in version 3.2.0. |
|
S3 bucket location for default us-east-1 is normally reported as Setting this option to Affects only queries with bucket_facts=true and bucket_location=true. Choices:
|
|
When set to “no”, SSL certificates will not be validated for communication with the AWS APIs. Choices:
|
Notes
Note
If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence
AWS_URL
orEC2_URL
,AWS_PROFILE
orAWS_DEFAULT_PROFILE
,AWS_ACCESS_KEY_ID
orAWS_ACCESS_KEY
orEC2_ACCESS_KEY
,AWS_SECRET_ACCESS_KEY
orAWS_SECRET_KEY
orEC2_SECRET_KEY
,AWS_SECURITY_TOKEN
orEC2_SECURITY_TOKEN
,AWS_REGION
orEC2_REGION
,AWS_CA_BUNDLE
When no credentials are explicitly provided the AWS SDK (boto3) that Ansible uses will fall back to its configuration files (typically
~/.aws/credentials
). See https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html for more information.Modules based on the original AWS SDK (boto) may read their default configuration from different files. See https://boto.readthedocs.io/en/latest/boto_config_tut.html for more information.
AWS_REGION
orEC2_REGION
can be typically be used to specify the AWS region, when required, but this can also be defined in the configuration files.
Examples
# Note: These examples do not set authentication details, see the AWS Guide for details.
# Note: Only AWS S3 is currently supported
# Lists all s3 buckets
- community.aws.aws_s3_bucket_info:
register: result
# Retrieve detailed bucket information
- community.aws.aws_s3_bucket_info:
# Show only buckets with name matching
name_filter: your.testing
# Choose facts to retrieve
bucket_facts:
# bucket_accelerate_configuration: true
bucket_acl: true
bucket_cors: true
bucket_encryption: true
# bucket_lifecycle_configuration: true
bucket_location: true
# bucket_logging: true
# bucket_notification_configuration: true
# bucket_ownership_controls: true
# bucket_policy: true
# bucket_policy_status: true
# bucket_replication: true
# bucket_request_payment: true
# bucket_tagging: true
# bucket_website: true
# public_access_block: true
transform_location: true
register: result
# Print out result
- name: List buckets
ansible.builtin.debug:
msg: "{{ result['buckets'] }}"
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
List of buckets Returned: always |
|
Bucket ACL configuration. Returned: when bucket_facts=true and bucket_acl=true |
|
List of ACL grants. Returned: success Sample: |
|
Bucket owner information. Returned: success |
|
Bucket owner user display name. Returned: always Sample: |
|
Bucket owner user ID. Returned: always Sample: |
|
Bucket CORS configuration. Returned: when bucket_facts=true and bucket_cors=true |
|
Bucket CORS configuration. Returned: when CORS rules are defined for the bucket Sample: |
|
Bucket encryption configuration. Returned: when bucket_facts=true and bucket_encryption=true |
|
ServerSideEncryptionConfiguration configuration. Returned: when encryption is enabled on the bucket |
|
List of applied encryptio rules. Returned: when encryption is enabled on the bucket Sample: |
|
Bucket lifecycle configuration settings. Returned: when bucket_facts=true and bucket_lifecycle_configuration=true |
|
List of lifecycle management rules. Returned: when lifecycle configuration is present Sample: |
|
Bucket location. Returned: when bucket_facts=true and bucket_location=true |
|
AWS region. Returned: always Sample: |
|
Server access logging configuration. Returned: when bucket_facts=true and bucket_logging=true |
|
Server access logging configuration. Returned: when server access logging is defined for the bucket |
|
Target bucket name. Returned: always Sample: |
|
Prefix in target bucket. Returned: always Sample: |
|
String used to limit buckets. See name_filter. Returned: when name_filter is defined Sample: |
|
Bucket notification settings. Returned: when bucket_facts=true and bucket_notification_configuration=true |
|
List of notification events configurations. Returned: when at least one notification is configured Sample: |
|
Preffered object ownership settings. Returned: when bucket_facts=true and bucket_ownership_controls=true |
|
Object ownership settings. Returned: when ownership controls are defined for the bucket |
|
List of ownership rules. Returned: when ownership rule is defined Sample: |
|
Bucket policy contents. Returned: when bucket_facts=true and bucket_policy=true Sample: |
|
Status of bucket policy. Returned: when bucket_facts=true and bucket_policy_status=true |
|
Status of bucket policy. Returned: when bucket policy is present |
|
Report bucket policy public status. Returned: when bucket policy is present Sample: |
|
Replication configuration settings. Returned: when bucket_facts=true and bucket_replication=true |
|
IAM role used for replication. Returned: when replication rule is defined Sample: |
|
List of replication rules. Returned: when replication rule is defined Sample: |
|
Requester pays setting. Returned: when bucket_facts=true and bucket_request_payment=true |
|
Current payer. Returned: always Sample: |
|
Bucket tags. Returned: when bucket_facts=true and bucket_tagging=true Sample: |
|
Static website hosting. Returned: when bucket_facts=true and bucket_website=true |
|
Object serving as HTTP error page. Returned: when static website hosting is enabled Sample: |
|
Object serving as HTTP index page. Returned: when static website hosting is enabled Sample: |
|
Website redict settings. Returned: when redirect requests is configured |
|
Hostname to redirect. Returned: always Sample: |
|
Protocol used for redirect. Returned: always Sample: |
|
Bucket creation date timestamp. Returned: always Sample: |
|
Bucket name. Returned: always Sample: |
|
Bucket public access block configuration. Returned: when bucket_facts=true and public_access_block=true |
|
PublicAccessBlockConfiguration data. Returned: when PublicAccessBlockConfiguration is defined for the bucket |
|
BlockPublicAcls setting value. Returned: success Sample: |
|
BlockPublicPolicy setting value. Returned: success Sample: |
|
IgnorePublicAcls setting value. Returned: success Sample: |
|
RestrictPublicBuckets setting value. Returned: success Sample: |