Console
    Contact Us Start free

    Create and manage Anywhere Cache caches

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

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

    Before using Anywhere Cache, review the Limitations and restrictions .

    Before you begin

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

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

    Required permissions

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

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

    You can also get these permissions with custom roles .

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

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

    Create a cache

    Console

    To create a cache on 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 detailspage, click the Configurationtab.

    4. In the Anywhere Cachesection, click Configure cache.

      The Configure cachepage appears for your bucket.

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

    6. In the Cache zonessection, select the zones in which you want to create a cache. For each zone you select, specify a Time to liveand an Ingest on second accessoption for the cache.

    7. Click Save configuration.

    8. In the dialogue that appears, click Confirm.

      The Operationstab in the Bucket detailspage 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 listpage:

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

      Go to Buckets

    2. Click the View Columnicon ( ), select Cache, then click OK.

    Command line

    Use the gcloud storage buckets anywhere-caches create command:

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

    Replace:

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

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

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

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

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

    • --admission-policy : Specify at what point data gets ingested into the cache. Acceptable values are ADMIT_ON_FIRST_MISS and ADMIT_ON_SECOND_MISS . If unspecified, defaults to ADMIT_ON_FIRST_MISS .

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

    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 
 
 ()); 
  
 } 
  
 } 
 }

    Terraform

    See the google_storage_anywhere_cache Terraform documentation for details on how to use Anywhere 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 
",
   "admissionPolicy": " ADMISSION_POLICY 
"
}

      Replace:

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

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

      • ADMISSION_POLICY with the admission policy of the cache, which specifies when data gets ingested. Values can be admit-on-first-miss or admit-on-second-miss . If unspecified, defaults to admit-on-first-miss .

    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 detailspage, click the Configurationtab.

    4. In the Anywhere Cachesection, click Editnext to the Cachefield.

    5. In the Edit configurationpage that appears, select a region to view all the caches within the region's zones.

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

    Command line

    Use the gcloud storage buckets anywhere-caches describe command:

    gcloud storage buckets anywhere-caches describe ID

    Replace:

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

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

    If successful, the command returns an AnywhereCache resource .

    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 
 
 ()); 
  
 } 
  
 } 
 }

    Terraform

    See the google_storage_anywhere_cache Terraform documentation for details on how to use Anywhere 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/ ANYWHERE_CACHE_ID 
"

      Replace:

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

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

    If successful, this operation returns an AnywhereCache resource .

    List caches

    Console

    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 detailspage, click the Configurationtab.

    4. In the Anywhere Cachesection, click Editnext to the Cachefield.

    5. In the Edit configurationpage 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 zonespane.

    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 
 ()); 
  
 } 
  
 } 
  
 } 
 }

    Terraform

    See the google_storage_anywhere_cache Terraform documentation for details on how to use Anywhere 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 detailspage, click the Observabilitytab, then click Anywhere Cachein the navigation menu.

    4. Click Edit configuration.

    5. In the Edit configurationpage that appears, update the properties of the cache, then click Save.

    Command line

    Use the gcloud storage buckets anywhere-caches update command:

    gcloud storage buckets anywhere-caches update ID

    Replace:

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

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

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

    • --ttl : Specify the time to live (TTL) of the data in the cache, in seconds.

    • --admission-policy : Specify at what point data gets ingested into the cache. Values can be ADMIT_ON_FIRST_MISS or ADMIT_ON_SECOND_MISS .

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

    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 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 admission_policy 
 ) 
  
 { 
  
 google 
 :: 
 storage 
 :: 
 control 
 :: 
 v2 
 :: 
 AnywhereCache 
  
 cache 
 ; 
  
 google 
 :: 
 protobuf 
 :: 
 FieldMask 
  
 field_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. 
  
 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 
 
 ()); 
  
 } 
  
 } 
 }

    Terraform

    See the google_storage_anywhere_cache Terraform documentation for details on how to use Anywhere 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 
",
   "admissionPolicy": " ADMISSION_POLICY 
