Create and manage Anywhere Cache caches

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

For information on how to use and manage long-running operations that getinitiated from Anywhere Cacheasynchronous cache operations, seeUse long-running operations.

Before using Anywhere Cache, review theLimitations 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 theStorage 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 theRequired 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 withcustom roles.

For information about granting roles on buckets, seeSet and manage IAM policies on buckets.

In order to managelong-running operations that get initiated fromAnywhere Cache methods, you might need additional roles and permissions.Seerequired roles for long-running operations to learn more.

Create a cache

Console

To create a cache on an existing bucket:

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

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

  3. On theBucket details page, click theConfiguration tab.

  4. In theAnywhere Cache section, clickConfigure cache.

    TheConfigure cache page appears for your bucket.

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

  6. In theCache zones section, select the zones in which you want tocreate a cache. For each zone you select, specify aTime to live andanIngest on second access option for the cache.

  7. ClickSave configuration.

  8. In the dialog that appears, clickConfirm.

    TheOperations tab in theBucket details page opens, which showsyou the job status of yourcreate cache operation.

To create a cache as part of creating a new bucket, follow the instructionsinCreate a new bucket.

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

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. Click theView Column icon (),selectCache, then clickOK.

Command line

Use thegcloud storage buckets anywhere-caches create command:

gcloud storage buckets anywhere-caches create gs://BUCKET_NAMEZONE

Replace:

  • BUCKET_NAME with the name of the bucket forwhich you want to cache data. For example,my-bucket.

  • ZONE with the zone in which thecache will run. For example,us-east1-b.

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

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

  • --ttl: Specify the time to live (TTL) of the data in the cache,in seconds. 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 to86400s (1 day).

  • --admission-policy: Specify at what point data gets ingested intothe cache. Acceptable values areADMIT_ON_FIRST_MISS andADMIT_ON_SECOND_MISS. If unspecified, defaults toADMIT_ON_FIRST_MISS.

If successful, the command returns the ID of the long-running operationassociated with the AnywhereCache Create operation. Youcanget details about the long-running operation orcancelthe long-running operation to stop the AnywhereCaches Create operationbefore it completes.

Client libraries

C++

For more information, see theCloud StorageC++ API reference documentation.

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

namespacestoragecontrol=google::cloud::storagecontrol_v2;[](storagecontrol::StorageControlClientclient,std::stringconst&bucket_name,std::stringconst&cache_name,std::stringconst&zone_name){google::storage::control::v2::AnywhereCachecache;cache.set_name(cache_name);cache.set_zone(zone_name);google::storage::control::v2::CreateAnywhereCacheRequestrequest;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.autoanywhere_cache=client.CreateAnywhereCache(request).get();if(!anywhere_cache)throwstd::move(anywhere_cache).status();std::cout <<"Created anywhere cache: " <<anywhere_cache->name() <<"\n";}

Java

For more information, see theCloud StorageJava API reference documentation.

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

importcom.google.api.gax.longrunning.OperationFuture;importcom.google.storage.control.v2.AnywhereCache;importcom.google.storage.control.v2.BucketName;importcom.google.storage.control.v2.CreateAnywhereCacheMetadata;importcom.google.storage.control.v2.CreateAnywhereCacheRequest;importcom.google.storage.control.v2.StorageControlClient;importjava.io.IOException;importjava.util.concurrent.ExecutionException;publicfinalclassAnywhereCacheCreate{publicstaticvoidanywhereCacheCreate(StringbucketName,StringcacheName,StringzoneName)throwsInterruptedException,ExecutionException,IOException{try(StorageControlClientstorageControl=StorageControlClient.create()){CreateAnywhereCacheRequestrequest=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.AnywhereCacheanywhereCache=operation.get();System.out.printf("Created anywhere cache: %s%n",anywhereCache.getName());}}}

Terraform

