--- title: Working with Object Storage summary: null url: >- https://www.fastly.com/documentation/guides/platform/object-storage/working-with-object-storage --- To work with Fastly Object Storage, complete the following steps: 1. [Create a bucket](https://www.fastly.com/documentation/guides/platform/object-storage/working-with-object-storage#creating-a-bucket). 2. [Create an access key](https://www.fastly.com/documentation/guides/platform/object-storage/working-with-object-storage#creating-an-access-key) to provide authentication when using the S3-compatible API such as the AWS CLI to interact with your buckets and objects. 3. [Configure a Fastly service](https://www.fastly.com/documentation/guides/platform/object-storage/working-with-object-storage#configuring-your-fastly-service) to serve content from the bucket. 4. [Upload files](https://www.fastly.com/documentation/guides/platform/object-storage/working-with-object-storage#managing-object-storage-buckets-and-objects) to the bucket. 5. [Test](https://www.fastly.com/documentation/guides/platform/object-storage/working-with-object-storage#retrieving-objects) to confirm you can retrieve objects. ## Before you begin Make sure to review the [prerequisites](https://www.fastly.com/documentation/guides/platform/object-storage/about-object-storage#prerequisites), [limitations, and considerations](https://www.fastly.com/documentation/guides/platform/object-storage/about-object-storage#limitations-and-considerations) for using Fastly Object Storage. ## Creating a bucket To create a bucket from the Fastly control panel, complete the following: 1. Log in to the [Fastly control panel](https://manage.fastly.com). 2. Go to **Resources** > [**Object Storage**](https://manage.fastly.com/resources/object-storage). 3. Click **Add bucket**. 4. In the **Bucket name** field, enter a name for the bucket. Bucket names can contain lowercase letters, numbers, periods, and hyphens and must be unique. > **IMPORTANT:** Bucket names cannot start with `fst` or `fastly`. 5. From the **Select a region** menu, select the [Fastly Object Storage region](https://www.fastly.com/documentation/guides/platform/object-storage/working-with-object-storage#using-the-s3-compatible-api) to perform commands against. 6. Click **Create**. After creating a bucket, [create an access key](https://www.fastly.com/documentation/guides/platform/object-storage/working-with-object-storage#creating-an-access-key) used to authenticate when making requests to buckets. ## Creating an access key [Access keys](https://www.fastly.com/documentation/reference/api/services/resources/object-storage-access-keys/) are used to [authenticate](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) requests to buckets when performing various [bucket operations](https://www.fastly.com/documentation/guides/platform/object-storage/working-with-object-storage#compatible-bucket-operations), such as uploading to buckets. The level of access you have to work with these operations depends on the combination of access key properties you select. > **HINT:** \* [Access keys](https://www.fastly.com/documentation/reference/api/services/resources/object-storage-access-keys/) created through the control panel grant access to Fastly Object Storage at the account-level, not the bucket-level. If you want to create access keys with bucket-level access, use the [Fastly API](https://www.fastly.com/documentation/reference/api/services/resources/object-storage-access-keys/). | Access key properties | Access granted | Access key permission | Considerations | | ------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------- | ----------------------------------------------- | | Full access + Read and write scope | Access to all current and future buckets in the account and the ability to read and modify those buckets | `read-write-admin` | Only key type that enables **creating** buckets | | Full access + Read scope | Access to all current and future buckets in the account and the ability to read those buckets | `read-only-admin` | | | Limited access + Read and write scope | Access to specific buckets and the ability to read and modify the contents of those buckets | `read-write-objects` | Buckets must already be created | | Limited access + Read scope | Access to specific buckets and the ability to read the contents of those buckets. | `read-only-objects` | Buckets must already be created | To create an access key: 1. Log in to the [Fastly control panel](https://manage.fastly.com). 2. Go to **Resources** > [**Object Storage**](https://manage.fastly.com/resources/object-storage). 3. Click **Create key**. 4. In the **Description** field, enter a description of the key. 5. In the **Bucket access** field, select whether to give the key **Full access** to current and future buckets or **Limited access** to certain buckets. - **Full access:** grants access to all current and future buckets. - **Limited access:** grants access to select buckets. If you choose this option, use the menu to select specific buckets the key has access to. 6. In the **Scope** field, select the level of access you want available to the key. The first key you create must have read and write access. - **Read:** access to read existing and future buckets. - **Read and write:** access to read and write to existing and future buckets. 7. Click **Create**. 8. Note the access key and secret key details. Record the secret key in a secure location because you won't be able to see it again. Once you have an access key created, [configure your Fastly service](https://www.fastly.com/documentation/guides/platform/object-storage/working-with-object-storage#configuring-your-fastly-service) to serve content from the bucket. ### Managing Object Storage keys Once at least one Object Storage access key is created, you can view details on all Object Storage access keys created on your account from **Resources** > [**Object Storage**](https://manage.fastly.com/resources/object-storage). The Object Storage page displays the following details: - **Access Key ID:** the access key ID returned from the S3-compatible API. - **Description:** a description of the access key. - **Scope:** the level of access available to the access key. - **Buckets:** the buckets the key grants access to. - **Created on:** the date on which the access key was created. Keys cannot be edited, only deleted. If the access key is being used by an active application, deleting it can cause unexpected behavior. To delete an Object Storage access key: 1. Log in to the [Fastly control panel](https://manage.fastly.com). 2. Go to **Resources** > [**Object Storage**](https://manage.fastly.com/resources/object-storage). 3. Click the trash Trash icon to the right of the access key you want to delete. 4. Click **Confirm and delete**. ## Configuring your Fastly service Now that you've created your bucket, you can create and configure a Fastly service to serve content from the bucket: 1. Follow the steps to [create a Fastly CDN service](https://www.fastly.com/documentation/guides/getting-started/services/working-with-cdn-services) and add a [domain](https://www.fastly.com/documentation/guides/getting-started/domains/working-with-domains/working-with-domains#creating-a-domain-for-the-first-time). 2. From the Fastly service configuration, go to **Origins** > **Hosts**. 3. In the **Hostname** field, enter the name of the Fastly Object Storage regional endpoint (e.g., `us-east-1.object.fastlystorage.app`). 4. Click **Add**. 5. Click the pencil Pencil icon to edit the host. 6. In the **Override host** field, enter the same Fastly Object Storage regional endpoint (e.g., `us-east-1.object.fastlystorage.app`). 7. Click **Update**. 8. Go to **VCL** and click **VCL snippets**. 9. Click **Add snippet**. 10. Fill out the **Add VCL snippet** fields as follows: - Using the **Type** controls, select **Regular** to create a regular VCL snippet. - Enter a name for the VCL snippet. - From the **Placement** controls, select **Within subroutine** - From the **Subroutine** menu, select **miss `(vcl_miss)`**. - Leave the **Priority** field set to the default. - In the VCL editor area, paste the following code, which generates the required AWS V4 signature to authenticate requests to your private Fastly Object Storage origin. > **IMPORTANT:** Be sure to replace the placeholder variables `var.fosAccessKey`, `var.fosSecretKey`, `var.fosBucket`, and `var.fosRegion` with your own values. ```vcl # vcl_miss # This snippet signs the backend request to your private Fastly Object Store. declare local var.fosAccessKey STRING; declare local var.fosSecretKey STRING; declare local var.fosBucket STRING; declare local var.fosRegion STRING; declare local var.fosHost STRING; declare local var.canonicalHeaders STRING; declare local var.signedHeaders STRING; declare local var.canonicalRequest STRING; declare local var.canonicalQuery STRING; declare local var.stringToSign STRING; declare local var.dateStamp STRING; declare local var.signature STRING; declare local var.scope STRING; # --- UPDATE THESE VALUES --- set var.fosAccessKey = "YOUR_FOS_ACCESS_KEY"; set var.fosSecretKey = "YOUR_FOS_SECRET_KEY"; set var.fosBucket = "my-fos-bucket"; # The name of your bucket set var.fosRegion = "us-east-1"; # The Fastly Object Storage region to send requests # -------------------------- set var.fosHost = var.fosRegion ".object.fastlystorage.app"; if (req.method == "GET" && !req.backend.is_shield) { set bereq.http.x-amz-content-sha256 = digest.hash_sha256(""); set bereq.http.x-amz-date = strftime({"%Y%m%dT%H%M%SZ"}, now); set bereq.http.host = var.fosHost; # The request to FOS must include the bucket name in the path. set bereq.url = "/" var.fosBucket bereq.url; set bereq.url = querystring.remove(bereq.url); set bereq.url = regsuball(urlencode(urldecode(bereq.url.path)), {"%2F"}, "/"); set var.dateStamp = strftime({"%Y%m%d"}, now); set var.canonicalHeaders = "" "host:" bereq.http.host LF "x-amz-content-sha256:" bereq.http.x-amz-content-sha256 LF "x-amz-date:" bereq.http.x-amz-date LF ; set var.canonicalQuery = ""; set var.signedHeaders = "host;x-amz-content-sha256;x-amz-date"; set var.canonicalRequest = "" "GET" LF bereq.url.path LF var.canonicalQuery LF var.canonicalHeaders LF var.signedHeaders LF digest.hash_sha256("") ; set var.scope = var.dateStamp "/" var.fosRegion "/s3/aws4_request"; set var.stringToSign = "" "AWS4-HMAC-SHA256" LF bereq.http.x-amz-date LF var.scope LF regsub(digest.hash_sha256(var.canonicalRequest),"^0x", "") ; set var.signature = digest.awsv4_hmac( var.fosSecretKey, var.dateStamp, var.fosRegion, "s3", var.stringToSign ); set bereq.http.Authorization = "AWS4-HMAC-SHA256 " "Credential=" var.fosAccessKey "/" var.scope ", " "SignedHeaders=" var.signedHeaders ", " "Signature=" + regsub(var.signature,"^0x", "") ; # Unset headers not needed by the origin unset bereq.http.Accept; unset bereq.http.Accept-Language; unset bereq.http.User-Agent; unset bereq.http.Fastly-Client-IP; } ``` 11. Click **Add** to create the VCL snippet. 12. From the **Activate** menu, select **Activate on Production** to deploy your configuration changes. Once you have your service configured, [upload files to the bucket](https://www.fastly.com/documentation/guides/platform/object-storage/working-with-object-storage#managing-object-storage-buckets-and-objects) before you activate. ## Managing Object Storage buckets and objects You can manage and interact with your buckets and object, including uploading files to buckets, using the S3-compatible API, such as the AWS CLI. No matter what method you choose, you must ensure requests are sent to one of the following regional Object Storage endpoints: - `us-west-1.object.fastlystorage.app` - `us-central-1.object.fastlystorage.app` - `us-east-1.object.fastlystorage.app` - `uk-east-1.object.fastlystorage.app` - `eu-west-1.object.fastlystorage.app` - `eu-central.object.fastlystorage.app` - `eu-south-1.object.fastlystorage.app` - `jp-central-1.object.fastlystorage.app` - `au-east-1.object.fastlystorage.app` These endpoints are different from AWS regions. Make sure you set all applicable region options, like `LocationConstraint`, to the correct Object Storage region name or you may receive an `InvalidRequest` error. > **HINT:** Check out our [On-Demand Migration for Fastly Object Storage](https://www.fastly.com/documentation/guides/platform/object-storage/on-demand-migration-for-object-storage/) guide to learn how you can migrate only your required working set of data to reduce egress charges from your source provider. ### Using the AWS CLI To use the AWS CLI, first check out our guide on configuring the Amazon Web Services (AWS) CLI to [use Fastly Object Storage as an S3 backend](https://www.fastly.com/documentation/guides/platform/object-storage/aws-cli-for-fastly-object-storage). Once a bucket is created, you can upload files by running the following command from the AWS CLI. Use the `--profile` flag to indicate which [Fastly Object Storage region](https://www.fastly.com/documentation/guides/platform/object-storage/working-with-object-storage#using-the-s3-compatible-api) to perform commands against. The following command uploads a file called `my-photo.jpg` to the bucket `my-bucket`: ```term aws s3 cp my-photo.jpg s3://my-bucket/my-photo.jpg --profile fastly-us-east-1 ``` > **HINT:** For additional details on this command, refer to the [AWS CLI documentation](https://docs.aws.amazon.com/cli/v1/userguide/cli-services-s3-commands.html). For common commands used to work with buckets and objects via the AWS CLI, refer to the [AWS CLI documentation](https://docs.aws.amazon.com/cli/v1/userguide/cli-services-s3-commands.html) ### Using the S3-compatible API Object Storage supports specific processing operations for the S3-compatible API. These operations are categorized into two groups, each with differing prices. Refer to the [Object Storage product description](https://docs.fastly.com/products/object-storage) for more information on how operations are billed. **Class A operations** - [CreateBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html) - [DeleteBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html) - [HeadBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html) - [GetBucketLocation](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLocation.html) - [ListBuckets](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html) - [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) - [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html) - [DeleteObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html) - [DeleteObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) - [ListObjectsV1](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html) - [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) - [CreateMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html) - [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) - [AbortMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html) - [ListMultipartUploads](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html) - [ListParts](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html) - [UploadPart](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html) - [UploadPartCopy](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html) **Class B operations** - [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) - [HeadObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) Before using the S3-compatible API, note the following considerations: - In order to work with S3-compatible API, you must use an access key with **full** access to all buckets and **read and write** scope. - Requests must be sent to one of the following regional Object Storage endpoints, and you must include the matching region in the `credential scope` portion of the AWS V4 signature: - `us-west-1.object.fastlystorage.app` - `us-central-1.object.fastlystorage.app` - `us-east-1.object.fastlystorage.app` - `uk-east-1.object.fastlystorage.app` - `eu-west-1.object.fastlystorage.app` - `eu-central.object.fastlystorage.app` - `eu-south-1.object.fastlystorage.app` - `jp-central-1.object.fastlystorage.app` - `au-east-1.object.fastlystorage.app` > **HINT:** The regional Object Storage endpoints are different from AWS regions. Make sure you set all region options, like `LocationConstraint`, to the correct Object Storage region name or you may receive an `InvalidRequest` error. - Object Storage doesn't support using bucket names in the hostname (i.e., `https://my-bucket.us-east.object.fastlystorage.app`). ## Retrieving objects Test that you can retrieve your object through the Fastly CDN by opening a web browser and navigating to the URL for your object. The path for the object should be `https:///`. For example, `https://example.com/my-photo.jpg`. If successful, you'll see your image served from the Fastly edge. ## Related content - [Object Storage Access Keys API](https://www.fastly.com/documentation/reference/api/services/resources/object-storage-access-keys/) - [Object Storage Product API](https://www.fastly.com/documentation/reference/api/products/object_storage/) - [AWS CLI for Fastly Object Storage](https://www.fastly.com/documentation/guides/platform/object-storage/aws-cli-for-fastly-object-storage)