ansible / ansible.builtin / v2.9.17 / 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.17) — module
pip
Install with pip install ansible==2.9.17
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. ec2_url: aliases: - aws_endpoint_url - endpoint_url description: - 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. type: str 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: - Using I(profile) will override I(aws_access_key), I(aws_secret_key) and I(security_token) and support for passing them at the same time as I(profile) has been deprecated. - I(aws_access_key), I(aws_secret_key) and I(security_token) will be made mutually exclusive with I(profile) after 2022-06-01. 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 aws_config: description: - A dictionary to modify the botocore configuration. - Parameters can be found at U(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 U(http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto) for more boto configuration. 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 aws_ca_bundle: description: - 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.' type: path 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. type: str 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. type: str security_token: aliases: - aws_security_token - access_token description: - C(AWS STS security token). If not set then the value of the C(AWS_SECURITY_TOKEN) or C(EC2_SECURITY_TOKEN) environment variable is used. - If I(profile) is set this parameter is ignored. - Passing the I(security_token) and I(profile) options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. type: str validate_certs: default: true description: - When set to "no", SSL certificates will not be validated for communication with the AWS APIs. 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: 'no' description: - 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. 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