google-cloud-redis 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 978325ee0d21558b615d62b4b5716405bede0027a513a17514121df9eda358b8
-  data.tar.gz: 0ed9772a1c34363a8ff183e8399d33b630e9532d48fac8e65623ab0afbed3563
+  metadata.gz: 77259a383da44a43dc112d8e849560089fbc35b5c0b539becb033008e4dbd07f
+  data.tar.gz: 36a3f0c3d32cc3bf9de0acb214a9acc29b186a2b5729077a34d24a9284f3ed84
 SHA512:
-  metadata.gz: c1d40b70a1151c4c670f252985969d04b80eca1a989f29510377276f0a53ddd830e1bc0a179b2009550773126b094669b98f1a3d8f0dc062b0fefa9fb3da915f
-  data.tar.gz: af1b9ad36e27ac1e14637bbe7a695023cd19d9f6c30ef32146ac0690aa78d034a95897352ef5e9ef44b5bce704b47cde238962db5002cc821c71ed981f05499e
+  metadata.gz: 189e8912ae7fa344a20ed36b824d71b5fab86f28f969ef59ad94d17b80d119100919852ed934770121e7325d5ee4afc2c85f5fe8596602e8ee9d608ea4571fe1
+  data.tar.gz: e444e4a28bd9f59f3d9350b719fed22d57c0026c130a2cfadd95d45b90ff90ec288e007704823172756916f88e06664cb27e3ed8bc22bb969d04e67c31a3eb48

data/.yardopts

@@ -7,3 +7,5 @@
 ./lib/**/*.rb
 -
 README.md
+AUTHENTICATION.md
+LICENSE

data/AUTHENTICATION.md