See thegoogle_storage_anywhere_cache Terraform documentation fordetails on how to use Anywhere Cache with Terraform.

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

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

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

    Replace:

    • ZONE with the zone in whichthe cache will run. For example,us-east1-b.

    • TIME_TO_LIVE with the time to live (TTL) ofthe data in the cache. The value can be between 1 hourto 7 days, specified in seconds. If unspecified, defaults to86400s (1 day).

    • ADMISSION_POLICY with the admission policyof the cache, which specifies when data gets ingested. Values canbeadmit-on-first-miss oradmit-on-second-miss. If unspecified, defaults toadmit-on-first-miss.

  3. UsecURL to call theJSON API with arequest 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 JSONfile you created in Step 2.

    • BUCKET_NAME with the name of the bucketfor which you want to cache data. For example,my-bucket.

If successful, the operation returns agoogle.longrunning.Operation.You canget details about the long-running operation orcancel the long-running operation to stop the AnywhereCachesCreate operation before it completes.

View a cache

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

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

  3. On theBucket details page, click theConfiguration tab.

  4. In theAnywhere Cache section, clickEdit next to theCachefield.

  5. In theEdit configuration page that appears, select a region toview all the caches within the region's zones.

    In theCache zones pane, you can then view details about eachavailable cache.

Command line

Use thegcloud storage buckets anywhere-caches describe command:

gcloud storage buckets anywhere-caches describeID

Replace:

  • ID with the identifier of the cacheinstance, formulated asBUCKET_NAME/ANYWHERE_CACHE_ID. Forexample,my-bucket/us-east1-b.

Use the optionalraw flag to output a raw API response instead ofa standardized API response.

If successful, the command returns anAnywhereCache resource.

Client libraries

C++

For more information, see theCloud StorageC++ API reference documentation.

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

namespacestoragecontrol=google::cloud::storagecontrol_v2;[](storagecontrol::StorageControlClientclient,std::stringconst&cache_name){autoanywhere_cache=client.GetAnywhereCache(cache_name);if(!anywhere_cache)throwstd::move(anywhere_cache).status();std::cout <<"Got anywhere cache: " <<anywhere_cache->name() <<"\n";}

Java

For more information, see theCloud StorageJava API reference documentation.

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

importcom.google.storage.control.v2.AnywhereCache;importcom.google.storage.control.v2.GetAnywhereCacheRequest;importcom.google.storage.control.v2.StorageControlClient;importjava.io.IOException;publicfinalclassAnywhereCacheGet{publicstaticvoidanywhereCacheGet(StringcacheName)throwsIOException{try(StorageControlClientstorageControl=StorageControlClient.create()){GetAnywhereCacheRequestrequest=GetAnywhereCacheRequest.newBuilder().setName(cacheName).build();AnywhereCacheanywhereCache=storageControl.getAnywhereCache(request);System.out.printf("Got anywhere cache: %s%n",anywhereCache.getName());}}}

Terraform

See thegoogle_storage_anywhere_cache Terraform documentation fordetails on how to use Anywhere Cache with Terraform.

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call theJSON API with arequest 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 bucketassociated with the cache you want to retrieve. For example,my-bucket.

    • ANYWHERE_CACHE_ID with the zone in whichthe cache is located. For example,us-east1-b.

If successful, this operation returns anAnywhereCache resource.

List caches

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

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

  3. On theBucket details page, click theConfiguration tab.

  4. In theAnywhere Cache section, clickEdit next to theCachefield.

  5. In theEdit configuration page that appears, select a region toview all the caches within that region's zones.

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

Command line

Use thegcloud storage buckets anywhere-caches list command:

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

Replace:

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

If successful, the command returns a list ofAnywhereCache resources.

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

Client libraries

C++

For more information, see theCloud StorageC++ API reference documentation.

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

