Create and manage Anywhere Cache caches

This page shows you how to create and manage Anywhere Cache cache instances.

For information on how to use and manage long-running operations that get initiated from Anywhere Cache asynchronous cache operations, see Use long-running operations.

Before using Anywhere Cache, review the Limitations and restrictions.

Before you begin

To get the permissions that you need to create and manage Anywhere Cache caches, ask your administrator to grant you the Storage Admin (roles/storage.admin) IAM role on the bucket for which you want to create caches.

This predefined role contains the permissions required to create and manage Anywhere Cache caches. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to create and manage Anywhere Cache caches:

storage.anywhereCaches.disable (required for disabling caches)
storage.anywhereCaches.get (required for getting caches)
storage.anywhereCaches.create (required for creating caches)
storage.anywhereCaches.list (required for listing caches)
storage.anywhereCaches.pause (required for pausing caches)
storage.anywhereCaches.resume (required for resuming caches)
storage.anywhereCaches.update (required for updating caches)

You can also get these permissions with custom roles.

For information about granting roles on buckets, see Use IAM with buckets.

In order to manage long-running operations that get initiated from Anywhere Cache methods, you might need additional roles and permissions. See required roles for long-running operations to learn more.

Create a cache

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket for which you want to cache data.
On the Bucket details page, click the Configuration tab.
In the Anywhere Cache section, click Configure cache.

The Edit configuration for <your_bucket_name> page appears for your bucket.
In the Cache regions section, click the region that contains the zones in which you want to create a cache.
In the Cache zones section, select the zones in which you want to create a cache. For each zone you select, specify a Time to live and an Ingest option for the cache.
Click Save configuration.
In the dialogue that appears, click Confirm.

The Operations tab in the Bucket details page opens, which shows you the job status of your create cache operation.

You can also view the status of a bucket's cache directly from the Bucket list page. To do so, complete the following instructions:

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
Click the View Column icon (), select Cache, then click OK.

Command line

Use the gcloud storage buckets anywhere-caches create command:

gcloud storage buckets anywhere-caches create gs://BUCKET_NAME ZONE

Replace:

BUCKET_NAME with the name of the bucket for which you want to cache data. For example, my-bucket.
ZONE with the zone in which the cache will run. For example, us-east1-b.

To create multiple caches at once, you can specify multiple zones. For example, us-east1-b us-east1-c us-east1-d.

Set the following optional flags to have greater control over the creation of the cache:

--ttl: Specify the time to live (TTL) of the data in the cache, in seconds. If unspecified, defaults to 86400s (24 hours).
--admission-policy: Specify at what point data gets ingested into the cache. Values can be ADMIT_ON_FIRST_MISS or ADMIT_ON_SECOND_MISS. If unspecified, defaults to ADMIT_ON_FIRST_MISS.

If successful, the command returns the ID of the long-running operation associated with the AnywhereCache Create operation. You can get details about the long-running operation or cancel the long-running operation to stop the AnywhereCaches Create operation before it completes.

REST APIs

JSON API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.

Create a JSON file that contains the following information:

{
   "zone": "ZONE",
   "ttl": "TIME_TO_LIVE",
   "admissionPolicy": "ADMISSION_POLICY"
}

Replace:

ZONE with the zone in which the cache will run. For example, us-east1-b.
TIME_TO_LIVE with the time to live (TTL) of the data in the cache. The value can be between 1 hour to 7 days, specified in seconds. If unspecified, defaults to 86400s (24 hours).
ADMISSION_POLICY with the admission policy of the cache, which specifies when data gets ingested. Values can be admit-on-first-miss or admit-on-second-miss. If unspecified, defaults to admit-on-first-miss.

Use cURL to call the JSON API with a request to create a cache:

curl -X POST --data-binary @JSON_FILE_NAME \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/anywhereCaches"

Replace:

JSON_FILE_NAME with the name of the JSON file you created in Step 2.
BUCKET_NAME with the name of the bucket for which you want to cache data. For example, my-bucket.

If successful, the operation returns a google.longrunning.Operation. You can get details about the long-running operation or cancel the long-running operation to stop the AnywhereCaches Create operation before it completes.

View a cache

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket associated with the cache you want to view.
On the Bucket details page, click the Configuration tab.
In the Anywhere Cache section, click Edit next to the Cache field.
In the Edit configuration page that appears, select a region to view all the caches within the region's zones.

In the Cache zones pane, you can then view details about each available cache.

Command line

Use the gcloud storage buckets anywhere-caches describe command:

gcloud storage buckets anywhere-caches describe ID

Replace:

