From 30f92a48054a64154a902d01ad9bb1ddfbbe9aff Mon Sep 17 00:00:00 2001 From: Kyle Rames Date: Wed, 27 Feb 2013 14:28:49 -0600 Subject: [PATCH 1/5] [rackspace] initial checkin for the Getting started with Cloud Files document. --- lib/fog/rackspace/docs/compute_v2.md | 15 +- lib/fog/rackspace/docs/getting_started.md | 4 +- lib/fog/rackspace/docs/storage.md | 453 ++++++++++++++++++++++ 3 files changed, 463 insertions(+), 9 deletions(-) create mode 100644 lib/fog/rackspace/docs/storage.md diff --git a/lib/fog/rackspace/docs/compute_v2.md b/lib/fog/rackspace/docs/compute_v2.md index 1e0fdcf4d..b81360884 100644 --- a/lib/fog/rackspace/docs/compute_v2.md +++ b/lib/fog/rackspace/docs/compute_v2.md @@ -1,6 +1,6 @@ #Next Generation Cloud Servers™ (compute_v2) -This document explains how to get started using Next Gneration Cloud Servers™ with Fog. It assumes you have read the [Getting Started with Fog and the Rackspace Open Cloud](/getting_started.md) document. +This document explains how to get started using Next Gneration Cloud Servers™ with Fog. It assumes you have read the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document. ## Starting irb console @@ -31,7 +31,7 @@ Next, create a connection to the Next Gen Cloud Servers™: :connection_options => {} # Optional }) -To learn more about obtaining cloud credentials visit the [Getting Started with Fog and the Rackspace Open Cloud](/getting_started.md) document. +To learn more about obtaining cloud credentials visit the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document. By default `Fog::Compute` will connect to the DFW region. You can specify alternative regions using the key `:rackspace_endpoint ` with one of the following values: @@ -106,7 +106,7 @@ To see a list of requests supported by the service: This returns: - :list_servers, :get_server, :create_server, :update_server, :delete_server, :change_server_password, :reboot_server, :rebuild_server, :resize_server, :confirm_resize_server, :revert_resize_server, :list_images, :get_image, :list_flavors, :get_flavor, :attach_volume, :get_attachment, :list_attachments, :delete_attachment] + :list_servers, :get_server, :create_server, :update_server, :delete_server, :change_server_password, :reboot_server, :rebuild_server, :resize_server, :confirm_resize_server, :revert_resize_server, :list_images, :get_image, :list_flavors, :get_flavor, :attach_volume, :get_attachment, :list_attachments, :delete_attachment #### Example Request @@ -125,16 +125,16 @@ To view the status of the response: **Note**: *Fog is aware valid HTTP response statuses for each request type. If an unexpected HTTP response status occurs, Fog will raise an exception.* -To view response body: +To view response header: - request.body + response.body This will return: {"flavors"=>[{"id"=>"2", "links"=>[{"href"=>"https://ord.servers.api.rackspacecloud.com/v2/772045/flavors/2", "rel"=>"self"}, {"href"=>"https://ord.servers.api.rackspacecloud.com/772045/flavors/2", "rel"=>"bookmark"}], "name"=>"512MB Standard Instance"}, {"id"=>"3", "links"=>[{"href"=>"https://ord.servers.api.rackspacecloud.com/v2/772045/flavors/3", "rel"=>"self"}, {"href"=>"https://ord.servers.api.rackspacecloud.com/772045/flavors/3", "rel"=>"bookmark"}], "name"=>"1GB Standard Instance"}, {"id"=>"4", "links"=>[{"href"=>"https://ord.servers.api.rackspacecloud.com/v2/772045/flavors/4", "rel"=>"self"}, {"href"=>"https://ord.servers.api.rackspacecloud.com/772045/flavors/4", "rel"=>"bookmark"}], "name"=>"2GB Standard Instance"}, {"id"=>"5", "links"=>[{"href"=>"https://ord.servers.api.rackspacecloud.com/v2/772045/flavors/5", "rel"=>"self"}, {"href"=>"https://ord.servers.api.rackspacecloud.com/772045/flavors/5", "rel"=>"bookmark"}], "name"=>"4GB Standard Instance"}, {"id"=>"6", "links"=>[{"href"=>"https://ord.servers.api.rackspacecloud.com/v2/772045/flavors/6", "rel"=>"self"}, {"href"=>"https://ord.servers.api.rackspacecloud.com/772045/flavors/6", "rel"=>"bookmark"}], "name"=>"8GB Standard Instance"}, {"id"=>"7", "links"=>[{"href"=>"https://ord.servers.api.rackspacecloud.com/v2/772045/flavors/7", "rel"=>"self"}, {"href"=>"https://ord.servers.api.rackspacecloud.com/772045/flavors/7", "rel"=>"bookmark"}], "name"=>"15GB Standard Instance"}, {"id"=>"8", "links"=>[{"href"=>"https://ord.servers.api.rackspacecloud.com/v2/772045/flavors/8", "rel"=>"self"}, {"href"=>"https://ord.servers.api.rackspacecloud.com/772045/flavors/8", "rel"=>"bookmark"}], "name"=>"30GB Standard Instance"}]} -To learn more about Compute request methods refer to [rdoc](http://rubydoc.info/gems/fog/Fog/Compute/Rackspace/Real#reboot_server-instance_method). To learn more about Excon refer to [Excon GitHub repo](https://github.com/geemus/excon). +To learn more about Compute request methods refer to [rdoc](http://rubydoc.info/gems/fog/Fog/Compute/Rackspace/Real). To learn more about Excon refer to [Excon GitHub repo](https://github.com/geemus/excon). ### Model Layer Fog models behave in a manner similar to `ActiveModel`. Models will generally respond to `create`, `save`, `persisted?`, `destroy`, `reload` and `attributes` methods. Additionally, fog will automatically create attribute accessors. @@ -450,6 +450,7 @@ Fog can wait for the server to become ready as follows: **Note**: *The `Fog::Compute::RackspaceV2::Server` instance returned from the create method contains a `password` attribute. The `password` attribute will NOT be present in subsequent retrievals either through `service.servers` or `server.servers.get my_server_id`*. ### Additional Parameters + The `create` method also supports the following key values: @@ -468,7 +469,7 @@ The `create` method also supports the following key values: - +
:personality File path and contents. Refer to Next Gen Server API documentation - Server Personality.
## Update Server diff --git a/lib/fog/rackspace/docs/getting_started.md b/lib/fog/rackspace/docs/getting_started.md index 877654d42..899fb7397 100644 --- a/lib/fog/rackspace/docs/getting_started.md +++ b/lib/fog/rackspace/docs/getting_started.md @@ -57,8 +57,8 @@ You should now be able to execute the following command to see a list of service These services can be explored in further depth in the following documents: -* [Next Generation Cloud Servers™ (compute_v2)](/cloud_servers.md) -* Cloud Files™ (storage) +* [Next Generation Cloud Servers™ (compute_v2)](compute_v2.md) +* [Cloud Files™ (storage)](storage.md) * Cloud Block Storage (block_storage) **Note**: *The compute service provides an interface to the First Geneneration Cloud Servers™ (compute). This service is deprecated. Users are encouraged to use Next Geneneration Cloud Servers™ (compute_v2).* diff --git a/lib/fog/rackspace/docs/storage.md b/lib/fog/rackspace/docs/storage.md new file mode 100644 index 000000000..2264d2ea5 --- /dev/null +++ b/lib/fog/rackspace/docs/storage.md @@ -0,0 +1,453 @@ +#Cloud Files™ (storage) + +This document explains how to get started using Cloud Files™ with Fog. It assumes you have read the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document. + + +## Starting irb console +Start by executing the following command: + + irb + +Once `irb` has launched you need to require the Fog library. + +If using Ruby 1.8.x execute: + + require 'rubygems' + require 'fog' + +If using Ruby 1.9.x execute: + + require 'fog' + +## Create Service + +Next, create a connection to the Cloud Files™. + +Using a US based account: + + service = Fog::Storage.new({ + :provider => 'Rackspace', # Rackspace Fog provider + :rackspace_username => RACKSPACE_USER_NAME, # Your Rackspace Username + :rackspace_api_key => RACKSPACE_API, # Your Rackspace API key + :rackspace_region => :ord # Defaults to :dfw + :connection_options => {} # Optional + }) + +Using a UK based account: + + service = Fog::Storage.new({ + :provider => 'Rackspace', # Rackspace Fog provider + :rackspace_username => RACKSPACE_USER_NAME, # Your Rackspace Username + :rackspace_api_key => RACKSPACE_API, # Your Rackspace API key + :rackspace_auth_url => Fog::Rackspace::UK_ENDPOINT + :rackspace_region => :lon + :connection_options => {} # Optional + }) + +To learn more about obtaining cloud credentials visit the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document. + +By default `Fog::Storage` will authenticate against the US authentication endpoint and connect to the DFW region. You can specify alternative authentication endpoints using the key `:rackspace_auth_url`. Please refer to [Alternate Authentication Endpoints](http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/Endpoints-d1e180.html) for a list of alernative Rackspace authentication endpoints. + +Alternative regions are specified using the key `:rackspace_region `. A list of regions available for Cloud Files™ can be found by executing the following: + + identity_service = Fog::Identity({ + :provider => 'Rackspace', # Rackspace Fog provider + :rackspace_username => RACKSPACE_USER_NAME, # Your Rackspace Username + :rackspace_api_key => RACKSPACE_API, # Your Rackspace API key + :rackspace_auth_url => Fog::Rackspace::UK_ENDPOINT # Not specified for US Cloud + }) + + identity_service.service_catalog.display_service_regions :cloudFiles + + +**Note**: *A`Fog::Storage` instance is needed for desired region.* + +### Optional Service Parameters + +The Storage service supports the following additional parameters: + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescription
:rackspace_servicenetIf set to true, the service will access Cloud Files™ using the internal Rackspace Service Net. This option should only be used for internal network connections.
:rackspace_cdn_sslIf set to true, the public_url method will return the SSL based URLs.
:persistentIf set to true, the service will use a persistent connection.
:rackspace_storage_urlThe endpoint for the Cloud Files™ service. By default, Fog::Storage will pick the appropriate endpoint for region. This option will typically only be used for Rackspace Private Cloud Access.
:rackspace_cdn_urlThe endpoint for the CDN service. By default, Fog::Storage pick the appropriate endpoint for region. This option will typically only be used for Rackspace Private Cloud Access.
+ + +### Optional Connection Parameters + +Fog supports passing additional connection parameters to its underlying HTTP library (Excon) using `:connection_options`. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescription
:connect_timeoutConnection timeout (default: 60 seconds)
:read_timeoutRead timeout for connection (default: 60 seconds)
:write_timeoutWrite timeout for connection (default: 60 seconds)
:proxyProxy for HTTP and HTTPS connections
:ssl_ca_pathPath to SSL certificate authorities
:ssl_ca_fileSSL certificate authority file
:ssl_verify_peerSSL verify peer (default: true)
+ + +## Fog Abstractions +Fog provides both a **model** and **request** abstraction. The request abstraction provides the most efficient interface and the model abstraction wraps the request abstraction to provide a convenient `ActiveModel` like interface. + +### Request Layer +The request abstraction maps directly to the [Cloud Files™ API](http://docs.rackspace.com/files/api/v1/cf-devguide/content/Overview-d1e70.html). It provides the most efficient interface to the Rackspace Open Cloud. + +To see a list of requests supported by the storage service: + + service.requests + +This returns: + + :copy_object, :delete_container, :delete_object, :get_container, :get_containers, :get_object, :get_object_https_url, :head_container, :head_containers, :head_object, :put_container, :put_object, :put_object_manifest, :post_set_meta_temp_url_key + +To see a list of requests supported by the CDN service: + + service.cdn.requests + +This returns: + + :get_containers, :head_container, :post_container, :put_container, :delete_object + + +#### Example Request + +To request a view account details: + + response = service.head_containers + +This returns in the following `Excon::Response`: + + #"2563554", "Date"=>"Thu, 21 Feb 2013 21:57:02 GMT", "X-Account-Meta-Temp-Url-Key"=>"super_secret_key", "X-Timestamp"=>"1354552916.82056", "Content-Length"=>"0", "Content-Type"=>"application/json; charset=utf-8", "X-Trans-Id"=>"txe934924374a744c8a6c40dd8f29ab94a", "Accept-Ranges"=>"bytes", "X-Account-Container-Count"=>"7", "X-Account-Object-Count"=>"5"}, @status=204, @body=""> + +To view the status of the response: + + response.status + +**Note**: *Fog is aware valid HTTP response statuses for each request type. If an unexpected HTTP response status occurs, Fog will raise an exception.* + +To view response body: + + response.headers + +This will return: + + {"X-Account-Bytes-Used"=>"2563554", "Date"=>"Thu, 21 Feb 2013 21:57:02 GMT", "X-Account-Meta-Temp-Url-Key"=>"super_secret_key", "X-Timestamp"=>"1354552916.82056", "Content-Length"=>"0", "Content-Type"=>"application/json; charset=utf-8", "X-Trans-Id"=>"txe934924374a744c8a6c40dd8f29ab94a", "Accept-Ranges"=>"bytes", "X-Account-Container-Count"=>"7", "X-Account-Object-Count"=>"5"} + + +To learn more about `Fog::Storage` request methods refer to [rdoc](http://rubydoc.info/gems/fog/Fog/Storage/Rackspace/Real). To learn more about Excon refer to [Excon GitHub repo](https://github.com/geemus/excon). + +### Model Layer +Fog models behave in a manner similar to `ActiveModel`. Models will generally respond to `create`, `save`, `destroy`, `reload` and `attributes` methods. Additionally, fog will automatically create attribute accessors. + +Here is a summary of common model methods: + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
create + Accepts hash of attributes and creates object.
+ Note: creation is a non blocking call and you will be required to wait for a valid state before using resulting object. +
saveSaves object.
+ Note: not all objects support updating object.
destroy + Destroys object.
+ Note: this is a non blocking call and object deletion might not be instantaneous. +
reloadUpdates object with latest state from service.
attributesReturns a hash containing the list of model attributes and values.
identity + Returns the identity of the object.
+ Note: This might not always be equal to object.id. +
+ +The remainder of this document details the model abstraction. + +**Note:** *Fog refers to Rackspace Cloud containers as directories.* + +## List Directories + +To retrieve a list of directories: + + service.directories + +This returns a collection of `Fog::Storage::Rackspace::Directory` models: + + , + , + ... + +## Get Directory + +To retrieve a specific directory: + + service.directories.get "blue" + +This returns a `Fog::Storage::Rackspace::Directory` instance: + + + +## Create Drectory + +To create a directory: + + service.directories.create :key => 'backups' + +To create a directory utilizing CDN: + + service.directories.create :key => 'web-assets', :public => true + +### Additional Parameters + +The `create` method also supports the following key values: + + + + + + + + + + +
KeyDescription
:metadataHash containing directory metadata.
+ + +## Update Directory + +Cloud Files™ supports updating the `public` attribute to enable/disable CDN. + +To update this attribute: + + directory.public = false + directory.save + +## Delete Directory + +To delete a directory: + + directory.destroy + +**Note**: *Directory must be empty before it can be deleted.* + +## List Files + +To list files in a directory: + + directory.files + +## Upload Files + +To upload a file into a directory: + + file = directory.files.create :key => 'space.jpg', :body => File.open "space.jpg" + +### Additional Parameters + +The `create` method also supports the following key values: + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescription
:content_typeThe content type of the object. Cloud Files™ will attempt to auto detect this value if omitted.
:access_control_allow_originURLs can make Cross Origin Requests. Format is http://www.example.com. Separate URLs with a space. An asterisk (*) allows all. Please refer to CORS Container Headers for more information.
:originThe origin is the URI of the object's host.
:etagThe MD5 checksum of your object's data. If specified, Cloud Files™ will validate the integrity of the uploaded object.
:metadataHash containing file metadata.
+ +## Download Files + +To download a file from a private or public directory: + + file = directory.files.get('germany.jpg') + File.open('germany.jpg', 'w') {|f| f.write(file.body) } + +## Accessing Files Through CDN + +The CDN service offers several different URLs to access your files. + +The simpiest is with the default container URL. This can be accessed as follows: + + file.public_url + +For a more user friendly URL, you can create a `CNAME` DNS record pointing the URL generated by the `public_url` method. Then set the`CNAME` on the `Directory` object using the attribute `cdn_cname`. Note, that the `cdn_cname` attribute does not persist and will need to be specified every time a directory object is retrieved. + +To access the file using SSL, you will need to specify the option `:rackspace_cdn_ssl => true` when creating `Fog::Storage` service. This will cause the `public_url` method to return the SSL secured URL. + +To stream content use the following: + + file.streaming_url + +To stream video for iOS devices without needing to convert your video use the following: + + file.ios_url + + +## Metadata + +You can access metadata as an attribute on both `Fog::Storage::Rackspace::Directory` and `Fog::Storage::Rackspace::File`. + +This example demonstrates how to iterate through a directory's metadata: + + directory.metadata.each_pair {|metadatum| puts "#{metadatum.key}: #{metadatum.value}" } + +You can update and retrieve metadata in a manner similar to a hash: + + directory.metadata[:thumbnails] + + file.metadata[:environment] = "development" + +Directory metadata is saved when the directory is saved and File metadata is set when the file is saved: + + directory.save + + file.save + +Metadata is reloaded when directory or file is reloaded: + + directory.reload + + file.reload + +## Copy File + +Cloud Files™ supports copying files. If you wanted to copy files into a container named "trip" with a name of "europe.jpg" you would do the following: + + file.copy("trip", "europe.jpg") + +To move or rename a file, you would perform a copy operation and then delete the old file like so: + + file.copy("trip", "germany.jpg") + file.destroy + +## Delete File + +To delete a file: + + file.destroy + +## CDN Purge + +To immediately remove a file from the CDN network use the following: + + file.purge_from_cdn + +You may only purge up to 25 objects per day and thus this should only be used in situations where there could be serious personal, business, or security consequences if it remained in the CDN. To purge a directory, please contact Rackspace support. + +**Note**: *You may only **PURGE** up to 25 objects per day. Any attempt to purge more than this will result in a 498 status code error (Rate Limited).* + +## Account Information + +To view Cloud Files™ usage, you would execute the following: + + service.account + +This will return: + + + From fa8c2984c7cdca8a6dd00b4bd400518b8b2e8333 Mon Sep 17 00:00:00 2001 From: Kyle Rames Date: Fri, 1 Mar 2013 13:47:51 -0600 Subject: [PATCH 2/5] [rackspace|storage] adding rackspace storage docs; general edits on other rackspace documents --- lib/fog/rackspace/docs/compute_v2.md | 23 +++++----- lib/fog/rackspace/docs/getting_started.md | 2 +- lib/fog/rackspace/docs/storage.md | 54 +++++++++++------------ lib/fog/rackspace/examples/README.md | 2 +- 4 files changed, 40 insertions(+), 41 deletions(-) diff --git a/lib/fog/rackspace/docs/compute_v2.md b/lib/fog/rackspace/docs/compute_v2.md index b81360884..4d19628e6 100644 --- a/lib/fog/rackspace/docs/compute_v2.md +++ b/lib/fog/rackspace/docs/compute_v2.md @@ -31,7 +31,7 @@ Next, create a connection to the Next Gen Cloud Servers™: :connection_options => {} # Optional }) -To learn more about obtaining cloud credentials visit the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document. +To learn more about obtaining cloud credentials refer to the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document. By default `Fog::Compute` will connect to the DFW region. You can specify alternative regions using the key `:rackspace_endpoint ` with one of the following values: @@ -53,7 +53,7 @@ By default `Fog::Compute` will connect to the DFW region. You can specify altern London Region -**Note**: *A`Fog::Compute` instance is needed for desired region.* +**Note**: A`Fog::Compute` instance is needed for the desired region. ### Optional Connection Parameters @@ -123,7 +123,7 @@ To view the status of the response: response.status -**Note**: *Fog is aware valid HTTP response statuses for each request type. If an unexpected HTTP response status occurs, Fog will raise an exception.* +**Note**: Fog is aware valid HTTP response statuses for each request type. If an unexpected HTTP response status occurs, Fog will raise an exception. To view response header: @@ -235,7 +235,7 @@ This returns a collection of `Fog::Compute::RackspaceV2::Image` models: >, … -**Note**: *In order to speed up access `service.images` does not retrieve all attribute values. To retrieve additional details you will either need to `reload` each individual image or use the request abstraction.* +**Note**: In order to speed up access `service.images` does not retrieve all attribute values. To retrieve additional details you will either need to `reload` each individual image or use the request abstraction. ## Get Image @@ -261,8 +261,7 @@ This returns an `Fog::Compute::RackspaceV2::Image` instance: links=[{"href"=>"https://ord.servers.api.rackspacecloud.com/v2/772045/images/8a3a9f96-b997-46fd-b7a8-a9e740796ffd", "rel"=>"self"}, {"href"=>"https://ord.servers.api.rackspacecloud.com/772045/images/8a3a9f96-b997-46fd-b7a8-a9e740796ffd", "rel"=>"bookmark"}, {"href"=>"https://ord.images.api.rackspacecloud.com/772045/images/8a3a9f96-b997-46fd-b7a8-a9e740796ffd", "type"=>"application/vnd.openstack.image", "rel"=>"alternate"}] > -**Note**: *This request populates all Image attributes.* - +**Note**: This request populates all Image attributes. ## List Flavors @@ -292,7 +291,7 @@ This returns a collection of `Fog::Compute::RackspaceV2::Flavor` models: >, … -**Note**: *In order to speed up access `service.flavors` does not retrieve all attribute values. To retrieve additional details you will either need to `reload` each individual flavor or use the request abstraction.* +**Note**: In order to speed up access `service.flavors` does not retrieve all attribute values. To retrieve additional details you will either need to `reload` each individual flavor or use the request abstraction. ## Get Flavor @@ -312,7 +311,7 @@ This returns a `Fog::Compute::RackspaceV2::Flavor` instance: links=[{"href"=>"https://dfw.servers.api.rackspacecloud.com/v2/772045/flavors/2", "rel"=>"self"}, {"href"=>"https://dfw.servers.api.rackspacecloud.com/772045/flavors/2", "rel"=>"bookmark"}] > -**Note**: *This request populates all Flavor attributes.* +**Note**: This request populates all Flavor attributes. ## List Servers @@ -447,7 +446,7 @@ Fog can wait for the server to become ready as follows: server.wait_for { ready? } -**Note**: *The `Fog::Compute::RackspaceV2::Server` instance returned from the create method contains a `password` attribute. The `password` attribute will NOT be present in subsequent retrievals either through `service.servers` or `server.servers.get my_server_id`*. +**Note**: The `Fog::Compute::RackspaceV2::Server` instance returned from the create method contains a `password` attribute. The `password` attribute will NOT be present in subsequent retrievals either through `service.servers` or `server.servers.get my_server_id`. ### Additional Parameters @@ -485,14 +484,14 @@ To update these attributes: Additional information about server access addresses can be found [here](http://docs.rackspace.com/servers/api/v2/cs-devguide/content/Server_Primary_Addresses-d1e2558.html). -**Note**: *Updating the server name does not change the host name. Names are not guaranteed to be unique.* +**Note**: Updating the server name does not change the host name. Names are not guaranteed to be unique. ## Delete Server To delete a server: server.destroy -**Note**: *The server is not immediately destroyed, but it does occur shortly there after.* +**Note**: The server is not immediately destroyed, but it does occur shortly there after. ## Metadata You can access metadata as an attribute on both `Fog::Compute::RackspaceV2::Server` and `Fog::Compute::RackspaceV2::Metadata::Image`. You can specify metadata during creation of a server or an image. Please refer to [Create Server](#create-server) or [Create Image](#create-image) sections for more information. @@ -596,7 +595,7 @@ In this case, `wait_for` is waiting for the server to become `VERIFY_READY` and Once a server enters the `VERIFY_RESIZE` we will need to call `confirm_resize` to confirm the server was properly resized or `revert_resize` to rollback to the old size/flavor. -**Note:** *A server will automatically confirm resize after 24 hours.* +**Note:** A server will automatically confirm resize after 24 hours. To confirm resize: diff --git a/lib/fog/rackspace/docs/getting_started.md b/lib/fog/rackspace/docs/getting_started.md index 899fb7397..7d54bf763 100644 --- a/lib/fog/rackspace/docs/getting_started.md +++ b/lib/fog/rackspace/docs/getting_started.md @@ -61,7 +61,7 @@ These services can be explored in further depth in the following documents: * [Cloud Files™ (storage)](storage.md) * Cloud Block Storage (block_storage) -**Note**: *The compute service provides an interface to the First Geneneration Cloud Servers™ (compute). This service is deprecated. Users are encouraged to use Next Geneneration Cloud Servers™ (compute_v2).* +**Note**: The compute service provides an interface to the First Geneneration Cloud Servers™ (compute). This service is deprecated. Users are encouraged to use Next Geneneration Cloud Servers™ (compute_v2). ## Additional Resources * [fog.io](http://fog.io) diff --git a/lib/fog/rackspace/docs/storage.md b/lib/fog/rackspace/docs/storage.md index 2264d2ea5..09f0d84a7 100644 --- a/lib/fog/rackspace/docs/storage.md +++ b/lib/fog/rackspace/docs/storage.md @@ -1,6 +1,6 @@ #Cloud Files™ (storage) -This document explains how to get started using Cloud Files™ with Fog. It assumes you have read the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document. +This document explains how to get started using Cloud Files with Fog. It assumes you have read the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document. ## Starting irb console @@ -21,7 +21,7 @@ If using Ruby 1.9.x execute: ## Create Service -Next, create a connection to the Cloud Files™. +Next, create a connection to Cloud Files. Using a US based account: @@ -44,11 +44,11 @@ Using a UK based account: :connection_options => {} # Optional }) -To learn more about obtaining cloud credentials visit the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document. +To learn more about obtaining cloud credentials refer to the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document. -By default `Fog::Storage` will authenticate against the US authentication endpoint and connect to the DFW region. You can specify alternative authentication endpoints using the key `:rackspace_auth_url`. Please refer to [Alternate Authentication Endpoints](http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/Endpoints-d1e180.html) for a list of alernative Rackspace authentication endpoints. +By default `Fog::Storage` will authenticate against the US authentication endpoint and connect to the DFW region. You can specify alternative authentication endpoints using the key `:rackspace_auth_url`. Please refer to [Alternate Authentication Endpoints](http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/Endpoints-d1e180.html) for a list of alternative Rackspace authentication endpoints. -Alternative regions are specified using the key `:rackspace_region `. A list of regions available for Cloud Files™ can be found by executing the following: +Alternative regions are specified using the key `:rackspace_region `. A list of regions available for Cloud Files can be found by executing the following: identity_service = Fog::Identity({ :provider => 'Rackspace', # Rackspace Fog provider @@ -60,7 +60,7 @@ Alternative regions are specified using the key `:rackspace_region `. A list of identity_service.service_catalog.display_service_regions :cloudFiles -**Note**: *A`Fog::Storage` instance is needed for desired region.* +**Note**: A`Fog::Storage` instance is needed for the desired region. ### Optional Service Parameters @@ -73,7 +73,7 @@ The Storage service supports the following additional parameters: :rackspace_servicenet - If set to true, the service will access Cloud Files™ using the internal Rackspace Service Net. This option should only be used for internal network connections. + If set to true, the service will access Cloud Files using the internal Rackspace ServiceNet. This option should only be used for internal network connections. :rackspace_cdn_ssl @@ -85,7 +85,7 @@ The Storage service supports the following additional parameters: :rackspace_storage_url - The endpoint for the Cloud Files™ service. By default, Fog::Storage will pick the appropriate endpoint for region. This option will typically only be used for Rackspace Private Cloud Access. + The endpoint for the Cloud Files service. By default, Fog::Storage will pick the appropriate endpoint for region. This option will typically only be used for Rackspace Private Cloud Access. :rackspace_cdn_url @@ -137,7 +137,7 @@ Fog supports passing additional connection parameters to its underlying HTTP lib Fog provides both a **model** and **request** abstraction. The request abstraction provides the most efficient interface and the model abstraction wraps the request abstraction to provide a convenient `ActiveModel` like interface. ### Request Layer -The request abstraction maps directly to the [Cloud Files™ API](http://docs.rackspace.com/files/api/v1/cf-devguide/content/Overview-d1e70.html). It provides the most efficient interface to the Rackspace Open Cloud. +The request abstraction maps directly to the [Cloud Files API](http://docs.rackspace.com/files/api/v1/cf-devguide/content/Overview-d1e70.html). It provides the most efficient interface to the Rackspace Open Cloud. To see a list of requests supported by the storage service: @@ -170,7 +170,7 @@ To view the status of the response: response.status -**Note**: *Fog is aware valid HTTP response statuses for each request type. If an unexpected HTTP response status occurs, Fog will raise an exception.* +**Note**: Fog is aware of the valid HTTP response statuses for each request type. If an unexpected HTTP response status occurs, Fog will raise an exception. To view response body: @@ -228,7 +228,7 @@ Here is a summary of common model methods: The remainder of this document details the model abstraction. -**Note:** *Fog refers to Rackspace Cloud containers as directories.* +**Note:** Fog refers to Rackspace Cloud containers as directories. ## List Directories @@ -297,7 +297,7 @@ The `create` method also supports the following key values: ## Update Directory -Cloud Files™ supports updating the `public` attribute to enable/disable CDN. +Cloud Files supports updating the `public` attribute to enable/disable CDN. To update this attribute: @@ -310,7 +310,7 @@ To delete a directory: directory.destroy -**Note**: *Directory must be empty before it can be deleted.* +**Note**: Directory must be empty before it can be deleted. ## List Files @@ -335,7 +335,7 @@ The `create` method also supports the following key values: :content_type - The content type of the object. Cloud Files™ will attempt to auto detect this value if omitted. + The content type of the object. Cloud Files will attempt to auto detect this value if omitted. :access_control_allow_origin @@ -347,7 +347,7 @@ The `create` method also supports the following key values: :etag - The MD5 checksum of your object's data. If specified, Cloud Files™ will validate the integrity of the uploaded object. + The MD5 checksum of your object's data. If specified, Cloud Files will validate the integrity of the uploaded object. :metadata @@ -359,20 +359,20 @@ The `create` method also supports the following key values: To download a file from a private or public directory: - file = directory.files.get('germany.jpg') - File.open('germany.jpg', 'w') {|f| f.write(file.body) } + file_object = directory.files.get('germany.jpg') + File.open('germany.jpg', 'w') {|f| f.write(file_object.body) } ## Accessing Files Through CDN The CDN service offers several different URLs to access your files. -The simpiest is with the default container URL. This can be accessed as follows: +The simplest is with the default container URL. This can be accessed as follows: file.public_url -For a more user friendly URL, you can create a `CNAME` DNS record pointing the URL generated by the `public_url` method. Then set the`CNAME` on the `Directory` object using the attribute `cdn_cname`. Note, that the `cdn_cname` attribute does not persist and will need to be specified every time a directory object is retrieved. +For a more user-friendly URL, you can create a `CNAME` DNS record pointing to the URL generated by the `public_url` method. Then set the`CNAME` on the `Directory` object using the attribute `cdn_cname`. Note, that the `cdn_cname` attribute does not persist and will need to be specified every time a directory object is retrieved. -To access the file using SSL, you will need to specify the option `:rackspace_cdn_ssl => true` when creating `Fog::Storage` service. This will cause the `public_url` method to return the SSL secured URL. +To access the file using SSL, you need to specify the option `:rackspace_cdn_ssl => true` when creating `Fog::Storage` service. This will cause the `public_url` method to return the SSL-secured URL. To stream content use the following: @@ -397,7 +397,7 @@ You can update and retrieve metadata in a manner similar to a hash: file.metadata[:environment] = "development" -Directory metadata is saved when the directory is saved and File metadata is set when the file is saved: +Directory metadata is saved when the directory is saved and file metadata is set when the file is saved: directory.save @@ -411,11 +411,11 @@ Metadata is reloaded when directory or file is reloaded: ## Copy File -Cloud Files™ supports copying files. If you wanted to copy files into a container named "trip" with a name of "europe.jpg" you would do the following: +Cloud Files supports copying files. To copy files into a container named "trip" with a name of "europe.jpg" do the following: file.copy("trip", "europe.jpg") -To move or rename a file, you would perform a copy operation and then delete the old file like so: +To move or rename a file, perform a copy operation and then delete the old file: file.copy("trip", "germany.jpg") file.destroy @@ -432,17 +432,17 @@ To immediately remove a file from the CDN network use the following: file.purge_from_cdn -You may only purge up to 25 objects per day and thus this should only be used in situations where there could be serious personal, business, or security consequences if it remained in the CDN. To purge a directory, please contact Rackspace support. +You may only purge up to 25 objects per day and thus this should only be used in situations where there could be serious personal, business, or security consequences if the object remained in the CDN. To purge a directory, please contact Rackspace support. -**Note**: *You may only **PURGE** up to 25 objects per day. Any attempt to purge more than this will result in a 498 status code error (Rate Limited).* +**Note**: You may only **PURGE** up to 25 objects per day. Any attempt to purge more than this will result in a 498 status code error (Rate Limited). ## Account Information -To view Cloud Files™ usage, you would execute the following: +To view Cloud Files usage execute the following: service.account -This will return: +This returns a response similar to the following: Date: Mon, 11 Mar 2013 15:32:54 -0500 Subject: [PATCH 3/5] [rackspace|storage] updating the download file section --- lib/fog/rackspace/docs/storage.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/lib/fog/rackspace/docs/storage.md b/lib/fog/rackspace/docs/storage.md index 09f0d84a7..8c39132f4 100644 --- a/lib/fog/rackspace/docs/storage.md +++ b/lib/fog/rackspace/docs/storage.md @@ -91,6 +91,10 @@ The Storage service supports the following additional parameters: :rackspace_cdn_url The endpoint for the CDN service. By default, Fog::Storage pick the appropriate endpoint for region. This option will typically only be used for Rackspace Private Cloud Access. + + :chunk_size + The chunk size in bytes to use for block transfers. By default, Fog uses 1 MB chunks. + @@ -357,11 +361,25 @@ The `create` method also supports the following key values: ## Download Files -To download a file from a private or public directory: +The most efficient way to download files from a private or public directory is as follows: + + File.open('downloaded-file.jpg', 'w') do | f | + directory.files.get("my_big_file.jpg") do | data, remaining, content_length | + f.syswrite data + end + end + +This will download and save the file in 1 MB chunks. The chunk size can be changed by passing the parameter :chunk_size into the :connection_options hash in the service constructor. + +**Note**: The `body` attribute of file will be empty if a file has been downloaded using this method. + +If a file object has already been loaded into memory, you can save it as follows: - file_object = directory.files.get('germany.jpg') File.open('germany.jpg', 'w') {|f| f.write(file_object.body) } +**Note**: This method is more memory intensive as the entire object is loaded into memory before saving the file as in the example above. + + ## Accessing Files Through CDN The CDN service offers several different URLs to access your files. From 517dfad8e62b57263b863539004ef007d442319e Mon Sep 17 00:00:00 2001 From: Kyle Rames Date: Mon, 11 Mar 2013 16:14:41 -0500 Subject: [PATCH 4/5] [rackspace|storage] updating auth endpoints in documentation --- lib/fog/rackspace/docs/storage.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/lib/fog/rackspace/docs/storage.md b/lib/fog/rackspace/docs/storage.md index 8c39132f4..71222c620 100644 --- a/lib/fog/rackspace/docs/storage.md +++ b/lib/fog/rackspace/docs/storage.md @@ -39,7 +39,7 @@ Using a UK based account: :provider => 'Rackspace', # Rackspace Fog provider :rackspace_username => RACKSPACE_USER_NAME, # Your Rackspace Username :rackspace_api_key => RACKSPACE_API, # Your Rackspace API key - :rackspace_auth_url => Fog::Rackspace::UK_ENDPOINT + :rackspace_auth_url => Fog::Rackspace::UK_AUTH_ENDPOINT :rackspace_region => :lon :connection_options => {} # Optional }) @@ -51,10 +51,10 @@ By default `Fog::Storage` will authenticate against the US authentication endpoi Alternative regions are specified using the key `:rackspace_region `. A list of regions available for Cloud Files can be found by executing the following: identity_service = Fog::Identity({ - :provider => 'Rackspace', # Rackspace Fog provider - :rackspace_username => RACKSPACE_USER_NAME, # Your Rackspace Username - :rackspace_api_key => RACKSPACE_API, # Your Rackspace API key - :rackspace_auth_url => Fog::Rackspace::UK_ENDPOINT # Not specified for US Cloud + :provider => 'Rackspace', # Rackspace Fog provider + :rackspace_username => RACKSPACE_USER_NAME, # Your Rackspace Username + :rackspace_api_key => RACKSPACE_API, # Your Rackspace API key + :rackspace_auth_url => Fog::Rackspace::UK_AUTH_ENDPOINT # Not specified for US Cloud }) identity_service.service_catalog.display_service_regions :cloudFiles From 0b5e636b9f39770e5edeec96dd9299c273e9a059 Mon Sep 17 00:00:00 2001 From: Kyle Rames Date: Mon, 11 Mar 2013 16:20:40 -0500 Subject: [PATCH 5/5] [rackspace|storage] fixing typos --- lib/fog/rackspace/docs/compute_v2.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/fog/rackspace/docs/compute_v2.md b/lib/fog/rackspace/docs/compute_v2.md index 4d19628e6..9c8985b58 100644 --- a/lib/fog/rackspace/docs/compute_v2.md +++ b/lib/fog/rackspace/docs/compute_v2.md @@ -1,6 +1,6 @@ #Next Generation Cloud Servers™ (compute_v2) -This document explains how to get started using Next Gneration Cloud Servers™ with Fog. It assumes you have read the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document. +This document explains how to get started using Next Generation Cloud Servers™ with Fog. It assumes you have read the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document. ## Starting irb console @@ -125,7 +125,7 @@ To view the status of the response: **Note**: Fog is aware valid HTTP response statuses for each request type. If an unexpected HTTP response status occurs, Fog will raise an exception. -To view response header: +To view response body: response.body