ansible / ansible.builtin / v2.4.4.0-1 / module / _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._s3 (v2.4.4.0-1) — module
pip
Install with pip install ansible==2.4.4.0.post1
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. 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: 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.' version_added: '1.8' version_added_collection: ansible.builtin s3_url: aliases: - S3_URL description: - S3 URL endpoint for usage with Ceph, Eucalypus, fakes3, etc. Otherwise assumes AWS encrypt: default: true description: - When set for PUT mode, asks for server-side encryption. 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. Prior to release 6.0.0 the C(AWS_PROFILE) environment variable will be ignored if any of I(access_key), I(secret_key), or I(session_token) are passed. After release 6.0.0 I(profile) will always fall back to the C(AWS_PROFILE) environment variable if set. - 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 overwrite: 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 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. Prior to release 6.0.0 these environment variables will be ignored if the I(profile) parameter is passed. After release 6.0.0 I(access_key) will always fall back to the environment variables if set. - 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. Prior to release 6.0.0 these environment variables will be ignored if the I(profile) parameter is passed. After release 6.0.0 I(secret_key) will always fall back to the environment variables if set. - 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. Prior to release 6.0.0 these environment variables will be ignored if the I(profile) parameter is passed. After release 6.0.0 I(session_token) will always fall back to the environment variables if set. - 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 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.' 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