Create and manage caches with Rapid Cache

You can create and manage cache instances with Rapid Cache to reduce latency and optimize data access for objects stored in Cloud Storage. This caching solution helps improve the performance of your applications by accelerating data retrieval.

This page shows you how to create and manage cache instances with Rapid Cache. For information on how to use and manage long-running operations that get initiated from Rapid Cache asynchronous cache operations, see Use long-running operations.

Before using Rapid Cache, review the Limitations and restrictions.

Before you begin

To get the permissions that you need to create and manage Rapid 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 Rapid 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 Rapid Cache caches:

storage.anywhereCaches.create (required for creating caches)
storage.anywhereCaches.disable (required for disabling caches)
storage.anywhereCaches.get (required for getting caches)
storage.anywhereCaches.list (required for listing 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 Set and manage IAM policies on buckets.

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

Create a cache

Console

To create a cache on an existing bucket:

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 Configure cache 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, set a Time to Live (TTL) and a data ingestion criteria.
- To set a TTL: in the Time to live column, enter a duration in the Duration* field and select a time unit.
- To set the data ingestion criteria: in the Ingestion criteria column, click Edit. In the Set ingestion criteria panel that appears, select a data ingestion option and click Done.
Click Save.
In the dialog that appears, click Confirm.

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

To create a cache as part of creating a new bucket, follow the instructions in Create a new bucket.

To view the status of a bucket's cache from the Buckets list page:

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 CACHE_ZONE \
[--ttl=TTL] [--enable-ingest-on-write]

Replace:

BUCKET_NAME with the name of the bucket for which you want to cache data. For example, my-bucket.
CACHE_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.
TTL (optional) with the time to live (TTL) of the data in the cache. The value can be between 1 day and 7 days, inclusive. The value can be expressed in seconds, minutes, hours, and days. For example:
- 86400s for 86,400 seconds
- 1440m for 1,440 minutes
- 24h for 24 hours
- 1d for 1 day
If unspecified, defaults to 86400s (1 day).

To configure the cache to ingest data the moment the data is written to the bucket, specify the --enable-ingest-on-write flag.

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.

Client libraries

C++

For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& bucket_name, std::string const& cache_name,
   std::string const& zone_name) {
  google::storage::control::v2::AnywhereCache cache;
  cache.set_name(cache_name);
  cache.set_zone(zone_name);

  google::storage::control::v2::CreateAnywhereCacheRequest request;
  request.set_parent(std::string{"projects/_/buckets/"} + bucket_name);
  *request.mutable_anywhere_cache() = cache;

  // Start a create operation and block until it completes. Real applications
  // may want to setup a callback, wait on a coroutine, or poll until it
  // completes.
  auto anywhere_cache = client.CreateAnywhereCache(request).get();
  if (!anywhere_cache) throw std::move(anywhere_cache).status();
  std::cout << "Created anywhere cache: " << anywhere_cache->name() << "\n";
}

Java

For more information, see the Cloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

import com.google.api.gax.longrunning.OperationFuture;
import com.google.storage.control.v2.AnywhereCache;
import com.google.storage.control.v2.BucketName;
import com.google.storage.control.v2.CreateAnywhereCacheMetadata;
import com.google.storage.control.v2.CreateAnywhereCacheRequest;
import com.google.storage.control.v2.StorageControlClient;
import java.io.IOException;
import java.util.concurrent.ExecutionException;

public final class AnywhereCacheCreate {

  public static void anywhereCacheCreate(String bucketName, String cacheName, String zoneName)
      throws InterruptedException, ExecutionException, IOException {
    try (StorageControlClient storageControl = StorageControlClient.create()) {

      CreateAnywhereCacheRequest request =
          CreateAnywhereCacheRequest.newBuilder()
              // Set project to "_" to signify globally scoped bucket
              .setParent(BucketName.format("_", bucketName))
              .setAnywhereCache(
                  AnywhereCache.newBuilder().setName(cacheName).setZone(zoneName).build())
              .build();

      // Start a long-running operation (LRO).
      OperationFuture<AnywhereCache, CreateAnywhereCacheMetadata> operation =
          storageControl.createAnywhereCacheAsync(request);

      // Await the LROs completion.
      AnywhereCache anywhereCache = operation.get();
      System.out.printf("Created anywhere cache: %s%n", anywhereCache.getName());
    }
  }
}