"
}

      Replace:

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

      • ADMISSION_POLICY with the admission policy of the cache, which specifies when data gets ingested. Values can be admit-on-first-miss or admit-on-second-miss . If unspecified, the current value remains used.

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

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

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

      Replace:

      • JSON_FILE_NAME with the name of the JSON file you created in Step 2.

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

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

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

    Pause a cache

    Console

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

    3. On the Bucket detailspage, click the Observabilitytab, then click Anywhere Cachein the navigation menu.

    4. Click Pause/resume caches.

    5. In the pane that appears, click the Pause cacheicon ( ).

    6. Click Close.

    Command line

    Use the gcloud storage buckets anywhere-caches pause command:

    gcloud storage buckets anywhere-caches pause ID

    Replace:

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

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

    If successful, the command returns a success message.

    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 
 . 
 PauseAnywhereCache 
 ( 
 cache_name 
 ); 
  
 if 
  
 ( 
 ! 
 anywhere_cache 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 anywhere_cache 
 ). 
 status 
 (); 
  
 std 
 :: 
 cout 
 << 
 "Paused 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. PauseAnywhereCacheRequest 
 
 ; 
 import 
  
 com.google.storage.control.v2. StorageControlClient 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 public 
  
 final 
  
 class 
 AnywhereCachePause 
  
 { 
  
 public 
  
 static 
  
 void 
  
 anywhereCachePause 
 ( 
 String 
  
 cacheName 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 try 
  
 ( 
  StorageControlClient 
 
  
 storageControl 
  
 = 
  
  StorageControlClient 
 
 . 
 create 
 ()) 
  
 { 
  
  PauseAnywhereCacheRequest 
 
  
 request 
  
 = 
  
  PauseAnywhereCacheRequest 
 
 . 
 newBuilder 
 (). 
 setName 
 ( 
 cacheName 
 ). 
 build 
 (); 
  
  AnywhereCache 
 
  
 anywhereCache 
  
 = 
  
 storageControl 
 . 
 pauseAnywhereCache 
 ( 
 request 
 ); 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Paused anywhere cache: %s%n" 
 , 
  
 anywhereCache 
 . 
  getName 
 
 ()); 
  
 } 
  
 } 
 }

    Terraform

    See the google_storage_anywhere_cache Terraform documentation for details on how to use Anywhere 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 pause a cache :

      curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME 
/anywhereCaches/ ANYWHERE_CACHE_ID 
/pause"

      Replace:

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

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

    If successful, the operation returns a formatted AnywhereCache resource .

    Resume a cache

    Console

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

    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 detailspage, click the Observabilitytab, then click Anywhere Cachein the navigation menu.

    4. Click Pause/resume caches.

    5. In the pane that appears, click the Resume cacheicon ( ).

    6. Click Close.

    To resume a cache that's been 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 detailspage, click the Observabilitytab, then click Anywhere Cachein the navigation menu.

    4. Click Disable/resume caches.

    5. In the pane that appears, click the Resume cacheicon ( ).

    6. Click Close.

    Command line

    Use the gcloud storage buckets anywhere-caches resume command:

    gcloud storage buckets anywhere-caches resume ID

    Replace:

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

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

    If successful, the command returns a formatted AnywhereCache resource .

    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 
 
 ()); 
  
 } 
  
 } 
 }

    Terraform

    See the google_storage_anywhere_cache Terraform documentation for details on how to use Anywhere 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/ ANYWHERE_CACHE_ID 
/resume"

      Replace:

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

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

    If successful, the operation returns a formatted AnywhereCache resource .

    Disable a cache

    Console

    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 detailspage, click the Observabilitytab, then click Anywhere Cachein the navigation menu.

    4. Click Disable/resume caches.

    5. In the pane that appears, click the Disable cacheicon ( ).

    6. In the dialogue that appears, click Confirm.

    7. Click Close.

    Command line

    Use the gcloud storage buckets anywhere-caches disable command:

    gcloud storage buckets anywhere-caches disable ID

    Replace:

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

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

    If successful, the command returns a formatted AnywhereCache resource .

    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 
 
 ()); 
  
 } 
  
 } 
 }

    Terraform

    See the google_storage_anywhere_cache Terraform documentation for details on how to use Anywhere 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/ ANYWHERE_CACHE_ID 
/disable"

      Replace:

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

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

    If successful, the command returns a formatted AnywhereCache resource .

    Monitor cache performance

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

    Available charts

    Chart Resource hierarchy level Description
    Byte eviction rate
    		Bucket The rate of bytes evicted from the cache, sampled every hour. This data is refreshed more than once an hour to allow time for post processing the data.
    Byte eviction rate
    		Project The rate of bytes evicted from all the caches of a bucket, sampled every hour. This data is refreshed more than once an hour to allow time for post processing the data.
    Bytes in cache
    		Bucket The 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 detailspage, click the Observabilitytab.

    4. In the navigation menu, select Anywhere 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 Storagenavigation pane, click Monitoring.

    3. In the menu bar, click Anywhere Cache.

      Monitoring charts are displayed.

    Use long-running operations

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

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

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

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

    Retries

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

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

    What's next

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

    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: