samples(StorageControl): Add samples for anywhereCache (#31536)

Author: shubhangi-google

google-cloud-storage-control/samples/acceptance/helper.rb

@@ -16,6 +16,7 @@
 require "minitest/autorun"
 require "minitest/focus"
 require "minitest/hooks/default"
+require "google/cloud/storage/control"
 
 def random_bucket_name
   t = Time.now.utc.iso8601.gsub ":", "-"
@@ -27,8 +28,11 @@ def random_folder_name prefix: "ruby-storage-control-folder-samples-test-"
   "#{prefix}-#{t}-#{SecureRandom.hex 4}".downcase
 end
 
+def storage_client
+  @storage_client ||= Google::Cloud::Storage.new
+end
+
 def create_bucket_helper bucket_name, uniform_bucket_level_access: nil, hierarchical_namespace: nil
-  storage_client = Google::Cloud::Storage.new
   retry_resource_exhaustion do
     storage_client.create_bucket bucket_name do |b|
       b.uniform_bucket_level_access = uniform_bucket_level_access
@@ -38,7 +42,6 @@ def create_bucket_helper bucket_name, uniform_bucket_level_access: nil, hierarch
 end
 
 def delete_bucket_helper bucket_name
-  storage_client = Google::Cloud::Storage.new
   retry_resource_exhaustion do
     bucket = storage_client.bucket bucket_name
     return unless bucket
@@ -60,3 +63,36 @@ def retry_resource_exhaustion
   end
   raise Google::Cloud::ResourceExhaustedError, "Maybe take a break from creating and deleting buckets for a bit"
 end
+
+# Waits until all Anywhere Caches for a given bucket are deleted.
+#
+# This method polls the Storage Control API, listing the Anywhere Caches
+# associated with the specified bucket. If caches are found, it waits and
+# retries with an exponential backoff strategy until no caches remain.
+#
+# @param bucket_name [String] The name of the Google Cloud Storage bucket.
+# @return [Integer] The final count of Anywhere Caches, which will be 0
+# the method completes successfully after all caches are deleted.
+def count_anywhere_caches bucket_name
+  storage_control_client = Google::Cloud::Storage::Control.storage_control
+
+  # Set project to "_" to signify global bucket
+  parent = "projects/_/buckets/#{bucket_name}"
+  request = Google::Cloud::Storage::Control::V2::ListAnywhereCachesRequest.new(
+    parent: parent
+  )
+  result = storage_control_client.list_anywhere_caches request
+  min_delay = 30 # 30 seconds
+  max_delay = 900 # 15 minutes
+  start_time = Time.now
+  while result.response.anywhere_caches.count != 0
+    puts "Cache not deleted yet, Retrying in #{min_delay} seconds."
+    sleep min_delay
+    min_delay = [min_delay * 2, max_delay].min # Exponential backoff with a max delay
+    result = storage_control_client.list_anywhere_caches request
+  end
+  end_time = Time.now
+  duration = end_time - start_time
+  puts "Total waiting time : #{duration.round 2} seconds."
+  result.response.anywhere_caches.count
+end

google-cloud-storage-control/samples/acceptance/storage_control_anywhere_cache_test.rb

@@ -0,0 +1,75 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative "helper"
+require_relative "../storage_control_create_anywhere_cache"
+require_relative "../storage_control_list_anywhere_caches"
+require_relative "../storage_control_get_anywhere_cache"
+require_relative "../storage_control_update_anywhere_cache"
+require_relative "../storage_control_pause_anywhere_cache"
+require_relative "../storage_control_resume_anywhere_cache"
+require_relative "../storage_control_disable_anywhere_cache"
+
+describe "Storage Control Anywhere Cache" do
+  let(:bucket_name) { random_bucket_name }
+  let(:zone) { "us-east1-b" }
+  # Set project to "_" to signify global bucket
+  let(:anywhere_cache_name) { "projects/_/buckets/#{bucket_name}/anywhereCaches/#{zone}" }
+
+  before :all do
+    create_bucket_helper bucket_name
+  end
+
+  after :all do
+    count_anywhere_caches bucket_name # Ensure all caches are deleted before deleting bucket
+    delete_bucket_helper bucket_name
+  end
+
+  it "handles Anywhere cache lifecycle in sequence" do
+    out_create, _err = capture_io do
+      create_anywhere_cache bucket_name: bucket_name, zone: zone
+    end
+    assert_includes out_create, "Successfully created anywhereCache - #{anywhere_cache_name}."
+
+    out_list, _err = capture_io do
+      list_anywhere_caches bucket_name: bucket_name
+    end
+    assert_includes out_list, "AnywhereCache #{anywhere_cache_name} found in list."
+
+    out_get, _err = capture_io do
+      get_anywhere_cache bucket_name: bucket_name, anywhere_cache_id: zone
+    end
+    assert_includes out_get, "Successfully fetched anywhereCache - #{anywhere_cache_name}."
+
+    out_update, _err = capture_io do
+      update_anywhere_cache bucket_name: bucket_name, anywhere_cache_id: zone
+    end
+    assert_includes out_update, "Successfully updated anywhereCache - #{anywhere_cache_name}."
+
+    out_pause, _err = capture_io do
+      pause_anywhere_cache bucket_name: bucket_name, anywhere_cache_id: zone
+    end
+    assert_includes out_pause, "Successfully paused anywhereCache - #{anywhere_cache_name}."
+
+    out_resume, _err = capture_io do
+      resume_anywhere_cache bucket_name: bucket_name, anywhere_cache_id: zone
+    end
+    assert_includes out_resume, "Successfully resumed anywhereCache - #{anywhere_cache_name}."
+
+    out_disable, _err = capture_io do
+      disable_anywhere_cache bucket_name: bucket_name, anywhere_cache_id: zone
+    end
+    assert_includes out_disable, "Successfully disabled anywhereCache - #{anywhere_cache_name}."
+  end
+end

google-cloud-storage-control/samples/storage_control_create_anywhere_cache.rb

@@ -0,0 +1,79 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# [START storage_control_create_anywhere_cache]
+require "google/cloud/storage/control"
+
+# Creates a new Anywhere Cache for a specified bucket and waits for it
+# to become active.
+#
+# This method initiates the creation of an Anywhere Cache in the given zone for
+# the specified bucket. After sending the creation request, it polls the status
+# of the cache with an exponential backoff strategy until the cache's state is
+# "running". Progress and final status are printed to the console.
+#
+# @param bucket_name [String] The name of the bucket.
+# @param zone [String] The zone where the Anywhere Cache instance should be
+#   located (e.g., "us-east1-b").
+#
+# @example
+#   create_anywhere_cache(
+#     bucket_name: "your-unique-bucket-name",
+#     zone: "us-east1-b"
+#   )
+#
+def create_anywhere_cache bucket_name:, zone:
+  # Create a client object. The client can be reused for multiple calls.
+  storage_control_client = Google::Cloud::Storage::Control.storage_control
+  # Set project to "_" to signify global bucket
+  parent = "projects/_/buckets/#{bucket_name}"
+  name = "#{parent}/anywhereCaches/#{zone}"
+
+  anywhere_cache = Google::Cloud::Storage::Control::V2::AnywhereCache.new(
+    name: name,
+    zone: zone
+  )
+  # Create a request.
+  request = Google::Cloud::Storage::Control::V2::CreateAnywhereCacheRequest.new(
+    parent: parent,
+    anywhere_cache: anywhere_cache
+  )
+  # The request creates a new cache in the specified zone.
+  # The cache is created in the specified bucket.
+  begin
+    operation = storage_control_client.create_anywhere_cache request
+    puts "AnywhereCache operation created - #{operation.name}"
+    get_request = Google::Cloud::Storage::Control::V2::GetAnywhereCacheRequest.new(
+      name: name
+    )
+    result = storage_control_client.get_anywhere_cache get_request
+    min_delay = 30 # 30 seconds
+    max_delay = 900 # 15 minutes
+    while result.state&.downcase != "running"
+      unless ["paused", "disabled", "creating"].include? result.state&.downcase
+        raise Google::Cloud::Error,
+              "AnywhereCache operation failed on the backend with state #{result.state&.downcase}."
+      end
+      puts "Cache not running yet, current state is #{result.state&.downcase}. Retrying in #{min_delay} seconds."
+      sleep min_delay
+      min_delay = [min_delay * 2, max_delay].min # Exponential backoff with a max delay
+      result = storage_control_client.get_anywhere_cache get_request
+    end
+    puts "Successfully created anywhereCache - #{result.name}."
+  rescue Google::Cloud::Error => e
+    puts "Failed to create AnywhereCache. Error: #{e.message}"
+  end
+end
+# [END storage_control_create_anywhere_cache]
+create_anywhere_cache bucket_name: ARGV.shift, zone: ARGV.shift if $PROGRAM_NAME == __FILE__

google-cloud-storage-control/samples/storage_control_disable_anywhere_cache.rb

@@ -0,0 +1,53 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# [START storage_control_disable_anywhere_cache]
+require "google/cloud/storage/control"
+
+# Disables a specific Anywhere Cache instance for a bucket.
+# This operation disables the cache but does not delete it. A disabled cache
+# can be re-enabled later.
+#
+# @param bucket_name [String] The name of the bucket.
+# @param anywhere_cache_id [String] A value that, along with the bucket's
+#   name, uniquely identifies the cache instance (e.g., "us-east1-b").
+#
+# @example
+#   disable_anywhere_cache(
+#     bucket_name: "your-unique-bucket-name",
+#     anywhere_cache_id: "us-east1-b"
+#   )
+#
+def disable_anywhere_cache bucket_name:, anywhere_cache_id:
+  # Create a client object. The client can be reused for multiple calls.
+  storage_control_client = Google::Cloud::Storage::Control.storage_control
+  # Set project to "_" to signify global bucket
+  parent = "projects/_/buckets/#{bucket_name}"
+  name = "#{parent}/anywhereCaches/#{anywhere_cache_id}"
+
+  # Create a request.
+  request = Google::Cloud::Storage::Control::V2::DisableAnywhereCacheRequest.new(
+    name: name
+  )
+  # The request disables the cache, but does not delete it.
+  # The cache can be re-enabled later.
+  begin
+    result = storage_control_client.disable_anywhere_cache request
+    puts "Successfully #{result.state&.downcase} anywhereCache - #{result.name}."
+  rescue Google::Cloud::Error => e
+    puts "Failed to disable AnywhereCache. Error: #{e.message}"
+  end
+end
+# [END storage_control_disable_anywhere_cache]
+disable_anywhere_cache bucket_name: ARGV.shift, anywhere_cache_id: ARGV.shift if $PROGRAM_NAME == __FILE__

google-cloud-storage-control/samples/storage_control_get_anywhere_cache.rb

@@ -0,0 +1,53 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# [START storage_control_get_anywhere_cache]
+require "google/cloud/storage/control"
+
+# Retrieves an Anywhere Cache configuration for a given bucket.
+#
+# @param bucket_name [String] The name of the bucket.
+# @param anywhere_cache_id [String] A value that, along with the bucket's
+#   name, uniquely identifies the cache. (e.g. "us-east1-b")
+#
+# @example
+#   get_anywhere_cache(
+#     bucket_name: "your-unique-bucket-name",
+#     anywhere_cache_id: "us-east1-b"
+#   )
+#
+def get_anywhere_cache bucket_name:, anywhere_cache_id:
+  # Create a client object. The client can be reused for multiple calls.
+  storage_control_client = Google::Cloud::Storage::Control.storage_control
+  # Set project to "_" to signify global bucket
+  parent = "projects/_/buckets/#{bucket_name}"
+  name = "#{parent}/anywhereCaches/#{anywhere_cache_id}"
+
+  # Create a request.
+  request = Google::Cloud::Storage::Control::V2::GetAnywhereCacheRequest.new(
+    name: name
+  )
+  # The request retrieves the cache in the specified bucket.
+  # The cache is identified by the specified ID.
+  # The cache is in the specified bucket.
+
+  begin
+    result = storage_control_client.get_anywhere_cache request
+    puts "Successfully fetched anywhereCache - #{result.name}."
+  rescue Google::Cloud::Error => e
+    puts "Failed to fetch AnywhereCache. Error: #{e.message}"
+  end
+end
+# [END storage_control_get_anywhere_cache]
+get_anywhere_cache bucket_name: ARGV.shift, anywhere_cache_id: ARGV.shift if $PROGRAM_NAME == __FILE__

google-cloud-storage-control/samples/storage_control_list_anywhere_caches.rb

@@ -0,0 +1,43 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# [START storage_control_list_anywhere_caches]
+require "google/cloud/storage/control"
+
+def list_anywhere_caches bucket_name:
+  # The Name of your GCS bucket
+  # bucket_name = "your-unique-bucket-name"
+
+  # Create a client object. The client can be reused for multiple calls.
+  storage_control_client = Google::Cloud::Storage::Control.storage_control
+  # Set project to "_" to signify global bucket
+  parent = "projects/_/buckets/#{bucket_name}"
+
+  # Create a request.
+  request = Google::Cloud::Storage::Control::V2::ListAnywhereCachesRequest.new(
+    parent: parent
+  )
+  # The request lists all caches in the specified bucket.
+  # The caches are identified by the specified bucket name.
+  begin
+    result = storage_control_client.list_anywhere_caches request
+    result.response.anywhere_caches.each do |item|
+      puts "AnywhereCache #{item.name} found in list."
+    end
+  rescue Google::Cloud::Error => e
+    puts "Failed to list AnywhereCaches. Error: #{e.message}"
+  end
+end
+# [END storage_control_list_anywhere_caches]
+list_anywhere_caches bucket_name: ARGV.shift if $PROGRAM_NAME == __FILE__