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

Before you begin creating and managing caches, complete the following sections.

Get required roles

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)
  • storage.managedFolders.create (only required to enable the ingest-on-write behavior for a cache)
  • storage.managedFolders.update (only required to update the ingest-on-write behavior of a cache)

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.

Understand ingest-on-write settings

When you create or update a cache, you can optionally enable the cache to ingest data the moment the data is written to the bucket. This capability is known as "ingest-on-write". If you plan to enable ingest-on-write by using the JSON API, we recommend that you first understand the behaviors of configured settings used for ingest-on-write.

Create a cache

Console

Create a cache for an existing bucket

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

    Go to Buckets

  2. In the list of buckets, click the name of the bucket for which you want to cache data.

  3. On the Bucket details page, click the Configuration tab.

  4. In the Rapid Cache section, click Configure cache.

    The Configure cache page appears for your bucket.

  5. In the Cache regions section, click the region that contains the zones in which you want to create a cache.

  6. In the Cache zones section, select the zones in which you want to create a cache. For each cache you create in a zone, optionally complete the following steps:

    • Optional: You can set a custom Time to Live (TTL) that determines when data gets evicted from the cache from its last read. By default, a cache's TTL is set to one day.

      To set a custom TTL:

      1. In the Time to live column, specify a duration value (for example: 48) and a unit of time (for example: hours).

      2. Click Save configuration.

    • Optional: You can enable the cache to ingest data on write in addition to ingesting data at first read. By default, caches are configured only to ingest data at first read.

      To enable the cache to ingest data on write:

      1. In the Ingestion criteria column, click Edit cache ingestion criteria edit.

        The Set ingestion criteria page appears.

      2. Select the Ingest data on write checkbox.

        • To enable ingest-on-write for all objects that are newly written to the bucket, click Entire bucket.

        • To enable ingest-on-write only for newly written objects that have a specific prefix in their name, click Selected folders, then enter the object name prefix. The object name prefix is also referred to as the "folder path".

        You can enter multiple object name prefixes by clicking Add add.

        To remove a prefix, click Delete item delete.

      3. Click Done.

  7. Click Save configuration.

  8. 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.

Create a cache for a new bucket

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:

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

    Go to Buckets

  2. 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 optional --enable-ingest-on-write flag. This flag enables the cache to ingest all objects when they're written to the bucket.

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

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

  2. Create a JSON file that contains the following information:

    {
   "zone": "ZONE",
   "ttl": "TIME_TO_LIVE",
   "ingestOnWrite": INGEST_SETTING
}

    Replace:

  3. 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

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

    Go to Buckets

  2. In the list of buckets, click the name of the bucket associated with the cache you want to view.

  3. On the Bucket details page, click the Configuration tab.

  4. In the Rapid Cache section, click Edit next to the Cache field.

  5. 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

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

  2. 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

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

    Go to Buckets

  2. In the list of buckets, click the name of the bucket associated with the caches you want to view.

  3. On the Bucket details page, click the Configuration tab.

  4. In the Rapid Cache section, click Edit next to the Cache field.

  5. 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

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

  2. 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

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

    Go to Buckets

  2. In the list of buckets, click the name of the bucket associated with the cache you want to update.

  3. On the Bucket details page, click the Configuration tab.

  4. In the Rapid Cache section, click Manage caches.

  5. In the Manage caches pane, click Edit or create caches.

  6. 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 configure the ingest-on-write behavior of the cache, including whether all objects written are cached or only selective objects written under a prefix are cached:

      1. Locate the Ingestion criteria column, then click Edit cache ingestion criteria.

      2. In the Set ingestion criteria pane:

      • To enable or disable ingest-on-write, select or clear the Ingest data on write checkbox, then click Done.

      • To update the cache to ingest all objects in the bucket on write, make sure the Ingest data on write checkbox is selected, then select Entire bucket. Then, click Done.

      • To update the cache to ingest only objects that contain a specified prefix in their name, make sure the Ingest data on write checkbox is selected, then select Selected folders.

        • To specify a prefix, enter one or multiple prefixes in the folder path field, then click Done.

        • To remove a prefix, click Delete item next to the prefix.

  7. In the Edit configuration page, click Save.

  8. 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. This flag enables the cache to ingest all objects when they're written to the bucket. To disable the cache from 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

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

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

    {
   "ttl": "TIME_TO_LIVE",
   "ingestOnWrite": INGEST_SETTING
}

    Replace:

    The following example updates the cache's TTL to 2 days and enables ingest-on-write for all objects written to the bucket:

    {
   "ttl": "172800s",
   "ingestOnWrite": true
}

  3. 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:

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

    Go to Buckets

  2. In the list of buckets, click the name of the bucket associated with the cache you want to resume.

  3. On the Bucket details page, click the Configuration tab.

  4. In the Rapid Cache section, click Manage caches.

  5. In the Manage caches pane, click the Resume cache icon ().

  6. 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

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

  2. 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

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

    Go to Buckets

  2. In the list of buckets, click the name of the bucket associated with the cache you want to disable.

  3. On the Bucket details page, click the Configuration tab.

  4. In the Rapid Cache section, click Manage caches.

  5. In the Manage caches pane, click the Disable cache icon ().

  6. In the dialog that appears, click Confirm.

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

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

  2. 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

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

    Go to Buckets

  2. In the list of buckets, click the name of the bucket for which you want to see monitoring charts.

  3. In the Bucket details page, click the Observability tab.

  4. In the navigation menu, select Rapid Cache.

    Monitoring charts are displayed.

Access project-level charts

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

    Go to Buckets

  2. In the Cloud Storage navigation pane, click Monitoring.

  3. 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.