Class: Cartage::S3

Inherits:
Plugin
  • Object
show all
Defined in:
lib/cartage/plugins/s3.rb

Overview

Manage packages in remote storage.

Configuration

cartage-s3 is configured in the plugins.s3 section of the Cartage configuration file. It supports two primary keys:

destinations

A dictionary of destinations, as described below, that indicate the remote storage location. The destination keys will be used as the destination value.

destination

The name of the target destination to be used. If missing, uses the default location.

For backwards compatability, a single destination may be specified in-line with these keys. This destination will become the default destination unless one is already specified in the destinations dictionary (which is an error).

Destinations

A destination describes the remote location for packages. It supports two keys:

path

The path or bucket name where the targets will be uploaded.

credentials

A dictionary used to initialize a Fog::Storage object.

Examples

An existing configuration would work implicitly. Assuming an AWS S3 bucket in us-west-2, the two configurations below are identical:

# Implicit
plugins:
  s3:
    path: PATHNAME
    credentials:
      provider: AWS
      aws_access_key_id: YOUR_AWS_ACCESS_KEY_ID
      aws_secret_access_key: YOUR_AWS_SECRET_ACCESS_KEY
      region: us-west-2

# Explicit
plugins:
  s3:
    destination: default
    destinations:
      default:
        path: PATHNAME
        credentials:
          provider: AWS
          aws_access_key_id: YOUR_AWS_ACCESS_KEY_ID
          aws_secret_access_key: YOUR_AWS_SECRET_ACCESS_KEY
          region: us-west-2

A configuration for Rackspace CloudFiles (London datacentre), the explicit configuration would be:

plugins:
  s3:
    destination: rackspace
    destinations:
      rackspace:
        path: PATHNAME
        credentials:
          provider: Rackspace
          rackspace_username: RACKSPACE_USERNAME
          rackspace_api_key: RACKSPACE_API_KEY
          rackspace_auth_url: lon.auth.api.rackspacecloud.com

For Google Cloud Storage, it would be:

plugins:
  s3:
    destination: google
    destinations:
      google:
        path: PATHNAME
        credentials:
          provider: Google
          google_storage_access_key_id: YOUR_SECRET_ACCESS_KEY_ID
          google_storage_secret_access_key: YOUR_SECRET_ACCESS_KEY

Remote Storage Security Considerations

cartage-s3 has multiple modes:

  • Put (cartage s3 put) expects that the target path (or bucket) will already exist and that the user credentials present will grant direct write access to the target path without enumeration.

  • Get (cartage s3 get) expects that direct read access to the target path will be granted.

  • List (cartage s3 ls) expects that listing capability on the target path will be granted.

  • Remove (cartage s3 rm) expects that deletion capability on the target path and files will be granted.

These permissions are only needed for the optionas listed.

Constant Summary collapse

VERSION =

:nodoc:

'2.1.2'

Instance Method Summary collapse

Instance Method Details

#check_config(require_destination: false) ⇒ Object

Check that the configuration is correct. If require_destination is present, an exception will be thrown if a destination is required and not present.



155
156
157
158
 
# File 'lib/cartage/plugins/s3.rb', line 155

def check_config(require_destination: false)
  verify_destinations(cartage.config(for_plugin: :s3).destinations)
  fail "No destination #{name} present" if require_destination && !destination
end

#delete ⇒ Object

Remove the metadata and packages from the remote destination.



142
143
144
145
146
147
148
149
150
 
# File 'lib/cartage/plugins/s3.rb', line 142

def delete
  check_config(require_destination: true)
  cartage.display "Removing packages from #{name}..."
  delete_file Pathname("#{cartage.final_name}-release-hashref.txt")
  delete_file cartage.final_release_metadata_json
  cartage.plugins.request_map(:build_package, :package_name).each do |name|
    delete_file name
  end
end

#get(local_path) ⇒ Object

Get packages and metadata from the remote location into local_path.



119
120
121
122
123
124
125
126
127
 
# File 'lib/cartage/plugins/s3.rb', line 119

def get(local_path)
  check_config(require_destination: true)
  local_path = Pathname(local_path)
  cartage.display "Downloading from #{name} to #{local_path}..."
  get_file local_path, cartage.final_release_metadata_json
  cartage.plugins.request_map(:build_package, :package_name).each do |name|
    get_file local_path, name
  end
end

#list(show_all = false) ⇒ Object

List files in the remote destination. If show_all is false, the default, only files related to the current Cartage configuration will be shown.



132
133
134
135
136
137
138
139
 
# File 'lib/cartage/plugins/s3.rb', line 132

def list(show_all = false)
  check_config(require_destination: true)
  cartage.display "Showing packages in #{name}..."
  connection.directories.get(destination.path).files.each do |file|
    next unless show_all || file.key =~ /#{cartage.name}/
    puts file.key
  end
end

#put ⇒ Object

Put packages and metadata to the remote location.



108
109
110
111
112
113
114
115
 
# File 'lib/cartage/plugins/s3.rb', line 108

def put
  check_config(require_destination: true)
  cartage.display "Uploading to #{name}..."
  put_file cartage.final_release_metadata_json
  cartage.plugins.request_map(:build_package, :package_name).each do |name|
    put_file name
  end
end