s3 - idempotent S3 module putting a file into S3.

Author:Lester Wade, Ralph Tice

Synopsis

New in version 1.1.

This module allows the user to dictate the presence of a given file in an S3 bucket. If or once the key (file) exists in the bucket, it returns a time-expired download URL. This module has a dependency on python-boto.

Options

parameter required default choices comments
aws_access_key no
    AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
    aws_secret_key no
      AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used.
      bucket yes
        Bucket name.
        dest no
          The destination file path when downloading an object/key with a GET operation. (added in Ansible 1.3)
          expiration no 600
            Time limit (in seconds) for the URL generated and returned by S3/Walrus when performing a mode=put or mode=geturl operation.
            metadata no
              Metadata for PUT operation, as a dictionary of 'key=value' and 'key=value,key=value'. (added in Ansible 1.6)
              mode yes
                Switches the module behaviour between put (upload), get (download), geturl (return download url (Ansible 1.3+), getstr (download object as string (1.3+)), create (bucket) and delete (bucket).
                object no
                  Keyname of the object inside the bucket. Can be used to create "virtual directories", see examples. (added in Ansible 1.3)
                  overwrite no True
                    Force overwrite either locally on the filesystem or remotely with the object/key. Used with PUT and GET operations. (added in Ansible 1.2)
                    s3_url no
                      S3 URL endpoint. If not specified then the S3_URL environment variable is used, if that variable is defined. Ansible tries to guess if fakes3 (https://github.com/jubos/fake-s3) or Eucalyptus Walrus (https://github.com/eucalyptus/eucalyptus/wiki/Walrus) is used and configure connection accordingly. Current heuristic is: everything with scheme fakes3:// is fakes3, everything else not ending with amazonaws.com is Walrus.
                      src no
                        The source file path when performing a PUT operation. (added in Ansible 1.3)

                        Note

                        Requires boto

                        Examples


                        # Simple PUT operation
                        - s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=put
                        # Simple GET operation
                        - s3: bucket=mybucket object=/my/desired/key.txt dest=/usr/local/myfile.txt mode=get
                        # GET/download and overwrite local file (trust remote)
                        - s3: bucket=mybucket object=/my/desired/key.txt dest=/usr/local/myfile.txt mode=get
                        # GET/download and do not overwrite local file (trust remote)
                        - s3: bucket=mybucket object=/my/desired/key.txt dest=/usr/local/myfile.txt mode=get force=false
                        # PUT/upload and overwrite remote file (trust local)
                        - s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=put
                        # PUT/upload with metadata
                        - s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=put metadata='Content-Encoding=gzip'
                        # PUT/upload with multiple metadata
                        - s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=put metadata='Content-Encoding=gzip,Cache-Control=no-cache'
                        # PUT/upload and do not overwrite remote file (trust local)
                        - s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=put force=false
                        # Download an object as a string to use else where in your playbook
                        - s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=getstr
                        # Create an empty bucket
                        - s3: bucket=mybucket mode=create
                        # Create a bucket with key as directory
                        - s3: bucket=mybucket object=/my/directory/path mode=create
                        # Delete a bucket and all contents
                        - s3: bucket=mybucket mode=delete