ID with the identifier of the cache instance, formulated as BUCKET_NAME/ANYWHERE_CACHE_ID. For example, my-bucket/us-east1-b.

Use the optional raw flag to output a raw API response instead of a standardized API response.

If successful, the command returns an AnywhereCache resource.

REST APIs

JSON API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.

Use cURL to call the JSON API with a request to get a cache:
```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/anywhereCaches/ANYWHERE_CACHE_ID"
```
Replace:
- BUCKET_NAME with the name of the bucket associated with the cache you want to retrieve. For example, my-bucket.
- ANYWHERE_CACHE_ID with the zone in which the cache is located. For example, us-east1-b.

If successful, this operation returns an AnywhereCache resource.

List caches

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket associated with the caches you want to view.
On the Bucket details page, click the Configuration tab.
In the Anywhere Cache section, click Edit next to the Cache field.
In the Edit configuration page that appears, select a region to view all the caches within that region's zones.

All available caches for zones within the region appear in the Cache zones pane.

Command line

Use the gcloud storage buckets anywhere-caches list command:

gcloud storage buckets anywhere-caches list gs://BUCKET_NAME

Replace:

BUCKET_NAME with the name of the bucket associated with the caches you want to list. For example, my-bucket.

If successful, the command returns a list of AnywhereCache resources.

You can optionally use the --raw flag to return a raw API response instead of a standardized response. For more information about controlling listing behaviors, such as paginating results, see the gcloud storage ls documentation.

REST APIs

JSON API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.

Use cURL to call the JSON API with a request to list caches:
```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/anywhereCaches"
```
Replace:
- BUCKET_NAME with the name of the bucket associated with the caches you want to retrieve. For example, my-bucket.
When listing multiple caches, you can paginate results.

If successful, this operation returns a list of AnywhereCache resources. For details on the structure of this response, see the response in the AnywhereCaches List documentation.

Update a cache

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket associated with the cache you want to update.
On the Bucket details page, click the Observability tab, then click Cache in the navigation menu.
Click Edit configuration.
In the Edit configuration page that appears, update the properties of the cache, then click Save.

Command line

Use the gcloud storage buckets anywhere-caches update command:

gcloud storage buckets anywhere-caches update ID

Replace:

ID with the identifier of the cache instance, formulated as BUCKET_NAME/ANYWHERE_CACHE_ID. For example, my-bucket/us-east1-b.

To update multiple caches at once, you can specify multiple identifiers. For example, my-bucket/us-east1-b my-bucket/us-east1-c.

Use the following flags to update the configuration of the cache. If a flag is not specified, the value remains unchanged.

--ttl: Specify the time to live (TTL) of the data in the cache, in seconds.
--admission-policy: Specify at what point data gets ingested into the cache. Values can be ADMIT_ON_FIRST_MISS or ADMIT_ON_SECOND_MISS.

If successful, the command returns the ID of the raw long-running operation associated with the AnywhereCache Update operation. You can get details about the long-running operation.

REST APIs

JSON API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.

Create a JSON file that includes changes to the cache properties you want to update.

{
   "ttl": "TIME_TO_LIVE",
   "admissionPolicy": "ADMISSION_POLICY"
}

Replace:

TIME_TO_LIVE with the TTL of the data in the cache. The value can be between 1 hour to 7 days, specified in seconds. If unspecified, the current value remains used.
ADMISSION_POLICY with the admission policy of the cache, which specifies when data gets ingested. Values can be admit-on-first-miss or admit-on-second-miss. If unspecified, the current value remains used.

The following example updates the cache's TTL to 2 days day and its admission policy to ingest data on the second miss:

{
   "ttl": "172800s",
   "admissionPolicy": "admit-on-second-miss"
}

To apply the new properties, use cURL to call the JSON API with a request to update the cache:
```
curl -X PATCH --data-binary @JSON_FILE_NAME \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/anywhereCaches/ANYWHERE_CACHE_ID"
```
Replace:
- JSON_FILE_NAME with the name of the JSON file you created in Step 2.
- BUCKET_NAME with the name of the bucket associated with the cache you want to update. For example, my-bucket.
- ANYWHERE_CACHE_ID with the identifier of the cache. For example, us-east1-b.

If successful, the operation returns a google.longrunning.Operation. You can get details about the long-running operation.

Pause a cache

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket associated with the cache you want to pause.
On the Bucket details page, click the Observability tab, then click Cache in the navigation menu.
Click Pause/resume a cache.
In the pane that appears, click the Pause cache toggle.
Click Pause/resume.
In the dialogue that appears, click Confirm.

Command line

Use the gcloud storage buckets anywhere-caches pause command:

