s3_object – Manage S3 objects¶

Create, update and delete AWS S3 objects.

Examples¶

- name: Create a new S3 object from a file
  s3_object:
    bucket: my-bucket
    key: path/to/my-object
    content_source: /tmp/my-file.txt

- name: Create a new S3 object by providing the content as a string
  s3_object:
    bucket: my-bucket
    key: path/to/my-object
    content: this is my data

- name: Update tags and the contents of an existing S3 object
  s3_object:
    bucket: my-bucket
    key: path/to/my-object
    tags:
      App: my-test-app

- name: Add user-defined metadata to an S3 object
  s3_object:
    bucket: my-bucket
    key: path/to/my-object
    metadata:
      DATA: TEST    # HTTP header, note the lowercase key -> x-amz-meta-data: TEST
      data-2: test  # HTTP header -> x-amz-meta-data-2: test

- name: Delete the S3 object
  s3_object:
    bucket: my-bucket
    key: path/to/my-object
    state: absent

Notes¶

Note

The module currently doesn’t support object versions.

Parameters¶

auth (optional)

Parameters for authenticating with the AWS service. Each of them may be defined via environment variables.

type: dict

access_key (optional)

The AWS access key ID. If not set, the value of the AWS_ACCESS_KEY environment variable will be checked.

Mutually exclusive with profile.

type: str

profile (optional)

The name of the AWS profile configured with aws configure.

Can be used instead of explicitly specifying your access credentials and region.

Use default to use the default profile.

Mutually exclusive with access_key and secret_key.

type: str

region (optional)

The name of the AWS region.

If not set, the value of the AWS_REGION environment variable will be checked.

If you set a profile that specifies a default region, that region is used and you can omit this parameter. Use this parameter to override the profile’s default region.

type: str

secret_key (optional)

The AWS secret access key. If not set, the value of the AWS_SECRET_KEY environment variable will be checked.

Mutually exclusive with profile.

type: str

url (optional)

The URL to the AWS service related to the resource. By default, this is automatically determined through the region parameter.

If not set explicitly, the value of the AWS_<SERVICE>_URL environment variable will be used.

The services currently supported are EC2 and S3.

type: str

bucket (required)

The name of the S3 bucket containing the S3 object we’re managing.

type: str

clear_metadata (optional)

Whether to clear any existing metadata on the resource that are not explicitly stated in metadata.

By default, existing metadata are kept on the resource.

When this parameter is set to true, any pre-existing metadata on the resource are removed.

type: bool

clear_tags (optional)

Whether to clear any existing tags on the resource that are not explicitly stated in tags.

By default, existing tags are kept on the resource.

When this parameter is set to true, any pre-existing tags on the resource are removed.

type: bool

content (optional)

The contents of the S3 object.

Only use this parameter if you are providing the content encoded as UTF-8 text. For binary contents, store the content to a file and use content_source instead.

This parameter is required when creating an object.

Mutually exclusive with content_source.

type: str

content_source (optional)

Path to the file on your local filesystem whose contents will be uploaded to S3.

This parameter is required when creating an object.

Mutually exclusive with content.

type: str

key (required)

The key name of the S3 object.

It must contain the full path to the object within the bucket, for example img/20-7-2020/image.jpeg.

type: str

metadata (optional)

User-defined metadata that will be stored with the S3 object as key/value pairs.

Note that the specified metadata keys will be automatically prefixed with x-amz-meta- and AWS will convert metadata keys to lowercase.

Metadata values are case-sensitive strings.

For more information about S3 object metadata, please refer to https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#object-metadata.

type: dict

state (optional)

The desired state of the S3 object.

When state is absent and multiple versions of the object exist, the module deletes all the versions of the S3 object.

type: str
default: present
choices: present, absent

storage_class (optional)

Storage class for the S3 object.

If you omit this parameter when creating a new object, the default value standard will be used.

Please refer to https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.html for more info on S3 storage types.

type: str

choices: standard, standard_ia, one_zone_ia, glacier, deep_archive, reduced_redundancy, intelligent_tiering

tags (optional)

Metadata for the AWS resource as key/value pairs.

Keys and values are case-sensitive.

type: dict

Return Values¶

object (success and C(state=present)), dict,

An object representing the S3 object.

bucket (always), str, steamybucket: The name of the S3 bucket that contains this object.
key (always), str, archive/documents/file.txt: The S3 object’s key name.
size (always), int, 433937: Size of the object’s content in bytes.
last_modified (always), str, 2020-06-24T11:50:15+00:00: Date and time of the S3 object’s last modification.
storage_class (always), str, standard: The storage class of the S3 object.
etag (always), str, 54292ef8bb5854ef3f9d32df302ed245: The entity tag (an MD5 hash) of the S3 object’s contents.
metadata (always), dict, {‘foo’: ‘bar’}: User-defined metadata of the S3 object.
tags (always), dict, {‘App’: ‘test-app’}: Tags associated with the S3 object.
owner (always), dict, {‘name’: ‘xlab’, ‘id’: ‘ff686298db457b3ac7’}: The owner of the S3 object.

s3_object – Manage S3 objects¶

Examples¶

Notes¶

See Also¶

Parameters¶

Return Values¶