ansible / ansible.builtin / v2.3.3.0-1 / module / s3 manage objects in S3. | "added in version" 1.1 of ansible.builtin" Authors: Lester Wade (@lwade) stableinterface | supported by curatedansible.builtin.s3 (v2.3.3.0-1) — module
pip
Install with pip install ansible==2.3.3.0.post1
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 python-boto.
- name: Simple PUT operation s3: bucket: mybucket object: /my/desired/key.txt src: /usr/local/myfile.txt mode: put
- name: Simple PUT operation in Ceph RGW S3 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 s3: bucket: mybucket object: /my/desired/key.txt dest: /usr/local/myfile.txt mode: get
- name: Get a specific version of an object. s3: bucket: mybucket object: /my/desired/key.txt version: 48c9ee5131af7a716edc22df9772aa6f dest: /usr/local/myfile.txt mode: get
- name: PUT/upload with metadata 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 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 s3: bucket: mybucket mode: list
- name: List keys all options s3: bucket: mybucket mode: list prefix: /my/desired/ marker: /my/desired/0023.txt max_keys: 472
- name: Create an empty bucket s3: bucket: mybucket mode: create permission: public-read
- name: Create a bucket with key as directory, in the EU region s3: bucket: mybucket object: /my/directory/path mode: create region: eu-west-1
- name: Delete a bucket and all contents s3: bucket: mybucket mode: delete
- name: GET an object but dont download if the file checksums match. New in 2.0 s3: bucket: mybucket object: /my/desired/key.txt dest: /usr/local/myfile.txt mode: get overwrite: different
- name: Delete an object from a bucket 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: aliases: [] default: null description: - The source file path when performing a PUT operation. required: false version_added: '1.3' version_added_collection: ansible.builtin dest: aliases: [] description: - The destination file path when downloading an object/key with a GET operation. required: false 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: aliases: [] default: null description: - Bucket name. required: true marker: default: null 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. required: false version_added: '2.0' version_added_collection: ansible.builtin object: default: null description: - Keyname of the object inside the bucket. Can be used to create "virtual directories", see examples. required: false prefix: default: null description: - Limits the response to keys that begin with the specified prefix for list mode required: false version_added: '2.0' version_added_collection: ansible.builtin region: default: null 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.' required: false version_added: '1.8' version_added_collection: ansible.builtin s3_url: aliases: - S3_URL default: null description: - S3 URL endpoint for usage with Ceph, Eucalypus, fakes3, etc. Otherwise assumes AWS ec2_url: aliases: - aws_endpoint_url - endpoint_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 encrypt: default: false description: - When set for PUT mode, asks for server-side encryption required: false version_added: '2.0' version_added_collection: ansible.builtin headers: default: null description: - Custom headers for PUT operation, as a dictionary of 'key=value' and 'key=value,key=value'. required: false 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. required: false version_added: '2.0' version_added_collection: ansible.builtin version: aliases: [] default: null 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. required: false 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. required: false version_added: '2.0' version_added_collection: ansible.builtin metadata: default: null description: - Metadata for PUT operation, as a dictionary of 'key=value' and 'key=value,key=value'. required: false version_added: '1.6' version_added_collection: ansible.builtin overwrite: 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 required: false 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: aliases: [] 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. required: false 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'. Multiple permissions can be specified as a list. required: false version_added: '2.0' version_added_collection: ansible.builtin 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 default: null description: - AWS access key id. If not set then the value of the AWS_ACCESS_KEY environment variable is used. required: false type: str aws_secret_key: aliases: - ec2_secret_key - secret_key default: null description: - AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used. required: false 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: aliases: [] default: false 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