gcloud storage buckets anywhere-caches pause ID

Replace:

ID with the identifier of the cache instance, formulated as BUCKET_NAME/ANYWHERE_CACHE_ID. For example, my-bucket/us-east1-b.

To pause multiple caches at once, you can specify multiple identifiers. For example, my-bucket/us-east1-b my-bucket/us-east1-c.

If successful, the command returns a success message.

REST APIs

JSON API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.

Use cURL to call the JSON API with a request to pause a cache:
```
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/anywhereCaches/ANYWHERE_CACHE_ID/pause"
```
Replace:
- BUCKET_NAME with the name of the bucket associated with the cache you want to pause. For example, my-bucket.
- ANYWHERE_CACHE_ID with the identifier of the cache. For example, us-east1-b.

If successful, the operation returns a formatted AnywhereCache resource.

Resume a cache

Console

To resume a cache that's been paused, complete the following instructions:

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket associated with the cache you want to resume.
On the Bucket details page, click the Observability tab, then click Cache in the navigation menu.
Click Pause/resume a cache.
In the pane that appears, click the Pause cache toggle.
Click Pause/resume.
In the dialogue that appears, click Confirm.

To resume a cache that's been disabled, complete the following instructions:

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket associated with the cache you want to resume.
On the Bucket details page, click the Observability tab, then click Cache in the navigation menu.
Click Disable/resume a cache.
In the pane that appears, click the Disable cache toggle.
Click Disable/resume.
In the dialogue that appears, click Confirm.

Command line

Use the gcloud storage buckets anywhere-caches resume command:

gcloud storage buckets anywhere-caches resume ID

Replace:

ID with the identifier of the cache instance, formulated as BUCKET_NAME/ANYWHERE_CACHE_ID. For example, my-bucket/us-east1-b.

To resume multiple caches at once, you can specify multiple identifiers. For example, my-bucket/us-east1-b my-bucket/us-east1-c.

If successful, the command returns a formatted AnywhereCache resource.

REST APIs

JSON API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.

Use cURL to call the JSON API with a request to resume a cache:
```
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/anywhereCaches/ANYWHERE_CACHE_ID/resume"
```
Replace:
- BUCKET_NAME with the name of the bucket associated with the cache you want to resume. For example, my-bucket.
- ANYWHERE_CACHE_ID with the identifier of the cache. For example, us-east1-b.

If successful, the operation returns a formatted AnywhereCache resource.

Disable a cache

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket associated with the cache you want to disable.
On the Bucket details page, click the Observability tab, then click Cache in the navigation menu.
Click Disable/resume a cache.
In the pane that appears, click the Disable cache toggle.
Click Disable/resume.
In the dialogue that appears, click Confirm.

Command line

Use the gcloud storage buckets anywhere-caches disable command:

gcloud storage buckets anywhere-caches disable ID

Replace:

ID with the identifier of the cache instance, formulated as BUCKET_NAME/ANYWHERE_CACHE_ID. For example, my-bucket/us-east1-b.

To disable multiple caches at once, you can specify multiple identifiers. For example, my-bucket/us-east1-b my-bucket/us-east1-c.

If successful, the command returns a formatted AnywhereCache resource.

REST APIs

JSON API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.

Use cURL to call the JSON API with a request to disable a cache:
```
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/anywhereCaches/ANYWHERE_CACHE_ID/disable"
```
Replace:
- BUCKET_NAME with the name of the bucket associated with the cache you want to disable. For example, my-bucket.
- ANYWHERE_CACHE_ID with the identifier of the cache. For example, us-east1-b.

If successful, the command returns a formatted AnywhereCache resource.

Monitor cache performance

The Cloud Storage portion of the Google Cloud console provides monitoring charts that let you track the performance of your caches using metrics. These monitoring charts can also be viewed using Cloud Monitoring.

Available charts

