You are viewing docs from a branch that is no longer active. You might want to view docs for the 2015.8.x release instead.

salt.modules.s3¶

Connection module for Amazon S3

configuration:

configuration:	This module accepts explicit s3 credentials but can also utilize IAM roles assigned to the instance trough 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 a pillar or in the minion's config file: s3.keyid: GKTADJGHEIQSXMKKRBJ08H s3.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs A service_url may also be specified in the configuration: s3.service_url: s3.amazonaws.com If a service_url is not specified, the default is s3.amazonaws.com. This may appear in various documentation as an "endpoint". A comprehensive list for Amazon S3 may be found at: http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region The service_url will form the basis for the final endpoint that is used to query the service. SSL verification may also be turned off in the configuration: s3.verify_ssl: False This is required if using S3 bucket names that contain a period, as these will not match Amazon's S3 wildcard certificates. Certificate verification is enabled by default. This module should be usable to query other S3-like services, such as Eucalyptus.
depends:	requests

This module accepts explicit s3 credentials but can also utilize IAM roles assigned to the instance trough 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 a pillar or in the minion's config file:

s3.keyid: GKTADJGHEIQSXMKKRBJ08H
s3.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

A service_url may also be specified in the configuration:

s3.service_url: s3.amazonaws.com

If a service_url is not specified, the default is s3.amazonaws.com. This may appear in various documentation as an "endpoint". A comprehensive list for Amazon S3 may be found at:

http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region

The service_url will form the basis for the final endpoint that is used to query the service.

SSL verification may also be turned off in the configuration:

s3.verify_ssl: False

This is required if using S3 bucket names that contain a period, as these will not match Amazon's S3 wildcard certificates. Certificate verification is enabled by default.

This module should be usable to query other S3-like services, such as Eucalyptus.

depends:

requests

salt.modules.s3.delete(bucket, path=None, action=None, key=None, keyid=None, service_url=None, verify_ssl=None)¶

Delete a bucket, or delete an object from a bucket.

CLI Example to delete a bucket:

salt myminion s3.delete mybucket

CLI Example to delete an object from a bucket:

salt myminion s3.delete mybucket remoteobject

salt.modules.s3.get(bucket=None, path=None, return_bin=False, action=None, local_file=None, key=None, keyid=None, service_url=None, verify_ssl=None)¶

List the contents of a bucket, or return an object from a bucket. Set return_bin to True in order to retrieve an object wholesale. Otherwise, Salt will attempt to parse an XML response.

CLI Example to list buckets:

salt myminion s3.get

CLI Example to list the contents of a bucket:

salt myminion s3.get mybucket

CLI Example to return the binary contents of an object:

salt myminion s3.get mybucket myfile.png return_bin=True

CLI Example to save the binary contents of an object to a local file:

salt myminion s3.get mybucket myfile.png local_file=/tmp/myfile.png

It is also possible to perform an action on a bucket. Currently, S3 supports the following actions:

acl
cors
lifecycle
policy
location
logging
notification
tagging
versions
requestPayment
versioning
website

To perform an action on a bucket:

salt myminion s3.get mybucket myfile.png action=acl

salt.modules.s3.head(bucket, path=None, key=None, keyid=None, service_url=None, verify_ssl=None)¶

Return the metadata for a bucket, or an object in a bucket.

CLI Examples:

salt myminion s3.head mybucket
salt myminion s3.head mybucket myfile.png

salt.modules.s3.put(bucket, path=None, return_bin=False, action=None, local_file=None, key=None, keyid=None, service_url=None, verify_ssl=None)¶

Create a new bucket, or upload an object to a bucket.

CLI Example to create a bucket:

salt myminion s3.put mybucket

CLI Example to upload an object to a bucket:

salt myminion s3.put mybucket remotepath local_file=/path/to/file