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.20
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:
- 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
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).
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
endpoint_url:
aliases:
- ec2_url
- aws_endpoint_url
- s3_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
aws_ca_bundle:
description:
- The location of a CA Bundle to use when validating SSL certificates.
- '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_session_token
- session_token
- 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.
- The I(security_token) and I(profile) options are mutually exclusive.
- Aliases I(aws_session_token) and I(session_token) have been added in version 3.2.0.
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
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: '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: 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