Working with Object Storage

To work with Fastly Object Storage, complete the following steps:

Create a bucket.
Create an access key to provide authentication when using the S3-compatible API such as the AWS CLI to interact with your buckets and objects.
Configure a Fastly service to serve content from the bucket.
Upload files to the bucket.
Test to confirm you can retrieve objects.

Before you begin

Make sure to review all prerequisites, limitations, and considerations for using Fastly Object Storage.

Creating a bucket

To create a bucket from the Fastly control panel, complete the following:

Log in to the Fastly control panel.
Go to Resources > Object Storage.
Click Add bucket.
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.
From the Select a region menu, select the Fastly Object Storage region to perform commands against.
Click Create.

After creating a bucket, create an access key used to authenticate when making requests to buckets.

Creating an access key

Access keys are used to authenticate requests to buckets when performing various 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.

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:

Log in to the Fastly control panel.
Go to Resources > Object Storage.
Click Create key.
In the Description field, enter a description of the key.
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.
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.
Click Create.
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 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. 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:

Log in to the Fastly control panel.
Go to Resources > Object Storage.
Click the trash to the right of the access key you want to delete.
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:

Follow the steps to create a Fastly CDN service and add a domain.
From the Fastly service configuration, go to Origins > Hosts.
In the Hostname field, enter the name of the Fastly Object Storage regional endpoint (e.g., us-east.object.fastlystorage.app).
Click Add.
Click the pencil to edit the host.
In the Override host field, enter the same Fastly Object Storage regional endpoint (e.g., us-east.object.fastlystorage.app).
Click Update.
Go to VCL and click VCL snippets.
Click Add snippet.

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_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"; # 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;
}

Click Add to create the VCL snippet.
From the Activate menu, select Activate on Production to deploy your configuration changes.

Once you have your service configured, upload files to the bucket 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-east.object.fastlystorage.app
us-west.object.fastlystorage.app
eu-central.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.

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.

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 to perform commands against.

The following command uploads a file called my-photo.jpg to the bucket my-bucket:

aws s3 cp my-photo.jpg s3://my-bucket/my-photo.jpg --profile fastly-us-east

HINT: For additional details on this command, refer to the AWS CLI documentation.

For common commands used to work with buckets and objects via the AWS CLI, refer to the AWS CLI documentation

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 for more information on how operations are billed.

Class A operations

Class B operations

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-east.object.fastlystorage.app
- us-west.object.fastlystorage.app
- eu-central.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://<your-domain>/<object-name>. For example, https://example.com/my-photo.jpg.

If successful, you'll see your image served from the Fastly edge.

Network services

Security

Compute

Quick start

Building blocks

Integrations

Tutorials

Demos

Use Cases

Code Examples

Starter Kits

Before you begin

Creating a bucket

Creating an access key

Managing Object Storage keys

Configuring your Fastly service

Managing Object Storage buckets and objects

Using the AWS CLI

Using the S3-compatible API

Retrieving objects

Network services

Security

Compute

Quick start

Building blocks

Integrations

Tutorials

Demos

Use Cases

Code Examples

Starter Kits

Working with Object Storage

Before you begin

Creating a bucket

Creating an access key

Managing Object Storage keys

Configuring your Fastly service

Managing Object Storage buckets and objects

Using the AWS CLI

Using the S3-compatible API

Retrieving objects

Related content