Chart	Resource hierarchy level	Description
Byte eviction rate	Bucket	The rate of bytes evicted from the cache, sampled every hour. This data is refreshed more than once an hour to allow time for post processing the data.
Byte eviction rate	Project	The rate of bytes evicted from all the caches of a bucket, sampled every hour. This data is refreshed more than once an hour to allow time for post processing the data.
Bytes in cache	Bucket	The rate of the bytes in the cache, sampled every hour. This data is refreshed more than once an hour to allow time for post processing the data.
Bytes in cache	Project	This rate of bytes in all the caches of a bucket, sampled every hour. This data is refreshed more than once an hour to allow time for post processing the data.
Cache throughput benefit	Project	The rate of the data transfer bandwidth quota for the region, usage of the quota, and extra throughput served by the cache. The extra throughput served by the cache doesn't count towards the quota, therefore, using the cache enables projects to exceed the throughput allowed by the quota.
Hit rate operations	Bucket	The percentage of cache operations serving the requested data from the cache relative to the total cache eligible operations, sampled every 60 seconds. If a read is completely returned from cache the operation counts as a hit. If the read is not returned from the cache or only partially returned from the cache, the operation counts as a miss.
Hit rate operations	Project	The percentage of cache operations serving the requested data from all caches for a bucket relative to the total cache eligible operations, sampled 60 seconds. If a read is completely returned from cache, the operation counts as a hit. If the read is not returned from the cache or only partially returned from the cache, the operation counts as a miss.
Hit rate bytes	Bucket	The percentage of bytes that are served from the cache relative to the total cache eligible bytes, sampled every 60 seconds.
Hit rate bytes	Project	The percentage of bytes that are served from all caches for a bucket relative to the total cache eligible bytes, sampled every 60 seconds.
Ingestion rate raw bytes	Bucket	The rate of raw bytes ingested into each cache, sampled every 60 seconds. All ingested bytes, including non-billable bytes, are used in calculating the value of this metric. This metric is reported in real time.
Ingestion rate raw bytes	Project	The rate of raw bytes ingested into all the caches of a bucket, sampled every 60 seconds. All ingested bytes, including non-billable bytes, are used in calculating the value of this metric. This metric is reported in real time.
Throughput - Cache hit	Bucket	The throughput served from the cache, sampled every 60 seconds.
Throughput - Cache hit	Project	The throughput served from all caches for a bucket, sampled every 60 seconds.
Throughput - Cache miss	Bucket	The throughput that's not served from the cache, sampled every 60 seconds.
Throughput - Cache miss	Project	The throughput that's not served from any of the caches of a bucket, sampled every 60 seconds.

Access charts

Monitoring charts capture data either for individual buckets or for all buckets within a project. The resource hierarchy level that a chart captures determines where you can access the chart.

Access bucket-level charts

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket for which you want to see monitoring charts.
In the Bucket details page, click the Observability tab.
In the navigation menu, select Anywhere Cache.

Monitoring charts are displayed.

Access project-level charts

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the Cloud Storage navigation pane, click Monitoring.
In the menu bar, click Anywhere Cache.

Monitoring charts are displayed.

Use long-running operations

When successfully run, the AnywhereCaches Create and Update operations initiate a long-running operation. You can get and list long-running operations in order to view the details and status of the underlying AnywhereCaches operation, or cancel a long-running operation in order to cancel the underlying AnywhereCaches operation while it's in progress.

For instructions on using long-running operations for Anywhere Cache, see Use long-running operations.

The following example shows a long-running operation that's initiated from an AnywhereCaches Create operation:

done: false
kind: storage#operation
metadata:
  '@type': type.googleapis.com/google.storage.control.v2.CreateAnywhereCacheMetadata
  anywhereCacheId: us-central1-c
  zone: us-central1-c
  ttl: 172800s
  admissionPolicy: admit-on-first-miss
  commonMetadata:
    createTime: '2023-12-14T20:52:00.032Z'
    progressPercent: -1
    requestedCancellation: false
    type: create-anywhere-cache
    updateTime: '2023-12-14T20:52:00.032Z'
name: projects/_/buckets/my-bucket/operations/AULf_KhQxxsWRSn56wv4jfmn3pOu_dKTz9FoYx6S0EzMw5ssR0cXIiorCvHRwqxZnQmWj9jnGpKb3Y6iCD3XM9KLc8EHBm7uig
selfLink: https://www.googleapis.com/storage/v1/b/my-bucket/operations/AULf_KhQxxsWRSn56wv4jfmn3pOu_dKTz9FoYx6S0EzMw5ssR0cXIiorCvHRwqxZnQmWj9jnGpKb3Y6iCD3XM9KLc8EHBm7uig

Retries

Asynchronous AnywhereCaches APIs are idempotent by default. This means that you can safely retry asynchronous AnywhereCaches API calls without concern about modifying resources unintentionally.

For example, say you perform an AnywhereCaches Create operation to create a cache in us-central1-a, which succeeds. If you perform a subsequent AnywhereCaches Create operation using the same zone that succeeds, the request returns the same long-running operation as the previous request. Note that this behavior only occurs if you include a request_id as part of your create cache request. If a request_id isn't included, you get an ANYWHERE_CACHE_ALREADY_EXISTS error when attempting to create a cache that already exists. For information about how to include a request_id, see Request duplication.

What's next

Get recommendations about which buckets and zones to create a cache for.