Documentation

rax_files_objects - Upload, download, and delete objects in Rackspace Cloud Files

New in version 1.5.

Synopsis

Upload, download, and delete objects in Rackspace Cloud Files

Requirements (on host that executes module)

  • python >= 2.6
  • pyrax

Options

parameter required default choices comments
api_key
no
    Rackspace API key (overrides credentials)

    aliases: password
    clear_meta
    no no
    • yes
    • no
    Optionally clear existing metadata when applying metadata to existing objects. Selecting this option is only appropriate when setting type=meta
    container
    yes
      The container to use for file object operations.
      credentials
      no
        File to find the Rackspace credentials in (ignored if api_key and username are provided)

        aliases: creds_file
        dest
        no
          The destination of a "get" operation; i.e. a local directory, "/home/user/myfolder". Used to specify the destination of an operation on a remote object; i.e. a file name, "file1", or a comma-separated list of remote objects, "file1,file2,file17"
          env
          (added in 1.5)
          no
            expires
            no
              Used to set an expiration on a file or folder uploaded to Cloud Files. Requires an integer, specifying expiration in seconds
              meta
              no
                A hash of items to set as metadata values on an uploaded file or folder
                method
                no get
                • get
                • put
                • delete
                The method of operation to be performed. For example, put to upload files to Cloud Files, get to download files from Cloud Files or delete to delete remote objects in Cloud Files
                region
                no DFW
                  Region to create an instance in
                  src
                  no
                    Source from which to upload files. Used to specify a remote object as a source for an operation, i.e. a file name, "file1", or a comma-separated list of remote objects, "file1,file2,file17". src and dest are mutually exclusive on remote-only object operations
                    state
                    no present
                    • present
                    • absent
                    Indicate desired state of the resource
                    structure
                    no yes
                    • True
                    • no
                    Used to specify whether to maintain nested directory structure when downloading objects from Cloud Files. Setting to false downloads the contents of a container to a single, flat directory
                    type
                    no file
                    • file
                    • meta
                    Type of object to do work on
                    Metadata object or a file object
                    username
                    no
                      Rackspace username (overrides credentials)
                      verify_ssl
                      (added in 1.5)
                      no
                        Whether or not to require SSL validation of API endpoints

                        Examples

                        - name: "Test Cloud Files Objects"
                          hosts: local
                          gather_facts: False
                          tasks:
                            - name: "Get objects from test container"
                              rax_files_objects: container=testcont dest=~/Downloads/testcont
                        
                            - name: "Get single object from test container"
                              rax_files_objects: container=testcont src=file1 dest=~/Downloads/testcont
                        
                            - name: "Get several objects from test container"
                              rax_files_objects: container=testcont src=file1,file2,file3 dest=~/Downloads/testcont
                        
                            - name: "Delete one object in test container"
                              rax_files_objects: container=testcont method=delete dest=file1
                        
                            - name: "Delete several objects in test container"
                              rax_files_objects: container=testcont method=delete dest=file2,file3,file4
                        
                            - name: "Delete all objects in test container"
                              rax_files_objects: container=testcont method=delete
                        
                            - name: "Upload all files to test container"
                              rax_files_objects: container=testcont method=put src=~/Downloads/onehundred
                        
                            - name: "Upload one file to test container"
                              rax_files_objects: container=testcont method=put src=~/Downloads/testcont/file1
                        
                            - name: "Upload one file to test container with metadata"
                              rax_files_objects:
                                container: testcont
                                src: ~/Downloads/testcont/file2
                                method: put
                                meta:
                                  testkey: testdata
                                  who_uploaded_this: someuser@example.com
                        
                            - name: "Upload one file to test container with TTL of 60 seconds"
                              rax_files_objects: container=testcont method=put src=~/Downloads/testcont/file3 expires=60
                        
                            - name: "Attempt to get remote object that does not exist"
                              rax_files_objects: container=testcont method=get src=FileThatDoesNotExist.jpg dest=~/Downloads/testcont
                              ignore_errors: yes
                        
                            - name: "Attempt to delete remote object that does not exist"
                              rax_files_objects: container=testcont method=delete dest=FileThatDoesNotExist.jpg
                              ignore_errors: yes
                        
                        - name: "Test Cloud Files Objects Metadata"
                          hosts: local
                          gather_facts: false
                          tasks:
                            - name: "Get metadata on one object"
                              rax_files_objects:  container=testcont type=meta dest=file2
                        
                            - name: "Get metadata on several objects"
                              rax_files_objects:  container=testcont type=meta src=file2,file1
                        
                            - name: "Set metadata on an object"
                              rax_files_objects:
                                container: testcont
                                type: meta
                                dest: file17
                                method: put
                                meta:
                                  key1: value1
                                  key2: value2
                                clear_meta: true
                        
                            - name: "Verify metadata is set"
                              rax_files_objects:  container=testcont type=meta src=file17
                        
                            - name: "Delete metadata"
                              rax_files_objects:
                                container: testcont
                                type: meta
                                dest: file17
                                method: delete
                                meta:
                                  key1: ''
                                  key2: ''
                        
                            - name: "Get metadata on all objects"
                              rax_files_objects:  container=testcont type=meta
                        

                        Notes

                        Note

                        The following environment variables can be used, RAX_USERNAME, RAX_API_KEY, RAX_CREDS_FILE, RAX_CREDENTIALS, RAX_REGION.

                        Note

                        RAX_CREDENTIALS and RAX_CREDS_FILE points to a credentials file appropriate for pyrax. See https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating

                        Note

                        RAX_USERNAME and RAX_API_KEY obviate the use of a credentials file

                        Note

                        RAX_REGION defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)

                        This is a Core Module

                        For more information on what this means please read Core Modules

                        For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.