.. meta:: :description: Create, update and delete AWS S3 objects. .. _s3_object_module: s3_object -- Manage S3 objects ============================== Create, update and delete AWS S3 objects. Examples -------- .. code-block:: yaml+jinja - 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. See Also -------- .. seealso:: - :ref:`s3_object_info_module` - :ref:`s3_bucket_module` 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__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.