Rust

use google_cloud_lro::Poller;
use google_cloud_storage::client::StorageControl;
use google_cloud_storage::model::AnywhereCache;

pub async fn sample(client: &StorageControl, bucket_id: &str, zone: &str) -> anyhow::Result<()> {
    let cache = client
        .create_anywhere_cache()
        .set_parent(format!("projects/_/buckets/{bucket_id}"))
        .set_anywhere_cache(AnywhereCache::new().set_zone(zone).set_name(format!(
            "projects/_/buckets/{bucket_id}/anywhereCaches/{zone}"
        )))
        .poller()
        .until_done()
        .await?;
    println!("Created anywhere cache: {cache:?}");
    Ok(())
}

Terraform

See the google_storage_anywhere_cache Terraform documentation for details on how to use Rapid Cache with Terraform.

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",
   "ingestOnWrite": INGEST_SETTING
}

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. Values can be expressed in seconds, minutes, hours, and days. For example:
- 86400s for 86,400 seconds
- 1440m for 1,440 minutes
- 24h for 24 hours
- 1d for 1 day
If unspecified, defaults to 86400s (1 day). The maximum value is 7 days.
INGEST_SETTING with true or false to specify whether or not the cache will ingest data on write.

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 Rapid 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 CACHE_ID

Replace:

CACHE_ID with the identifier of the cache instance, formulated as BUCKET_NAME/CACHE_ZONE. 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.

Client libraries

C++

For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& cache_name) {
  auto anywhere_cache = client.GetAnywhereCache(cache_name);
  if (!anywhere_cache) throw std::move(anywhere_cache).status();
  std::cout << "Got anywhere cache: " << anywhere_cache->name() << "\n";
}

Java

For more information, see the Cloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.


import com.google.storage.control.v2.AnywhereCache;
import com.google.storage.control.v2.GetAnywhereCacheRequest;
import com.google.storage.control.v2.StorageControlClient;
import java.io.IOException;

public final class AnywhereCacheGet {

  public static void anywhereCacheGet(String cacheName) throws IOException {
    try (StorageControlClient storageControl = StorageControlClient.create()) {

      GetAnywhereCacheRequest request =
          GetAnywhereCacheRequest.newBuilder().setName(cacheName).build();

      AnywhereCache anywhereCache = storageControl.getAnywhereCache(request);

      System.out.printf("Got anywhere cache: %s%n", anywhereCache.getName());
    }
  }
}

Rust

use google_cloud_storage::client::StorageControl;

pub async fn sample(
    client: &StorageControl,
    bucket_id: &str,
    cache_id: &str,
) -> anyhow::Result<()> {
    let cache = client
        .get_anywhere_cache()
        .set_name(format!(
            "projects/_/buckets/{bucket_id}/anywhereCaches/{cache_id}"
        ))
        .send()
        .await?;
    println!("Got anywhere cache: {:?}", cache);
    Ok(())
}

Terraform

See the google_storage_anywhere_cache Terraform documentation for details on how to use Rapid Cache with Terraform.

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/RAPID_CACHE_ID"

Replace:

BUCKET_NAME with the name of the bucket associated with the cache you want to retrieve. For example, my-bucket.
RAPID_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 Rapid 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.

Client libraries

C++

For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& bucket_name) {
  auto const parent = std::string{"projects/_/buckets/"} + bucket_name;
  for (auto anywhere_cache : client.ListAnywhereCaches(parent)) {
    if (!anywhere_cache) throw std::move(anywhere_cache).status();
    std::cout << anywhere_cache->name() << "\n";
  }
}

Java

For more information, see the Cloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.


