steampunk.aws.s3_object (0.9.0) — module

Install collection

Install with ansible-galaxy collection install steampunk.aws:==0.9.0

Add to requirements.yml

  collections:
    - name: steampunk.aws
      version: 0.9.0

Description

Create, update and delete AWS S3 objects.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Inputs

    
key:
    description:
    - The key name of the S3 object.
    - It must contain the full path to the object within the I(bucket), for example C(img/20-7-2020/image.jpeg).
    required: true
    type: str

auth:
    description:
    - Parameters for authenticating with the AWS service. Each of them may be defined
      via environment variables.
    suboptions:
      access_key:
        description:
        - The AWS access key ID. If not set, the value of the AWS_ACCESS_KEY environment
          variable will be checked.
        - Mutually exclusive with I(profile).
        required: false
        type: str
      profile:
        description:
        - The name of the AWS profile configured with C(aws configure).
        - Can be used instead of explicitly specifying your access credentials and region.
        - Use C(default) to use the default profile.
        - Mutually exclusive with I(access_key) and I(secret_key).
        required: false
        type: str
      region:
        description:
        - The name of the AWS region.
        - If not set, the value of the AWS_REGION environment variable will be checked.
        - If you set a I(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:
        description:
        - The AWS secret access key. If not set, the value of the AWS_SECRET_KEY environment
          variable will be checked.
        - Mutually exclusive with I(profile).
        required: false
        type: str
      url:
        description:
        - 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.
        required: false
        type: str
    type: dict

tags:
    description:
    - Metadata for the AWS resource as key/value pairs.
    - Keys and values are case-sensitive.
    type: dict

state:
    choices:
    - present
    - absent
    default: present
    description:
    - The desired state of the S3 object.
    - When I(state) is C(absent) and multiple versions of the object exist, the module
      deletes all the versions of the S3 object.
    type: str

bucket:
    description:
    - The name of the S3 bucket containing the S3 object we're managing.
    required: true
    type: str

content:
    description:
    - 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 I(content_source) instead.
    - This parameter is required when creating an object.
    - Mutually exclusive with I(content_source).
    type: str

metadata:
    description:
    - 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 C(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 U(https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#object-metadata).
    type: dict

clear_tags:
    default: false
    description:
    - Whether to clear any existing tags on the resource that are not explicitly stated
      in I(tags).
    - By default, existing tags are kept on the resource.
    - When this parameter is set to C(true), any pre-existing tags on the resource are
      removed.
    type: bool

storage_class:
    choices:
    - standard
    - standard_ia
    - one_zone_ia
    - glacier
    - deep_archive
    - reduced_redundancy
    - intelligent_tiering
    description:
    - Storage class for the S3 object.
    - If you omit this parameter when creating a new object, the default value C(standard)
      will be used.
    - Please refer to U(https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.html)
      for more info on S3 storage types.
    type: str

clear_metadata:
    default: false
    description:
    - Whether to clear any existing metadata on the resource that are not explicitly stated
      in I(metadata).
    - By default, existing metadata are kept on the resource.
    - When this parameter is set to C(true), any pre-existing metadata on the resource
      are removed.
    type: bool

content_source:
    description:
    - 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 I(content).
    type: str

Outputs

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

See also

• s3_object_info
• s3_bucket