namespacestoragecontrol=google::cloud::storagecontrol_v2;[](storagecontrol::StorageControlClientclient,std::stringconst&bucket_name){autoconstparent=std::string{"projects/_/buckets/"}+bucket_name;for(autoanywhere_cache:client.ListAnywhereCaches(parent)){if(!anywhere_cache)throwstd::move(anywhere_cache).status();std::cout <<anywhere_cache->name() <<"\n";}}

Java

For more information, see theCloud StorageJava API reference documentation.

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

importcom.google.storage.control.v2.AnywhereCache;importcom.google.storage.control.v2.BucketName;importcom.google.storage.control.v2.ListAnywhereCachesRequest;importcom.google.storage.control.v2.StorageControlClient;importcom.google.storage.control.v2.StorageControlClient.ListAnywhereCachesPagedResponse;importjava.io.IOException;publicfinalclassAnywhereCacheList{publicstaticvoidanywhereCacheList(StringbucketName)throwsIOException{try(StorageControlClientstorageControl=StorageControlClient.create()){ListAnywhereCachesRequestrequest=ListAnywhereCachesRequest.newBuilder().setParent(BucketName.format("_",bucketName)).build();ListAnywhereCachesPagedResponsepage=storageControl.listAnywhereCaches(request);for(AnywhereCacheanywhereCache:page.iterateAll()){System.out.println(anywhereCache.getName());}}}}

Terraform

See thegoogle_storage_anywhere_cache Terraform documentation fordetails on how to use Anywhere Cache with Terraform.

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call theJSON API with arequest 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 bucketassociated with the caches you want to retrieve. For example,my-bucket.

    When listing multiple caches, you canpaginate results.

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

Update a cache

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

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

  3. On theBucket details page, click theConfiguration tab.

  4. In theAnywhere Cache section, clickManage Anywhere Caches.

  5. In theManage caches pane, clickEdit or create caches

  6. In theEdit configuration page that appears, update the propertiesof the cache, then clickSave.

  7. In the dialog that appears, clickConfirm.

Command line

Use thegcloud storage buckets anywhere-caches update command:

gcloud storage buckets anywhere-caches updateID

Replace:

  • ID with the identifier of the cacheinstance, formulated asBUCKET_NAME/ANYWHERE_CACHE_ID. Forexample,my-bucket/us-east1-b.

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

Use the following flags to update the configuration of the cache. If aflag 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 intothe cache. Values can beADMIT_ON_FIRST_MISS orADMIT_ON_SECOND_MISS.

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

Client libraries

C++

For more information, see theCloud StorageC++ API reference documentation.

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