import com.google.storage.control.v2.AnywhereCache;
import com.google.storage.control.v2.BucketName;
import com.google.storage.control.v2.ListAnywhereCachesRequest;
import com.google.storage.control.v2.StorageControlClient;
import com.google.storage.control.v2.StorageControlClient.ListAnywhereCachesPagedResponse;
import java.io.IOException;

public final class AnywhereCacheList {

  public static void anywhereCacheList(String bucketName) throws IOException {
    try (StorageControlClient storageControl = StorageControlClient.create()) {

      ListAnywhereCachesRequest request =
          ListAnywhereCachesRequest.newBuilder()
              .setParent(BucketName.format("_", bucketName))
              .build();

      ListAnywhereCachesPagedResponse page = storageControl.listAnywhereCaches(request);
      for (AnywhereCache anywhereCache : page.iterateAll()) {
        System.out.println(anywhereCache.getName());
      }
    }
  }
}

Rust

use google_cloud_gax::paginator::ItemPaginator;
use google_cloud_storage::client::StorageControl;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    let mut stream = client
        .list_anywhere_caches()
        .set_parent(format!("projects/_/buckets/{}", bucket_id))
        .by_item();
    while let Some(cache) = stream.next().await {
        println!("Found cache: {:?}", cache?);
    }
    Ok(())
}

Terraform

See the google_storage_anywhere_cache Terraform documentation for details on how to use Rapid Cache with Terraform.

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 Configuration tab.
In the Rapid Cache section, click Manage caches.
In the Manage caches pane, click Edit or create caches.
In the Edit configuration page that appears, update the properties of the cache:
- To update the TTL of the cache, locate the Time to live column, then specify a time duration and select a time unit (for example, minutes).
- To enable ingest on write:
  1. Locate the Ingestion criteria column, then click Edit cache ingestion criteria.
  2. In the Set ingestion criteria pane, select the Ingest data on write checkbox, then click Done.
In the Edit configuration page, click Save.
In the dialog that appears, click Confirm.

Command line

Use the gcloud storage buckets anywhere-caches update command:

gcloud storage buckets anywhere-caches update CACHE_ID \
[--ttl=TTL] [--[no-]enable-ingest-on-write]

Replace:

CACHE_ID with the identifier of the cache instance, formulated as BUCKET_NAME/CACHE_ZONE. 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.
TTL (optional) with the time to live (TTL) of the data in the cache. The value can be between 1 day and 7 days, inclusive. The value can be expressed in seconds, minutes, hours, and days. For example:
- 86400s for 86,400 seconds
- 1440m for 1,440 minutes
- 24h for 24 hours
- 1d for 1 day

To configure the cache to ingest data the moment the data is written to the bucket, specify the --enable-ingest-on-write flag. To disable ingesting data on write, specify the --no-enable-ingest-on-write flag.

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.

Client libraries

C++

For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& cache_name) {
  google::storage::control::v2::AnywhereCache cache;
  google::protobuf::FieldMask field_mask;
  field_mask.add_paths("ttl");
  cache.set_name(cache_name);
  cache.mutable_ttl()->set_seconds(86400);
  // Start an update operation and block until it completes. Real applications
  // may want to setup a callback, wait on a coroutine, or poll until it
  // completes.
  auto anywhere_cache = client.UpdateAnywhereCache(cache, field_mask).get();
  if (!anywhere_cache) throw std::move(anywhere_cache).status();
  std::cout << "Updated anywhere cache: " << anywhere_cache->name() << "\n";
}

Java

For more information, see the Cloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.


import com.google.api.gax.longrunning.OperationFuture;
import com.google.protobuf.FieldMask;
import com.google.storage.control.v2.AnywhereCache;
import com.google.storage.control.v2.StorageControlClient;
import com.google.storage.control.v2.UpdateAnywhereCacheMetadata;
import com.google.storage.control.v2.UpdateAnywhereCacheRequest;
import java.io.IOException;
import java.util.concurrent.ExecutionException;

public final class AnywhereCacheUpdate {

