ansible / ansible.builtin / v2.9.13 / module / aws_s3 manage objects in S3. | "added in version" 1.1 of ansible.builtin" Authors: Lester Wade (@lwade), Sloane Hertel (@s-hertel) stableinterface | supported by coreansible.builtin.aws_s3 (v2.9.13) — module
pip
Install with pip install ansible==2.9.13
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.
- name: Simple PUT operation aws_s3: bucket: mybucket object: /my/desired/key.txt src: /usr/local/myfile.txt mode: put
- name: Simple PUT operation in Ceph RGW S3 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 aws_s3: bucket: mybucket object: /my/desired/key.txt dest: /usr/local/myfile.txt mode: get
- name: Get a specific version of an object. aws_s3: bucket: mybucket object: /my/desired/key.txt version: 48c9ee5131af7a716edc22df9772aa6f dest: /usr/local/myfile.txt mode: get
- name: PUT/upload with metadata 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 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 aws_s3: bucket: mybucket mode: list
- name: List keys all options aws_s3: bucket: mybucket mode: list prefix: /my/desired/ marker: /my/desired/0023.txt max_keys: 472
- name: Create an empty bucket aws_s3: bucket: mybucket mode: create permission: public-read
- name: Create a bucket with key as directory, in the EU region aws_s3: bucket: mybucket object: /my/directory/path mode: create region: eu-west-1
- name: Delete a bucket and all contents aws_s3: bucket: mybucket mode: delete
- name: GET an object but don't download if the file checksums match. New in 2.0 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 aws_s3: bucket: mybucket object: /my/desired/key.txt mode: delobj
rgw: default: false description: - Enable Ceph RGW S3 support. This option requires an explicit url via s3_url. type: bool version_added: '2.2' version_added_collection: ansible.builtin src: description: - The source file path when performing a PUT operation. version_added: '1.3' version_added_collection: ansible.builtin dest: description: - The destination file path when downloading an object/key with a GET operation. version_added: '1.3' version_added_collection: ansible.builtin mode: choices: - get - put - delete - create - geturl - getstr - delobj - list description: - Switches the module behaviour between put (upload), get (download), geturl (return download url, Ansible 1.3+), getstr (download object as string (1.3+)), list (list keys, Ansible 2.0+), create (bucket), delete (bucket), and delobj (delete object, Ansible 2.0+). required: true bucket: description: - Bucket name. required: true marker: description: - 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. version_added: '2.0' version_added_collection: ansible.builtin object: description: - Keyname of the object inside the bucket. Can be used to create "virtual directories", see examples. prefix: default: '' description: - Limits the response to keys that begin with the specified prefix for list mode version_added: '2.0' version_added_collection: ansible.builtin region: aliases: - aws_region - ec2_region description: - 'AWS region to create the bucket in. If not set then the value of the AWS_REGION and EC2_REGION environment variables are checked, followed by the aws_region and ec2_region settings in the Boto config file. If none of those are set the region defaults to the S3 Location: US Standard. Prior to ansible 1.8 this parameter could be specified but had no effect.' type: str version_added: '1.8' version_added_collection: ansible.builtin s3_url: aliases: - S3_URL description: - S3 URL endpoint for usage with Ceph, Eucalyptus and fakes3 etc. Otherwise assumes AWS. encrypt: default: true description: - When set for PUT mode, asks for server-side encryption. type: bool version_added: '2.0' version_added_collection: ansible.builtin headers: description: - Custom headers for PUT operation, as a dictionary of 'key=value' and 'key=value,key=value'. version_added: '2.0' version_added_collection: ansible.builtin profile: aliases: - aws_profile description: - A named AWS profile to use for authentication. - See the AWS documentation for more information about named profiles U(https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html). - The C(AWS_PROFILE) environment variable may also be used. - The I(profile) option is mutually exclusive with the I(aws_access_key), I(aws_secret_key) and I(security_token) options. type: str retries: default: 0 description: - On recoverable failure, how many times to retry before actually failing. version_added: '2.0' version_added_collection: ansible.builtin version: description: - 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. version_added: '2.0' version_added_collection: ansible.builtin max_keys: default: 1000 description: - Max number of results to return in list mode, set this if you want to retrieve fewer than the default 1000 keys. version_added: '2.0' version_added_collection: ansible.builtin metadata: description: - Metadata for PUT operation, as a dictionary of 'key=value' and 'key=value,key=value'. version_added: '1.6' version_added_collection: ansible.builtin dualstack: default: 'no' description: - Enables Amazon S3 Dual-Stack Endpoints, allowing S3 communications using both IPv4 and IPv6. - Requires at least botocore version 1.4.45. type: bool version_added: '2.7' version_added_collection: ansible.builtin overwrite: aliases: - force default: always description: - Force overwrite either locally on the filesystem or remotely with the object/key. Used with PUT and GET operations. Boolean or one of [always, never, different], true is equal to 'always' and false is equal to 'never', new in 2.0. When this is set to 'different', 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 U(https://docs.aws.amazon.com/AmazonS3/latest/API/RESTCommonResponseHeaders.html) version_added: '1.2' version_added_collection: ansible.builtin access_key: aliases: - aws_access_key_id - aws_access_key - ec2_access_key description: - AWS access key ID. - See the AWS documentation for more information about access tokens U(https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys). - The C(AWS_ACCESS_KEY_ID), C(AWS_ACCESS_KEY) or C(EC2_ACCESS_KEY) environment variables may also be used in decreasing order of preference. - The I(aws_access_key) and I(profile) options are mutually exclusive. - The I(aws_access_key_id) alias was added in release 5.1.0 for consistency with the AWS botocore SDK. - The I(ec2_access_key) alias has been deprecated and will be removed in a release after 2024-12-01. - Support for the C(EC2_ACCESS_KEY) environment variable has been deprecated and will be removed in a release after 2024-12-01. type: str aws_config: description: - A dictionary to modify the botocore configuration. - Parameters can be found in the AWS documentation U(https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config). type: dict expiration: default: 600 description: - Time limit (in seconds) for the URL generated and returned by S3/Walrus when performing a mode=put or mode=geturl operation. permission: default: private description: - This option lets the user set the canned permissions on the object/bucket that are created. The permissions that can be set are 'private', 'public-read', 'public-read-write', 'authenticated-read' for a bucket or 'private', 'public-read', 'public-read-write', 'aws-exec-read', 'authenticated-read', 'bucket-owner-read', 'bucket-owner-full-control' for an object. Multiple permissions can be specified as a list. version_added: '2.0' version_added_collection: ansible.builtin secret_key: aliases: - aws_secret_access_key - aws_secret_key - ec2_secret_key description: - AWS secret access key. - See the AWS documentation for more information about access tokens U(https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys). - The C(AWS_SECRET_ACCESS_KEY), C(AWS_SECRET_KEY), or C(EC2_SECRET_KEY) environment variables may also be used in decreasing order of preference. - The I(secret_key) and I(profile) options are mutually exclusive. - The I(aws_secret_access_key) alias was added in release 5.1.0 for consistency with the AWS botocore SDK. - The I(ec2_secret_key) alias has been deprecated and will be removed in a release after 2024-12-01. - Support for the C(EC2_SECRET_KEY) environment variable has been deprecated and will be removed in a release after 2024-12-01. type: str endpoint_url: aliases: - ec2_url - aws_endpoint_url - s3_url description: - URL to connect to instead of the default AWS endpoints. While this can be used to connection to other AWS-compatible services the amazon.aws and community.aws collections are only tested against AWS. - The C(AWS_URL) or C(EC2_URL) environment variables may also be used, in decreasing order of preference. - The I(ec2_url) and I(s3_url) aliases have been deprecated and will be removed in a release after 2024-12-01. - Support for the C(EC2_URL) environment variable has been deprecated and will be removed in a release after 2024-12-01. type: str aws_ca_bundle: description: - The location of a CA Bundle to use when validating SSL certificates. - The C(AWS_CA_BUNDLE) environment variable may also be used. type: path session_token: aliases: - aws_session_token - security_token - aws_security_token - access_token description: - AWS STS session token for use with temporary credentials. - See the AWS documentation for more information about access tokens U(https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys). - The C(AWS_SESSION_TOKEN), C(AWS_SECURITY_TOKEN) or C(EC2_SECURITY_TOKEN) environment variables may also be used in decreasing order of preference. - The I(security_token) and I(profile) options are mutually exclusive. - Aliases I(aws_session_token) and I(session_token) were added in release 3.2.0, with the parameter being renamed from I(security_token) to I(session_token) in release 6.0.0. - The I(security_token), I(aws_security_token), and I(access_token) aliases have been deprecated and will be removed in a release after 2024-12-01. - Support for the C(EC2_SECRET_KEY) and C(AWS_SECURITY_TOKEN) environment variables has been deprecated and will be removed in a release after 2024-12-01. type: str aws_access_key: aliases: - ec2_access_key - access_key description: - AWS access key id. If not set then the value of the AWS_ACCESS_KEY environment variable is used. aws_secret_key: aliases: - ec2_secret_key - secret_key description: - AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used. validate_certs: default: true description: - When set to C(false), SSL certificates will not be validated for communication with the AWS APIs. - Setting I(validate_certs=false) is strongly discouraged, as an alternative, consider setting I(aws_ca_bundle) instead. type: bool encryption_mode: choices: - AES256 - aws:kms default: AES256 description: - What encryption mode to use if C(encrypt) is set version_added: '2.7' version_added_collection: ansible.builtin encryption_kms_key_id: description: - KMS key id to use when encrypting objects using C(aws:kms) encryption. Ignored if encryption is not C(aws:kms) version_added: '2.7' version_added_collection: ansible.builtin ignore_nonexistent_bucket: description: - '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 ignore_nonexistent_bucket: True.' type: bool version_added: '2.3' version_added_collection: ansible.builtin debug_botocore_endpoint_logs: default: false description: - Use a C(botocore.endpoint) logger to parse the unique (rather than total) C("resource:action") API calls made during a task, outputing the set to the resource_actions key in the task results. Use the C(aws_resource_action) callback to output to total list made during a playbook. - The C(ANSIBLE_DEBUG_BOTOCORE_LOGS) environment variable may also be used. type: bool
contents: description: contents of the object as string returned: (for getstr operation) sample: Hello, world! type: str expiry: description: number of seconds the presigned url is valid for returned: (for geturl operation) sample: 600 type: int msg: description: msg indicating the status of the operation returned: always sample: PUT operation complete type: str s3_keys: description: list of object keys returned: (for list operation) sample: - prefix1/ - prefix1/key1 - prefix1/key2 type: list url: description: url of the object returned: (for put and geturl operations) sample: https://my-bucket.s3.amazonaws.com/my-key.txt?AWSAccessKeyId=<access-key>&Expires=1506888865&Signature=<signature> type: str