namespacestoragecontrol=google::cloud::storagecontrol_v2;[](storagecontrol::StorageControlClientclient,std::stringconst&cache_name,std::stringconst&admission_policy){google::storage::control::v2::AnywhereCachecache;google::protobuf::FieldMaskfield_mask;field_mask.add_paths("admission_policy");cache.set_name(cache_name);cache.set_admission_policy(admission_policy);// 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.autoanywhere_cache=client.UpdateAnywhereCache(cache,field_mask).get();if(!anywhere_cache)throwstd::move(anywhere_cache).status();std::cout <<"Updated anywhere cache: " <<anywhere_cache->name() <<"\n";}

Java

For more information, see theCloud StorageJava API reference documentation.

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

importcom.google.api.gax.longrunning.OperationFuture;importcom.google.protobuf.FieldMask;importcom.google.storage.control.v2.AnywhereCache;importcom.google.storage.control.v2.StorageControlClient;importcom.google.storage.control.v2.UpdateAnywhereCacheMetadata;importcom.google.storage.control.v2.UpdateAnywhereCacheRequest;importjava.io.IOException;importjava.util.concurrent.ExecutionException;publicfinalclassAnywhereCacheUpdate{publicstaticvoidanywhereCacheUpdate(StringcacheName,StringadmissionPolicy)throwsInterruptedException,ExecutionException,IOException{try(StorageControlClientstorageControl=StorageControlClient.create()){AnywhereCachependingUpdate=AnywhereCache.newBuilder().setName(cacheName).setAdmissionPolicy(admissionPolicy).build();UpdateAnywhereCacheRequestrequest=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.AnywhereCacheupdatedAnywhereCache=operation.get();System.out.printf("Updated anywhere cache: %s%n",updatedAnywhereCache.getName());}}}

Terraform

See thegoogle_storage_anywhere_cache Terraform documentation fordetails on how to use Anywhere Cache with Terraform.

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

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

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

    Replace:

    • TIME_TO_LIVE with the TTL of the data inthe cache. The value can be between 1 hour to 7 days, specified inseconds. If unspecified, the current value remains used.

    • ADMISSION_POLICY with the admission policyof the cache, which specifies when data gets ingested. Values canbeadmit-on-first-miss oradmit-on-second-miss. If unspecified, the currentvalue remains used.

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

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

  3. To apply the new properties, usecURL to call theJSON API with arequest 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 JSONfile you created in Step 2.

    • BUCKET_NAME with the name of the bucketassociated with the cache you want to update. For example,my-bucket.

    • ANYWHERE_CACHE_ID with the identifier ofthe cache. For example,us-east1-b.

If successful, the operation returns agoogle.longrunning.Operation.You canget details about the long-running operation.

Pause a cache

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

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

  3. On theBucket details page, click theConfiguration tab.

  4. In theAnywhere Cache section, clickManage Anywhere Caches.

  5. In theManage caches pane, click thePause cache icon().

  6. ClickClose.

Command line

Use thegcloud storage buckets anywhere-caches pause command:

gcloud storage buckets anywhere-caches pauseID

Replace:

  • ID with the identifier of the cacheinstance, formulated asBUCKET_NAME/ANYWHERE_CACHE_ID. Forexample,my-bucket/us-east1-b.

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

If successful, the command returns a success message.

Client libraries

C++

For more information, see theCloud StorageC++ API reference documentation.

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

namespacestoragecontrol=google::cloud::storagecontrol_v2;[](storagecontrol::StorageControlClientclient,std::stringconst&cache_name){autoanywhere_cache=client.PauseAnywhereCache(cache_name);if(!anywhere_cache)throwstd::move(anywhere_cache).status();std::cout <<"Paused anywhere cache: " <<anywhere_cache->name() <<"\n";}

Java

For more information, see theCloud StorageJava API reference documentation.

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

importcom.google.storage.control.v2.AnywhereCache;importcom.google.storage.control.v2.PauseAnywhereCacheRequest;importcom.google.storage.control.v2.StorageControlClient;importjava.io.IOException;publicfinalclassAnywhereCachePause{publicstaticvoidanywhereCachePause(StringcacheName)throwsIOException{try(StorageControlClientstorageControl=StorageControlClient.create()){PauseAnywhereCacheRequestrequest=PauseAnywhereCacheRequest.newBuilder().setName(cacheName).build();AnywhereCacheanywhereCache=storageControl.pauseAnywhereCache(request);System.out.printf("Paused anywhere cache: %s%n",anywhereCache.getName());}}}

Terraform

See thegoogle_storage_anywhere_cache Terraform documentation fordetails on how to use Anywhere Cache with Terraform.

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call theJSON API with arequest 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 bucketassociated with the cache you want to pause. For example,my-bucket.

    • ANYWHERE_CACHE_ID with the identifier ofthe cache. For example,us-east1-b.

If successful, the operation returns a formattedAnywhereCache resource.

Resume a cache

Console

To resume a cache that's been paused or disabled, complete the followinginstructions:

  1. In the Google Cloud console, go to the Cloud StorageBuckets 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 theBucket details page, click theConfiguration tab.

  4. In theAnywhere Cache section, clickManage Anywhere Caches.

  5. In theManage caches pane, click theResume cache icon ().

  6. ClickClose.

Command line

Use thegcloud storage buckets anywhere-caches resume command:

gcloud storage buckets anywhere-caches resumeID

Replace:

  • ID with the identifier of the cacheinstance, formulated asBUCKET_NAME/ANYWHERE_CACHE_ID. Forexample,my-bucket/us-east1-b.

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

If successful, the command returns a formattedAnywhereCache resource.

Client libraries

C++

For more information, see theCloud StorageC++ API reference documentation.

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

namespacestoragecontrol=google::cloud::storagecontrol_v2;[](storagecontrol::StorageControlClientclient,std::stringconst&cache_name){autoanywhere_cache=client.ResumeAnywhereCache(cache_name);if(!anywhere_cache)throwstd::move(anywhere_cache).status();std::cout <<"Resumed anywhere cache: " <<anywhere_cache->name() <<"\n";}

Java

For more information, see theCloud StorageJava API reference documentation.

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

importcom.google.storage.control.v2.AnywhereCache;importcom.google.storage.control.v2.ResumeAnywhereCacheRequest;importcom.google.storage.control.v2.StorageControlClient;importjava.io.IOException;publicfinalclassAnywhereCacheResume{publicstaticvoidanywhereCacheResume(StringcacheName)throwsIOException{try(StorageControlClientstorageControl=StorageControlClient.create()){ResumeAnywhereCacheRequestrequest=ResumeAnywhereCacheRequest.newBuilder().setName(cacheName).build();AnywhereCacheanywhereCache=storageControl.resumeAnywhereCache(request);System.out.printf("Resumed anywhere cache: %s%n",anywhereCache.getName());}}}

Terraform

See thegoogle_storage_anywhere_cache Terraform documentation fordetails on how to use Anywhere Cache with Terraform.

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call theJSON API with arequest 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 bucketassociated with the cache you want to resume. For example,my-bucket.

    • ANYWHERE_CACHE_ID with the identifier ofthe cache. For example,us-east1-b.

If successful, the operation returns a formattedAnywhereCache resource.

Disable a cache

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

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

  3. On theBucket details page, click theConfiguration tab.

  4. In theAnywhere Cache section, clickManage Anywhere Caches.

  5. In theManage caches pane, click theDisable cache icon().

  6. In the dialog that appears, clickConfirm.

  7. ClickClose.

Command line

Use thegcloud storage buckets anywhere-caches disable command:

gcloud storage buckets anywhere-caches disableID

Replace:

  • ID with the identifier of the cacheinstance, formulated asBUCKET_NAME/ANYWHERE_CACHE_ID. Forexample,my-bucket/us-east1-b.

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

If successful, the command returns a formattedAnywhereCache resource.

Client libraries

C++

For more information, see theCloud StorageC++ API reference documentation.

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

namespacestoragecontrol=google::cloud::storagecontrol_v2;[](storagecontrol::StorageControlClientclient,std::stringconst&cache_name){autoanywhere_cache=client.DisableAnywhereCache(cache_name);if(!anywhere_cache)throwstd::move(anywhere_cache).status();std::cout <<"Disabled anywhere cache: " <<anywhere_cache->name() <<"\n";}

Java

For more information, see theCloud StorageJava API reference documentation.

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

importcom.google.storage.control.v2.AnywhereCache;importcom.google.storage.control.v2.DisableAnywhereCacheRequest;importcom.google.storage.control.v2.StorageControlClient;importjava.io.IOException;publicfinalclassAnywhereCacheDisable{publicstaticvoidanywhereCacheDisable(StringcacheName)throwsIOException{try(StorageControlClientstorageControl=StorageControlClient.create()){DisableAnywhereCacheRequestrequest=DisableAnywhereCacheRequest.newBuilder().setName(cacheName).build();AnywhereCacheanywhereCache=storageControl.disableAnywhereCache(request);System.out.printf("Disabled anywhere cache: %s%n",anywhereCache.getName());}}}

Terraform

See thegoogle_storage_anywhere_cache Terraform documentation fordetails on how to use Anywhere Cache with Terraform.

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call theJSON API with arequest 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 bucketassociated with the cache you want to disable. For example,my-bucket.

    • ANYWHERE_CACHE_ID with the identifier ofthe cache. For example,us-east1-b.

If successful, the command returns a formattedAnywhereCache resource.

Monitor cache performance

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

Available charts

ChartResource hierarchy levelDescription
Byte eviction rateBucketThe 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 rateProjectThe 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 cacheBucketThe 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 cacheProjectThe 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 benefitProjectThe 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 operationsBucketThe 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 operationsProjectThe 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 bytesBucketThe percentage of bytes that are served from the cache relative to the total cache eligible bytes, sampled every 60 seconds.
Hit rate bytesProjectThe 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 bytesBucketThe 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 bytesProjectThe 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 hitBucketThe throughput served from the cache, sampled every 60 seconds.
Throughput - Cache hitProjectThe throughput served from all caches for a bucket, sampled every 60 seconds.
Throughput - Cache missBucketThe throughput that's not served from the cache, sampled every 60 seconds.
Throughput - Cache missProjectThe 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 bucketswithin a project. The resource hierarchy level that a chart captures determineswhere you can access the chart.

Access bucket-level charts

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

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

  3. In theBucket details page, click theObservability tab.

  4. In the navigation menu, selectAnywhere Cache.

    Monitoring charts are displayed.

Access project-level charts

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. In theCloud Storage navigation pane, clickMonitoring.

  3. In the menu bar, clickAnywhere Cache.

    Monitoring charts are displayed.

Use long-running operations

When successfully run, theAnywhereCaches Create andUpdate operationsinitiate along-running operation. You can get and list long-runningoperations in order to view the details and status of the underlyingAnywhereCaches operation, or cancel a long-running operation in order tocancel the underlying AnywhereCaches operation while it's in progress.

Note: You can only cancel long-running operations that get initiated fromAnywhereCaches Create operations. AnywhereCaches Update operationsinitiate long-running operations that can be viewed and listed, but cannot becancelled.

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

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

done:falsekind:storage#operationmetadata:'@type':type.googleapis.com/google.storage.control.v2.CreateAnywhereCacheMetadataanywhereCacheId:us-central1-czone:us-central1-cttl:172800sadmissionPolicy:admit-on-first-misscommonMetadata:createTime:'2023-12-14T20:52:00.032Z'progressPercent:-1requestedCancellation:falsetype:create-anywhere-cacheupdateTime:'2023-12-14T20:52:00.032Z'name:projects/_/buckets/my-bucket/operations/AULf_KhQxxsWRSn56wv4jfmn3pOu_dKTz9FoYx6S0EzMw5ssR0cXIiorCvHRwqxZnQmWj9jnGpKb3Y6iCD3XM9KLc8EHBm7uigselfLink:https://www.googleapis.com/storage/v1/b/my-bucket/operations/AULf_KhQxxsWRSn56wv4jfmn3pOu_dKTz9FoYx6S0EzMw5ssR0cXIiorCvHRwqxZnQmWj9jnGpKb3Y6iCD3XM9KLc8EHBm7uig

Retries

Asynchronous AnywhereCaches APIs areidempotent by default. This meansthat you can safely retry asynchronous AnywhereCaches API calls without concernabout modifying resources unintentionally.

For example, say you perform an AnywhereCaches Create operation to create acache inus-central1-a, which succeeds. If you perform a subsequentAnywhereCaches Create operation using the same zone that succeeds, the requestreturns the same long-running operation as the previous request. Note that thisbehavior only occurs if you include arequest_id as part ofyour create cache request. If arequest_id isn't included, you get anANYWHERE_CACHE_ALREADY_EXISTS error when attempting to create a cache thatalready exists. For information about how to include arequest_id, seeRequest identification.

What's next

Getrecommendations about which buckets and zones to create a cache for.

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

Last updated 2026-02-19 UTC.