Try Spottermanage objects in S3.
| "added in version" 1.1 of ansible.builtin"
Authors: Lester Wade (@lwade), Sloane Hertel (@s-hertel)
stableinterface | supported by core
pipInstall with pip install ansible==2.6.10
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:
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, 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:
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(http://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. 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
contents: description: contents of the object as string returned: (for getstr operation) sample: Hello, world! type: string 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: string 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: string