  public static void anywhereCacheUpdate(String cacheName, String admissionPolicy)
      throws InterruptedException, ExecutionException, IOException {
    try (StorageControlClient storageControl = StorageControlClient.create()) {

      AnywhereCache pendingUpdate =
          AnywhereCache.newBuilder().setName(cacheName).setAdmissionPolicy(admissionPolicy).build();

      UpdateAnywhereCacheRequest request =
          UpdateAnywhereCacheRequest.newBuilder()
              .setAnywhereCache(pendingUpdate)
              .setUpdateMask(FieldMask.newBuilder().addPaths("admission_policy").build())
              .build();

      // Start a long-running operation (LRO).
      OperationFuture<AnywhereCache, UpdateAnywhereCacheMetadata> operation =
          storageControl.updateAnywhereCacheAsync(request);

      // Await the LROs completion.
      AnywhereCache updatedAnywhereCache = operation.get();
      System.out.printf("Updated anywhere cache: %s%n", updatedAnywhereCache.getName());
    }
  }
}

Rust

use google_cloud_lro::Poller;
use google_cloud_storage::client::StorageControl;
use google_cloud_storage::model::AnywhereCache;
use google_cloud_wkt::FieldMask;

pub async fn sample(
    client: &StorageControl,
    bucket_id: &str,
    cache_id: &str,
) -> anyhow::Result<()> {
    let anywhere_cache = AnywhereCache::new()
        .set_name(format!(
            "projects/_/buckets/{}/anywhereCaches/{}",
            bucket_id, cache_id
        ))
        .set_admission_policy("ADMIT_ON_SECOND_MISS".to_string());
    let operation = client
        .update_anywhere_cache()
        .set_anywhere_cache(anywhere_cache)
        .set_update_mask(FieldMask::default().set_paths(["admission_policy"]))
        .poller()
        .until_done()
        .await?;
    println!("Updated anywhere cache: {:?}", operation);
    Ok(())
}

Terraform

See the google_storage_anywhere_cache Terraform documentation for details on how to use Rapid Cache with Terraform.

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",
   "ingestOnWrite": INGEST_SETTING
}

Replace:

TIME_TO_LIVE with the TTL of the data in the cache. The value can be between 1 day and 7 days, inclusive. The value can be expressed in seconds, minutes, hours, and days. For example:
- 86400s for 86,400 seconds
- 1440m for 1,440 minutes
- 24h for 24 hours
- 1d for 1 day
INGEST_SETTING with true or false to specify whether or not the cache ingests data on write.

The following example updates the cache's TTL to 2 days:

{
   "ttl": "172800s"
}

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/RAPID_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.
RAPID_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.

Resume a cache

Console

To resume a cache that's been paused or 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 Configuration tab.
In the Rapid Cache section, click Manage caches.
In the Manage caches pane, click the Resume cache icon ().
Click Close.

Command line

Use the gcloud storage buckets anywhere-caches resume command:

gcloud storage buckets anywhere-caches resume CACHE_ID

Replace:

CACHE_ID with the identifier of the cache instance, formulated as BUCKET_NAME/CACHE_ZONE. 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.

Client libraries

C++

For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& cache_name) {
  auto anywhere_cache = client.ResumeAnywhereCache(cache_name);
  if (!anywhere_cache) throw std::move(anywhere_cache).status();
  std::cout << "Resumed anywhere cache: " << anywhere_cache->name() << "\n";
}

Java

For more information, see the Cloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.


import com.google.storage.control.v2.AnywhereCache;
import com.google.storage.control.v2.ResumeAnywhereCacheRequest;
import com.google.storage.control.v2.StorageControlClient;
import java.io.IOException;

public final class AnywhereCacheResume {

  public static void anywhereCacheResume(String cacheName) throws IOException {
    try (StorageControlClient storageControl = StorageControlClient.create()) {

      ResumeAnywhereCacheRequest request =
          ResumeAnywhereCacheRequest.newBuilder().setName(cacheName).build();

      AnywhereCache anywhereCache = storageControl.resumeAnywhereCache(request);

      System.out.printf("Resumed anywhere cache: %s%n", anywhereCache.getName());
    }
  }
}

Rust

use google_cloud_storage::client::StorageControl;