@@ -0,0 +1,199 @@
+# Authentication
+
+In general, the google-cloud-redis library uses [Service
+Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts)
+credentials to connect to Google Cloud services. When running within [Google
+Cloud Platform environments](#google-cloud-platform-environments)
+the credentials will be discovered automatically. When running on other
+environments, the Service Account credentials can be specified by providing the
+path to the [JSON
+keyfile](https://cloud.google.com/iam/docs/managing-service-account-keys) for
+the account (or the JSON itself) in [environment
+variables](#environment-variables). Additionally, Cloud SDK credentials can also
+be discovered automatically, but this is only recommended during development.
+
+## Quickstart
+
+1. [Create a service account and credentials](#creating-a-service-account).
+2. Set the [environment variable](#environment-variables).
+
+```sh
+export REDIS_CREDENTIALS=/path/to/json`
+```
+
+3. Initialize the client.
+
+```ruby
+require "google/cloud/redis"
+
+client = Google::Cloud::Redis.new
+```
+
+## Project and Credential Lookup
+
+The google-cloud-redis library aims to make authentication
+as simple as possible, and provides several mechanisms to configure your system
+without providing **Project ID** and **Service Account Credentials** directly in
+code.
+
+**Project ID** is discovered in the following order:
+
+1. Specify project ID in method arguments
+2. Specify project ID in configuration
+3. Discover project ID in environment variables
+4. Discover GCE project ID
+5. Discover project ID in credentials JSON
+
+**Credentials** are discovered in the following order:
+
+1. Specify credentials in method arguments
+2. Specify credentials in configuration
+3. Discover credentials path in environment variables
+4. Discover credentials JSON in environment variables
+5. Discover credentials file in the Cloud SDK's path
+6. Discover GCE credentials
+
+### Google Cloud Platform environments
+
+While running on Google Cloud Platform environments such as Google Compute
+Engine, Google App Engine and Google Kubernetes Engine, no extra work is needed.
+The **Project ID** and **Credentials** and are discovered automatically. Code
+should be written as if already authenticated. Just be sure when you [set up the
+GCE instance][gce-how-to], you add the correct scopes for the APIs you want to
+access. For example:
+
+  * **All APIs**
+    * `https://www.googleapis.com/auth/cloud-platform`
+    * `https://www.googleapis.com/auth/cloud-platform.read-only`
+  * **BigQuery**
+    * `https://www.googleapis.com/auth/bigquery`
+    * `https://www.googleapis.com/auth/bigquery.insertdata`
+  * **Compute Engine**
+    * `https://www.googleapis.com/auth/compute`
+  * **Datastore**
+    * `https://www.googleapis.com/auth/datastore`
+    * `https://www.googleapis.com/auth/userinfo.email`
+  * **DNS**
+    * `https://www.googleapis.com/auth/ndev.clouddns.readwrite`
+  * **Pub/Sub**
+    * `https://www.googleapis.com/auth/pubsub`
+  * **Storage**
+    * `https://www.googleapis.com/auth/devstorage.full_control`
+    * `https://www.googleapis.com/auth/devstorage.read_only`
+    * `https://www.googleapis.com/auth/devstorage.read_write`
+
+### Environment Variables
+
+The **Project ID** and **Credentials JSON** can be placed in environment
+variables instead of declaring them directly in code. Each service has its own
+environment variable, allowing for different service accounts to be used for
+different services. (See the READMEs for the individual service gems for
+details.) The path to the **Credentials JSON** file can be stored in the
+environment variable, or the **Credentials JSON** itself can be stored for
+environments such as Docker containers where writing files is difficult or not
+encouraged.
+
+The environment variables that google-cloud-redis checks for project ID are:
+
+1. `REDIS_PROJECT`
+2. `GOOGLE_CLOUD_PROJECT`
+
+The environment variables that google-cloud-redis checks for credentials are configured on {Google::Cloud::Redis::V1::Credentials}:
+
+1. `REDIS_CREDENTIALS` - Path to JSON file, or JSON contents
+2. `REDIS_KEYFILE` - Path to JSON file, or JSON contents
+3. `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents
+4. `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents
+5. `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file
+
+```ruby
+require "google/cloud/redis"
+
+ENV["REDIS_PROJECT"]     = "my-project-id"
+ENV["REDIS_CREDENTIALS"] = "path/to/keyfile.json"
+
+client = Google::Cloud::Redis.new
+```
+
+### Configuration
+
+The **Project ID** and **Credentials JSON** can be configured instead of placing them in environment variables or providing them as arguments.
+
+```ruby
+require "google/cloud/redis"
+
+Google::Cloud::Redis.configure do |config|
+  config.project_id  = "my-project-id"
+  config.credentials = "path/to/keyfile.json"
+end
+
+client = Google::Cloud::Redis.new
+```
+
+### Cloud SDK
+
+This option allows for an easy way to authenticate during development. If
+credentials are not provided in code or in environment variables, then Cloud SDK
+credentials are discovered.
+
+To configure your system for this, simply:
+
+1. [Download and install the Cloud SDK](https://cloud.google.com/sdk)
+2. Authenticate using OAuth 2.0 `$ gcloud auth login`
+3. Write code as if already authenticated.
+
+**NOTE:** This is _not_ recommended for running in production. The Cloud SDK
+*should* only be used during development.
+
+[gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
+[dev-console]: https://console.cloud.google.com/project
+
+[enable-apis]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/enable-apis.png
+
+[create-new-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account.png
+[create-new-service-account-existing-keys]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account-existing-keys.png
+[reuse-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/reuse-service-account.png
+
+## Creating a Service Account
+
+Google Cloud requires a **Project ID** and **Service Account Credentials** to
+connect to the APIs. You will use the **Project ID** and **JSON key file** to
+connect to most services with google-cloud-redis.
+
+If you are not running this client within [Google Cloud Platform
+environments](#google-cloud-platform-environments), you need a Google
+Developers service account.
+
+1. Visit the [Google Developers Console][dev-console].
+1. Create a new project or click on an existing project.
+1. Activate the slide-out navigation tray and select **API Manager**. From
+   here, you will enable the APIs that your application requires.
+
+   ![Enable the APIs that your application requires][enable-apis]
+
+   *Note: You may need to enable billing in order to use these services.*
+
+1. Select **Credentials** from the side navigation.
+
+   You should see a screen like one of the following.
+
+   ![Create a new service account][create-new-service-account]
+
+   ![Create a new service account With Existing Keys][create-new-service-account-existing-keys]
+
+   Find the "Add credentials" drop down and select "Service account" to be
+   guided through downloading a new JSON key file.
+
+   If you want to re-use an existing service account, you can easily generate a
+   new key file. Just select the account you wish to re-use, and click "Generate
+   new JSON key":
+
+   ![Re-use an existing service account][reuse-service-account]
+
+   The key file you download will be used by this library to authenticate API
+   requests and should be stored in a secure location.
+
+## Troubleshooting
+
+If you're having trouble authenticating you can ask for help by following the
+{file:TROUBLESHOOTING.md Troubleshooting Guide}.

data/README.md

@@ -1,8 +1,7 @@
 # Ruby Client for Google Cloud Memorystore for Redis API ([Alpha](https://github.com/googleapis/google-cloud-ruby#versioning))
 
 [Google Cloud Memorystore for Redis API][Product Documentation]:
-The Google Cloud Memorystore for Redis API is used for creating and managing
-Redis instances on the Google Cloud Platform.
+Creates and manages Redis instances on the Google Cloud Platform.
 - [Client Library Documentation][]
 - [Product Documentation][]
 

data/lib/google/cloud/redis.rb

@@ -1,4 +1,4 @@
-# Copyright 2018 Google LLC
+# Copyright 2019 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -24,8 +24,7 @@ module Google
     # # Ruby Client for Google Cloud Memorystore for Redis API ([Alpha](https://github.com/googleapis/google-cloud-ruby#versioning))
     #
     # [Google Cloud Memorystore for Redis API][Product Documentation]:
-    # The Google Cloud Memorystore for Redis API is used for creating and managing
-    # Redis instances on the Google Cloud Platform.
+    # Creates and manages Redis instances on the Google Cloud Platform.
     # - [Product Documentation][]
     #
     # ## Quick Start
@@ -101,7 +100,7 @@ module Google
       # * As such, Redis instances are resources of the form:
       #   `/projects/{project_id}/locations/{location_id}/instances/{instance_id}`
       #
-      # Note that location_id must be refering to a GCP `region`; for example:
+      # Note that location_id must be referring to a GCP `region`; for example:
       # * `projects/redpepper-1290/locations/us-central1/instances/my-redis`
       #
       # @param version [Symbol, String]

data/lib/google/cloud/redis/v1.rb

@@ -1,4 +1,4 @@
-# Copyright 2018 Google LLC
+# Copyright 2019 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -25,8 +25,7 @@ module Google
       # # Ruby Client for Google Cloud Memorystore for Redis API ([Alpha](https://github.com/googleapis/google-cloud-ruby#versioning))
       #
       # [Google Cloud Memorystore for Redis API][Product Documentation]:
-      # The Google Cloud Memorystore for Redis API is used for creating and managing
-      # Redis instances on the Google Cloud Platform.
+      # Creates and manages Redis instances on the Google Cloud Platform.
       # - [Product Documentation][]
       #
       # ## Quick Start
@@ -94,7 +93,7 @@ module Google
         # * As such, Redis instances are resources of the form:
         #   `/projects/{project_id}/locations/{location_id}/instances/{instance_id}`
         #
-        # Note that location_id must be refering to a GCP `region`; for example:
+        # Note that location_id must be referring to a GCP `region`; for example:
         # * `projects/redpepper-1290/locations/us-central1/instances/my-redis`
         #
         # @param credentials [Google::Auth::Credentials, String, Hash, GRPC::Core::Channel, GRPC::Core::ChannelCredentials, Proc]

data/lib/google/cloud/redis/v1/cloud_redis_client.rb

@@ -1,4 +1,4 @@
-# Copyright 2018 Google LLC
+# Copyright 2019 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -47,7 +47,7 @@ module Google
         # * As such, Redis instances are resources of the form:
         #   `/projects/{project_id}/locations/{location_id}/instances/{instance_id}`
         #
-        # Note that location_id must be refering to a GCP `region`; for example:
+        # Note that location_id must be referring to a GCP `region`; for example:
         # * `projects/redpepper-1290/locations/us-central1/instances/my-redis`
         #
         # @!attribute [r] cloud_redis_stub
@@ -88,28 +88,17 @@ module Google
             self::GRPC_INTERCEPTORS = CloudRedisClient::GRPC_INTERCEPTORS
           end
 
-          LOCATION_PATH_TEMPLATE = Google::Gax::PathTemplate.new(
-            "projects/{project}/locations/{location}"
-          )
-
-          private_constant :LOCATION_PATH_TEMPLATE
-
           INSTANCE_PATH_TEMPLATE = Google::Gax::PathTemplate.new(
             "projects/{project}/locations/{location}/instances/{instance}"
           )
 
           private_constant :INSTANCE_PATH_TEMPLATE
 
-          # Returns a fully-qualified location resource name string.
-          # @param project [String]
-          # @param location [String]
-          # @return [String]
-          def self.location_path project, location
-            LOCATION_PATH_TEMPLATE.render(
-              :"project" => project,
-              :"location" => location
-            )
-          end
+          LOCATION_PATH_TEMPLATE = Google::Gax::PathTemplate.new(
+            "projects/{project}/locations/{location}"
+          )
+
+          private_constant :LOCATION_PATH_TEMPLATE
 
           # Returns a fully-qualified instance resource name string.
           # @param project [String]
@@ -124,6 +113,17 @@ module Google
             )
           end
 
+          # Returns a fully-qualified location resource name string.
+          # @param project [String]
+          # @param location [String]
+          # @return [String]
+          def self.location_path project, location
+            LOCATION_PATH_TEMPLATE.render(
+              :"project" => project,
+              :"location" => location
+            )
+          end
+
           # @param credentials [Google::Auth::Credentials, String, Hash, GRPC::Core::Channel, GRPC::Core::ChannelCredentials, Proc]
           #   Provides the means for authenticating requests made by the client. This parameter can
           #   be many types.
@@ -239,27 +239,50 @@ module Google
             @list_instances = Google::Gax.create_api_call(
               @cloud_redis_stub.method(:list_instances),
               defaults["list_instances"],
-              exception_transformer: exception_transformer
+              exception_transformer: exception_transformer,
+              params_extractor: proc do |request|
+                {'parent' => request.parent}
+              end
             )
             @get_instance = Google::Gax.create_api_call(
               @cloud_redis_stub.method(:get_instance),
               defaults["get_instance"],
-              exception_transformer: exception_transformer
+              exception_transformer: exception_transformer,
+              params_extractor: proc do |request|
+                {'name' => request.name}
+              end
             )
             @create_instance = Google::Gax.create_api_call(
               @cloud_redis_stub.method(:create_instance),
               defaults["create_instance"],
-              exception_transformer: exception_transformer
+              exception_transformer: exception_transformer,
+              params_extractor: proc do |request|
+                {'parent' => request.parent}
+              end
             )
             @update_instance = Google::Gax.create_api_call(
               @cloud_redis_stub.method(:update_instance),
               defaults["update_instance"],
-              exception_transformer: exception_transformer
+              exception_transformer: exception_transformer,
+              params_extractor: proc do |request|
+                {'instance.name' => request.instance.name}
+              end
             )
             @delete_instance = Google::Gax.create_api_call(
               @cloud_redis_stub.method(:delete_instance),
               defaults["delete_instance"],
-              exception_transformer: exception_transformer
+              exception_transformer: exception_transformer,
+              params_extractor: proc do |request|
+                {'name' => request.name}
+              end
+            )
+            @failover_instance = Google::Gax.create_api_call(
+              @cloud_redis_stub.method(:failover_instance),
+              defaults["failover_instance"],
+              exception_transformer: exception_transformer,
+              params_extractor: proc do |request|
+                {'name' => request.name}
+              end
             )
           end
 
@@ -602,6 +625,77 @@ module Google
             operation.on_done { |operation| yield(operation) } if block_given?
             operation
           end
+
+          # Failover the master role to current replica node against a specific
+          # STANDARD tier redis instance.
+          #
+          # @param name [String]
+          #   Required. Redis instance resource name using the form:
+          #       `projects/{project_id}/locations/{location_id}/instances/{instance_id}`
+          #   where `location_id` refers to a GCP region
+          # @param data_protection_mode [Google::Cloud::Redis::V1::FailoverInstanceRequest::DataProtectionMode]
+          #   Optional. Available data protection modes that the user can choose. If it's
+          #   unspecified, data protection mode will be LIMITED_DATA_LOSS by default.
+          # @param options [Google::Gax::CallOptions]
+          #   Overrides the default settings for this call, e.g, timeout,
+          #   retries, etc.
+          # @return [Google::Gax::Operation]
+          # @raise [Google::Gax::GaxError] if the RPC is aborted.
+          # @example
+          #   require "google/cloud/redis"
+          #
+          #   cloud_redis_client = Google::Cloud::Redis.new(version: :v1)
+          #   formatted_name = Google::Cloud::Redis::V1::CloudRedisClient.instance_path("[PROJECT]", "[LOCATION]", "[INSTANCE]")
+          #
+          #   # TODO: Initialize `data_protection_mode`:
+          #   data_protection_mode = :DATA_PROTECTION_MODE_UNSPECIFIED
+          #
+          #   # Register a callback during the method call.
+          #   operation = cloud_redis_client.failover_instance(formatted_name, data_protection_mode) do |op|
+          #     raise op.results.message if op.error?
+          #     op_results = op.results
+          #     # Process the results.
+          #
+          #     metadata = op.metadata
+          #     # Process the metadata.
+          #   end
+          #
+          #   # Or use the return value to register a callback.
+          #   operation.on_done do |op|
+          #     raise op.results.message if op.error?
+          #     op_results = op.results
+          #     # Process the results.
+          #
+          #     metadata = op.metadata
+          #     # Process the metadata.
+          #   end
+          #
+          #   # Manually reload the operation.
+          #   operation.reload!
+          #
+          #   # Or block until the operation completes, triggering callbacks on
+          #   # completion.
+          #   operation.wait_until_done!
+
+          def failover_instance \
+              name,
+              data_protection_mode,
+              options: nil
+            req = {
+              name: name,
+              data_protection_mode: data_protection_mode
+            }.delete_if { |_, v| v.nil? }
+            req = Google::Gax::to_proto(req, Google::Cloud::Redis::V1::FailoverInstanceRequest)
+            operation = Google::Gax::Operation.new(
+              @failover_instance.call(req, options),
+              @operations_client,
+              Google::Cloud::Redis::V1::Instance,
+              Google::Cloud::Redis::V1::OperationMetadata,
+              call_options: options
+            )
+            operation.on_done { |operation| yield(operation) } if block_given?
+            operation
+          end
         end
       end
     end