boto3_s3

Connection module for Amazon S3 using boto3.

Renamed from boto_s3 to boto3_s3 and rewritten to use the boto3 s3 client APIs directly via saltext.boto3.utils.boto3mod. The legacy boto2 code path (object-style access, retry loops) has been removed.

depends:

  • boto3 >= 1.28.0

  • botocore >= 1.31.0

configuration:

This module accepts explicit S3 credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More Information available at:

http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html

If IAM roles are not used you need to specify them either in the minion’s config file or as a profile. For example, to specify them in the minion’s config file:

s3.keyid: GKTADJGHEIQSXMKKRBJ08H
s3.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

A region may also be specified in the configuration:

s3.region: us-east-1

It’s also possible to specify key, keyid and region via a profile, either as a passed in dict, or as a string to pull from pillars or minion config:

myprofile:
    keyid: GKTADJGHEIQSXMKKRBJ08H
    key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
    region: us-east-1

Added in version 1.0.0.

Changed in version 1.2.0: Added download_file and generate_presigned_url object operations.

saltext.boto3.modules.boto3_s3.__virtual__()[source]

Only load if boto3 is available.

saltext.boto3.modules.boto3_s3.get_object_metadata(name, extra_args=None, region=None, key=None, keyid=None, profile=None)[source]

Get metadata about an S3 object. Returns {"result": None} if the object does not exist.

You can pass AWS SSE-C related args and/or RequestPayer in extra_args.

name (str):

S3 object location in bucket/key format.

extra_args (dict, optional):

Optional args passed to head_object.

region (str, optional):

AWS region.

key (str, optional):

AWS access key.

keyid (str, optional):

AWS access key ID.

profile (dict or str, optional):

AWS profile to use.

CLI Example:

salt myminion boto3_s3.get_object_metadata my_bucket/path/to/object
saltext.boto3.modules.boto3_s3.get_object(name, extra_args=None, region=None, key=None, keyid=None, profile=None)[source]

Get an S3 object body.

Added in version 1.0.2.

name (str):

S3 object location in bucket/key format.

extra_args (dict, optional):

Optional args passed to get_object.

region (str, optional):

AWS region.

key (str, optional):

AWS access key.

keyid (str, optional):

AWS access key ID.

profile (dict or str, optional):

AWS profile to use.

CLI Example:

salt myminion boto3_s3.get_object my_bucket/path/to/object
saltext.boto3.modules.boto3_s3.put_object(name, data, extra_args=None, region=None, key=None, keyid=None, profile=None)[source]

Create or update an S3 object.

Added in version 1.0.2.

name (str):

S3 object location in bucket/key format.

data (str):

Object body content.

extra_args (dict, optional):

Optional args passed to put_object.

region (str, optional):

AWS region.

key (str, optional):

AWS access key.

keyid (str, optional):

AWS access key ID.

profile (dict or str, optional):

AWS profile to use.

CLI Example:

salt myminion boto3_s3.put_object my_bucket/path/to/object "payload"
saltext.boto3.modules.boto3_s3.delete_object(name, extra_args=None, region=None, key=None, keyid=None, profile=None)[source]

Delete an S3 object.

Added in version 1.2.0.

name (str):

S3 object location in bucket/key format.

extra_args (dict, optional):

Optional args passed to delete_object.

region (str, optional):

AWS region.

key (str, optional):

AWS access key.

keyid (str, optional):

AWS access key ID.

profile (dict or str, optional):

AWS profile to use.

CLI Example:

salt myminion boto3_s3.delete_object my_bucket/path/to/object
saltext.boto3.modules.boto3_s3.upload_file(source, name, extra_args=None, region=None, key=None, keyid=None, profile=None)[source]

Upload a local file as an S3 object.

source (str):

Local path to the file to upload.

name (str):

S3 object location in bucket/key format.

extra_args (dict, optional):

Optional args passed to upload_file.

region (str, optional):

AWS region.

key (str, optional):

AWS access key.

keyid (str, optional):

AWS access key ID.

profile (dict or str, optional):

AWS profile to use.

CLI Example:

salt myminion boto3_s3.upload_file /path/to/local/file my_bucket/path/to/object
saltext.boto3.modules.boto3_s3.download_file(name, destination, extra_args=None, region=None, key=None, keyid=None, profile=None)[source]

Download an S3 object to a local file path.

Added in version 1.2.0.

name (str):

S3 object location in bucket/key format.

destination (str):

Local destination path where the object should be written.

extra_args (dict, optional):

Optional boto3 Transfer ExtraArgs for download_file.

region (str, optional):

AWS region.

key (str, optional):

AWS access key.

keyid (str, optional):

AWS access key ID.

profile (dict or str, optional):

AWS profile to use.

CLI Example:

salt myminion boto3_s3.download_file my_bucket/path/to/object /tmp/object
saltext.boto3.modules.boto3_s3.generate_presigned_url(name, expiration=900, extra_args=None, region=None, key=None, keyid=None, profile=None)[source]

Generate a pre-signed GET URL for an S3 object.

Added in version 1.2.0.

name (str):

S3 object location in bucket/key format.

expiration (int, optional):

Number of seconds the pre-signed URL remains valid.

extra_args (dict, optional):

Optional dict merged into the request Params.

region (str, optional):

AWS region.

key (str, optional):

AWS access key.

keyid (str, optional):

AWS access key ID.

profile (dict or str, optional):

AWS profile to use.

CLI Example:

salt myminion boto3_s3.generate_presigned_url my_bucket/path/to/object expiration=300