pub async fn sample(
    client: &StorageControl,
    bucket_id: &str,
    cache_id: &str,
) -> anyhow::Result<()> {
    let cache = client
        .resume_anywhere_cache()
        .set_name(format!(
            "projects/_/buckets/{}/anywhereCaches/{}",
            bucket_id, cache_id
        ))
        .send()
        .await?;
    println!("Resumed anywhere cache: {:?}", cache);
    Ok(())
}

Terraform

See the google_storage_anywhere_cache Terraform documentation for details on how to use Rapid Cache with Terraform.

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/RAPID_CACHE_ID/resume"

Replace:

BUCKET_NAME with the name of the bucket associated with the cache you want to resume. For example, my-bucket.
RAPID_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 Configuration tab.
In the Rapid Cache section, click Manage caches.
In the Manage caches pane, click the Disable cache icon ().
In the dialog that appears, click Confirm.
Click Close.

Command line

Use the gcloud storage buckets anywhere-caches disable command:

gcloud storage buckets anywhere-caches disable CACHE_ID

Replace:

CACHE_ID with the identifier of the cache instance, formulated as BUCKET_NAME/CACHE_ZONE. 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.

Client libraries

C++

For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& cache_name) {
  auto anywhere_cache = client.DisableAnywhereCache(cache_name);
  if (!anywhere_cache) throw std::move(anywhere_cache).status();
  std::cout << "Disabled anywhere cache: " << anywhere_cache->name() << "\n";
}

Java

For more information, see the Cloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.


import com.google.storage.control.v2.AnywhereCache;
import com.google.storage.control.v2.DisableAnywhereCacheRequest;
import com.google.storage.control.v2.StorageControlClient;
import java.io.IOException;

public final class AnywhereCacheDisable {

  public static void anywhereCacheDisable(String cacheName) throws IOException {
    try (StorageControlClient storageControl = StorageControlClient.create()) {

      DisableAnywhereCacheRequest request =
          DisableAnywhereCacheRequest.newBuilder().setName(cacheName).build();

      AnywhereCache anywhereCache = storageControl.disableAnywhereCache(request);

      System.out.printf("Disabled anywhere cache: %s%n", anywhereCache.getName());
    }
  }
}

Rust

use google_cloud_storage::client::StorageControl;

pub async fn sample(
    client: &StorageControl,
    bucket_id: &str,
    cache_id: &str,
) -> anyhow::Result<()> {
    let cache = client
        .disable_anywhere_cache()
        .set_name(format!(
            "projects/_/buckets/{}/anywhereCaches/{}",
            bucket_id, cache_id
        ))
        .send()
        .await?;
    println!("Disabled anywhere cache: {:?}", cache);
    Ok(())
}

Terraform

See the google_storage_anywhere_cache Terraform documentation for details on how to use Rapid Cache with Terraform.

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/RAPID_CACHE_ID/disable"

Replace:

BUCKET_NAME with the name of the bucket associated with the cache you want to disable. For example, my-bucket.
RAPID_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 number 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	The number 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, dual-region, or multi-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 Rapid 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 Rapid 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 Rapid 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
  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 identification.

What's next

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

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-06-09 UTC.

Create and manage caches with Rapid Cache Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Required permissions

Create a cache

Console

Command line

Client libraries

C++

Java

Rust

Terraform

REST APIs

JSON API

View a cache

Console

Command line

Client libraries

C++

Java

Rust

Terraform

REST APIs

JSON API

List caches

Console

Command line

Client libraries

C++

Java

Rust

Terraform

REST APIs

JSON API

Update a cache

Console

Command line

Client libraries

C++

Java

Rust

Terraform

REST APIs

JSON API

Resume a cache

Console

Command line

Client libraries

C++

Java

Rust

Terraform

REST APIs

JSON API

Disable a cache

Console

Command line

Client libraries

C++

Java

Rust

Terraform

REST APIs

JSON API

Monitor cache performance

Available charts

Access charts

Access bucket-level charts

Access project-level charts

Use long-running operations

Retries

What's next

Create and manage caches with Rapid Cache