diff --git a/google-cloud-org_policy/.owlbot-manifest.json b/google-cloud-org_policy/.owlbot-manifest.json index b0d4674fc4e4..0684925659d3 100644 --- a/google-cloud-org_policy/.owlbot-manifest.json +++ b/google-cloud-org_policy/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-org_policy/.toys.rb b/google-cloud-org_policy/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-org_policy/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-org_policy/AUTHENTICATION.md b/google-cloud-org_policy/AUTHENTICATION.md index 1fb46bd19df7..a385cacd2480 100644 --- a/google-cloud-org_policy/AUTHENTICATION.md +++ b/google-cloud-org_policy/AUTHENTICATION.md @@ -1,151 +1,122 @@ # Authentication -In general, the google-cloud-org_policy 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. +The recommended way to authenticate to the google-cloud-org_policy library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export ORG_POLICY_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/org_policy" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::OrgPolicy.org_policy +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-org_policy library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-org_policy library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-org_policy -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::OrgPolicy::V2::OrgPolicy::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `ORG_POLICY_CREDENTIALS` - Path to JSON file, or JSON contents -* `ORG_POLICY_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/org_policy" - -ENV["ORG_POLICY_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::OrgPolicy.org_policy -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/org_policy" client = Google::Cloud::OrgPolicy.org_policy do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/org_policy" Google::Cloud::OrgPolicy.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::OrgPolicy.org_policy ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-org_policy +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/org_policy" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-org_policy. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::OrgPolicy.org_policy +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). diff --git a/google-cloud-os_config/.owlbot-manifest.json b/google-cloud-os_config/.owlbot-manifest.json index 0a67aca94698..bcea4e8423ed 100644 --- a/google-cloud-os_config/.owlbot-manifest.json +++ b/google-cloud-os_config/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-os_config/.toys.rb b/google-cloud-os_config/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-os_config/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-os_config/AUTHENTICATION.md b/google-cloud-os_config/AUTHENTICATION.md index 1892bf7b5793..037cff5e2172 100644 --- a/google-cloud-os_config/AUTHENTICATION.md +++ b/google-cloud-os_config/AUTHENTICATION.md @@ -1,151 +1,122 @@ # Authentication -In general, the google-cloud-os_config 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. +The recommended way to authenticate to the google-cloud-os_config library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export OS_CONFIG_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/os_config" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::OsConfig.os_config_service +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-os_config library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-os_config library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-os_config -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::OsConfig::V1::OsConfigService::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `OS_CONFIG_CREDENTIALS` - Path to JSON file, or JSON contents -* `OS_CONFIG_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/os_config" - -ENV["OS_CONFIG_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::OsConfig.os_config_service -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/os_config" client = Google::Cloud::OsConfig.os_config_service do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/os_config" Google::Cloud::OsConfig.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::OsConfig.os_config_service ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-os_config +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/os_config" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-os_config. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::OsConfig.os_config_service +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). diff --git a/google-cloud-os_login/.owlbot-manifest.json b/google-cloud-os_login/.owlbot-manifest.json index 0a56ee6a640d..58dc0267851d 100644 --- a/google-cloud-os_login/.owlbot-manifest.json +++ b/google-cloud-os_login/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-os_login/.toys.rb b/google-cloud-os_login/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-os_login/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-os_login/AUTHENTICATION.md b/google-cloud-os_login/AUTHENTICATION.md index 8e0b3f1b3e62..cc308c358e90 100644 --- a/google-cloud-os_login/AUTHENTICATION.md +++ b/google-cloud-os_login/AUTHENTICATION.md @@ -1,151 +1,122 @@ # Authentication -In general, the google-cloud-os_login 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. +The recommended way to authenticate to the google-cloud-os_login library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export OS_LOGIN_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/os_login" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::OsLogin.os_login_service +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-os_login library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-os_login library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-os_login -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::OsLogin::V1::OsLoginService::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `OS_LOGIN_CREDENTIALS` - Path to JSON file, or JSON contents -* `OS_LOGIN_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/os_login" - -ENV["OS_LOGIN_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::OsLogin.os_login_service -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/os_login" client = Google::Cloud::OsLogin.os_login_service do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/os_login" Google::Cloud::OsLogin.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::OsLogin.os_login_service ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-os_login +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/os_login" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-os_login. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::OsLogin.os_login_service +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). diff --git a/google-cloud-phishing_protection/.owlbot-manifest.json b/google-cloud-phishing_protection/.owlbot-manifest.json index 66863fada4d6..4e55bf566b42 100644 --- a/google-cloud-phishing_protection/.owlbot-manifest.json +++ b/google-cloud-phishing_protection/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-phishing_protection/.toys.rb b/google-cloud-phishing_protection/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-phishing_protection/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-phishing_protection/AUTHENTICATION.md b/google-cloud-phishing_protection/AUTHENTICATION.md index a74e295430e0..cc5990a4b429 100644 --- a/google-cloud-phishing_protection/AUTHENTICATION.md +++ b/google-cloud-phishing_protection/AUTHENTICATION.md @@ -1,151 +1,122 @@ # Authentication -In general, the google-cloud-phishing_protection 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. +The recommended way to authenticate to the google-cloud-phishing_protection library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export PHISHING_PROTECTION_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/phishing_protection" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::PhishingProtection.phishing_protection_service +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-phishing_protection library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-phishing_protection library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-phishing_protection -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::PhishingProtection::V1beta1::PhishingProtectionService::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `PHISHING_PROTECTION_CREDENTIALS` - Path to JSON file, or JSON contents -* `PHISHING_PROTECTION_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/phishing_protection" - -ENV["PHISHING_PROTECTION_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::PhishingProtection.phishing_protection_service -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/phishing_protection" client = Google::Cloud::PhishingProtection.phishing_protection_service do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/phishing_protection" Google::Cloud::PhishingProtection.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::PhishingProtection.phishing_protection_service ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-phishing_protection +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/phishing_protection" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-phishing_protection. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::PhishingProtection.phishing_protection_service +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). diff --git a/google-cloud-policy_simulator/.owlbot-manifest.json b/google-cloud-policy_simulator/.owlbot-manifest.json index 4f917373b013..d8234a685010 100644 --- a/google-cloud-policy_simulator/.owlbot-manifest.json +++ b/google-cloud-policy_simulator/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-policy_simulator/.toys.rb b/google-cloud-policy_simulator/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-policy_simulator/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-policy_simulator/AUTHENTICATION.md b/google-cloud-policy_simulator/AUTHENTICATION.md index eeb2e36bd3fa..7152a87c534a 100644 --- a/google-cloud-policy_simulator/AUTHENTICATION.md +++ b/google-cloud-policy_simulator/AUTHENTICATION.md @@ -1,149 +1,122 @@ # Authentication -In general, the google-cloud-policy_simulator 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. +The recommended way to authenticate to the google-cloud-policy_simulator library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export GOOGLE_CLOUD_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/policy_simulator" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::PolicySimulator.simulator +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-policy_simulator library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-policy_simulator library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-policy_simulator -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::PolicySimulator::V1::Simulator::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/policy_simulator" - -ENV["GOOGLE_CLOUD_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::PolicySimulator.simulator -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/policy_simulator" client = Google::Cloud::PolicySimulator.simulator do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/policy_simulator" Google::Cloud::PolicySimulator.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::PolicySimulator.simulator ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-policy_simulator +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/policy_simulator" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-policy_simulator. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::PolicySimulator.simulator +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). diff --git a/google-cloud-policy_troubleshooter/.owlbot-manifest.json b/google-cloud-policy_troubleshooter/.owlbot-manifest.json index 189a0885ac38..5ed24e3a0067 100644 --- a/google-cloud-policy_troubleshooter/.owlbot-manifest.json +++ b/google-cloud-policy_troubleshooter/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-policy_troubleshooter/.toys.rb b/google-cloud-policy_troubleshooter/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-policy_troubleshooter/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-policy_troubleshooter/AUTHENTICATION.md b/google-cloud-policy_troubleshooter/AUTHENTICATION.md index 7e5d6e3aadfe..74d90fd5d123 100644 --- a/google-cloud-policy_troubleshooter/AUTHENTICATION.md +++ b/google-cloud-policy_troubleshooter/AUTHENTICATION.md @@ -1,151 +1,122 @@ # Authentication -In general, the google-cloud-policy_troubleshooter 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. +The recommended way to authenticate to the google-cloud-policy_troubleshooter library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export POLICY_TROUBLESHOOTER_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/policy_troubleshooter" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::PolicyTroubleshooter.iam_checker +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-policy_troubleshooter library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-policy_troubleshooter library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-policy_troubleshooter -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::PolicyTroubleshooter::V1::IamChecker::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `POLICY_TROUBLESHOOTER_CREDENTIALS` - Path to JSON file, or JSON contents -* `POLICY_TROUBLESHOOTER_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/policy_troubleshooter" - -ENV["POLICY_TROUBLESHOOTER_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::PolicyTroubleshooter.iam_checker -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/policy_troubleshooter" client = Google::Cloud::PolicyTroubleshooter.iam_checker do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/policy_troubleshooter" Google::Cloud::PolicyTroubleshooter.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::PolicyTroubleshooter.iam_checker ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-policy_troubleshooter +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/policy_troubleshooter" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-policy_troubleshooter. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::PolicyTroubleshooter.iam_checker +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). diff --git a/google-cloud-private_catalog/.owlbot-manifest.json b/google-cloud-private_catalog/.owlbot-manifest.json index 25354edc418c..54ee1e3604b3 100644 --- a/google-cloud-private_catalog/.owlbot-manifest.json +++ b/google-cloud-private_catalog/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-private_catalog/.toys.rb b/google-cloud-private_catalog/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-private_catalog/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-private_catalog/AUTHENTICATION.md b/google-cloud-private_catalog/AUTHENTICATION.md index 29dad99d377b..408135d89769 100644 --- a/google-cloud-private_catalog/AUTHENTICATION.md +++ b/google-cloud-private_catalog/AUTHENTICATION.md @@ -1,151 +1,122 @@ # Authentication -In general, the google-cloud-private_catalog 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. +The recommended way to authenticate to the google-cloud-private_catalog library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export PRIVATE_CATALOG_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/private_catalog" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::PrivateCatalog.private_catalog +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-private_catalog library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-private_catalog library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-private_catalog -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::PrivateCatalog::V1beta1::PrivateCatalog::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `PRIVATE_CATALOG_CREDENTIALS` - Path to JSON file, or JSON contents -* `PRIVATE_CATALOG_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/private_catalog" - -ENV["PRIVATE_CATALOG_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::PrivateCatalog.private_catalog -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/private_catalog" client = Google::Cloud::PrivateCatalog.private_catalog do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/private_catalog" Google::Cloud::PrivateCatalog.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::PrivateCatalog.private_catalog ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-private_catalog +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/private_catalog" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-private_catalog. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::PrivateCatalog.private_catalog +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). diff --git a/google-cloud-rapid_migration_assessment/.owlbot-manifest.json b/google-cloud-rapid_migration_assessment/.owlbot-manifest.json index 85196eaae0db..469ce2af3c19 100644 --- a/google-cloud-rapid_migration_assessment/.owlbot-manifest.json +++ b/google-cloud-rapid_migration_assessment/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-rapid_migration_assessment/.toys.rb b/google-cloud-rapid_migration_assessment/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-rapid_migration_assessment/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-rapid_migration_assessment/AUTHENTICATION.md b/google-cloud-rapid_migration_assessment/AUTHENTICATION.md index a7896937e828..90c88f61aadb 100644 --- a/google-cloud-rapid_migration_assessment/AUTHENTICATION.md +++ b/google-cloud-rapid_migration_assessment/AUTHENTICATION.md @@ -1,149 +1,122 @@ # Authentication -In general, the google-cloud-rapid_migration_assessment 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. +The recommended way to authenticate to the google-cloud-rapid_migration_assessment library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export GOOGLE_CLOUD_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/rapid_migration_assessment" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::RapidMigrationAssessment.rapid_migration_assessment +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-rapid_migration_assessment library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-rapid_migration_assessment library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-rapid_migration_assessment -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::RapidMigrationAssessment::V1::RapidMigrationAssessment::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/rapid_migration_assessment" - -ENV["GOOGLE_CLOUD_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::RapidMigrationAssessment.rapid_migration_assessment -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/rapid_migration_assessment" client = Google::Cloud::RapidMigrationAssessment.rapid_migration_assessment do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/rapid_migration_assessment" Google::Cloud::RapidMigrationAssessment.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::RapidMigrationAssessment.rapid_migration_assessment ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-rapid_migration_assessment +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/rapid_migration_assessment" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-rapid_migration_assessment. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::RapidMigrationAssessment.rapid_migration_assessment +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). diff --git a/google-cloud-recaptcha_enterprise/.owlbot-manifest.json b/google-cloud-recaptcha_enterprise/.owlbot-manifest.json index 6429338491ea..f973446c2bb5 100644 --- a/google-cloud-recaptcha_enterprise/.owlbot-manifest.json +++ b/google-cloud-recaptcha_enterprise/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-recaptcha_enterprise/.toys.rb b/google-cloud-recaptcha_enterprise/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-recaptcha_enterprise/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-recaptcha_enterprise/AUTHENTICATION.md b/google-cloud-recaptcha_enterprise/AUTHENTICATION.md index 1f4dc4320088..40c7c6576a97 100644 --- a/google-cloud-recaptcha_enterprise/AUTHENTICATION.md +++ b/google-cloud-recaptcha_enterprise/AUTHENTICATION.md @@ -1,151 +1,122 @@ # Authentication -In general, the google-cloud-recaptcha_enterprise 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. +The recommended way to authenticate to the google-cloud-recaptcha_enterprise library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export RECAPTCHA_ENTERPRISE_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/recaptcha_enterprise" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::RecaptchaEnterprise.recaptcha_enterprise_service +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-recaptcha_enterprise library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-recaptcha_enterprise library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-recaptcha_enterprise -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::RecaptchaEnterprise::V1::RecaptchaEnterpriseService::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `RECAPTCHA_ENTERPRISE_CREDENTIALS` - Path to JSON file, or JSON contents -* `RECAPTCHA_ENTERPRISE_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/recaptcha_enterprise" - -ENV["RECAPTCHA_ENTERPRISE_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::RecaptchaEnterprise.recaptcha_enterprise_service -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/recaptcha_enterprise" client = Google::Cloud::RecaptchaEnterprise.recaptcha_enterprise_service do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/recaptcha_enterprise" Google::Cloud::RecaptchaEnterprise.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::RecaptchaEnterprise.recaptcha_enterprise_service ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-recaptcha_enterprise +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/recaptcha_enterprise" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-recaptcha_enterprise. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::RecaptchaEnterprise.recaptcha_enterprise_service +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). diff --git a/google-cloud-recommendation_engine/.owlbot-manifest.json b/google-cloud-recommendation_engine/.owlbot-manifest.json index c8b5a09a7ae4..9d6a754d637f 100644 --- a/google-cloud-recommendation_engine/.owlbot-manifest.json +++ b/google-cloud-recommendation_engine/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-recommendation_engine/.toys.rb b/google-cloud-recommendation_engine/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-recommendation_engine/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-recommendation_engine/AUTHENTICATION.md b/google-cloud-recommendation_engine/AUTHENTICATION.md index 4e00f1999f37..c225dd7f867a 100644 --- a/google-cloud-recommendation_engine/AUTHENTICATION.md +++ b/google-cloud-recommendation_engine/AUTHENTICATION.md @@ -1,151 +1,122 @@ # Authentication -In general, the google-cloud-recommendation_engine 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. +The recommended way to authenticate to the google-cloud-recommendation_engine library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export RECOMMENDATION_ENGINE_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/recommendation_engine" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::RecommendationEngine.catalog_service +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-recommendation_engine library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-recommendation_engine library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-recommendation_engine -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::RecommendationEngine::V1beta1::CatalogService::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `RECOMMENDATION_ENGINE_CREDENTIALS` - Path to JSON file, or JSON contents -* `RECOMMENDATION_ENGINE_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/recommendation_engine" - -ENV["RECOMMENDATION_ENGINE_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::RecommendationEngine.catalog_service -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/recommendation_engine" client = Google::Cloud::RecommendationEngine.catalog_service do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/recommendation_engine" Google::Cloud::RecommendationEngine.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::RecommendationEngine.catalog_service ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-recommendation_engine +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/recommendation_engine" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-recommendation_engine. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::RecommendationEngine.catalog_service +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). diff --git a/google-cloud-recommender/.owlbot-manifest.json b/google-cloud-recommender/.owlbot-manifest.json index 8ae2eabce4a9..200843f0a856 100644 --- a/google-cloud-recommender/.owlbot-manifest.json +++ b/google-cloud-recommender/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-recommender/.toys.rb b/google-cloud-recommender/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-recommender/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-recommender/AUTHENTICATION.md b/google-cloud-recommender/AUTHENTICATION.md index 3d24d52e4bda..f4a097096b14 100644 --- a/google-cloud-recommender/AUTHENTICATION.md +++ b/google-cloud-recommender/AUTHENTICATION.md @@ -1,151 +1,122 @@ # Authentication -In general, the google-cloud-recommender 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. +The recommended way to authenticate to the google-cloud-recommender library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export RECOMMENDER_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/recommender" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::Recommender.recommender_service +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-recommender library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-recommender library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-recommender -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::Recommender::V1::Recommender::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `RECOMMENDER_CREDENTIALS` - Path to JSON file, or JSON contents -* `RECOMMENDER_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/recommender" - -ENV["RECOMMENDER_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::Recommender.recommender_service -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/recommender" client = Google::Cloud::Recommender.recommender_service do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/recommender" Google::Cloud::Recommender.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::Recommender.recommender_service ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-recommender +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/recommender" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-recommender. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::Recommender.recommender_service +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). diff --git a/google-cloud-redis-cluster/.owlbot-manifest.json b/google-cloud-redis-cluster/.owlbot-manifest.json index 08f0a007fc91..79e07d3f2eaf 100644 --- a/google-cloud-redis-cluster/.owlbot-manifest.json +++ b/google-cloud-redis-cluster/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-redis-cluster/.toys.rb b/google-cloud-redis-cluster/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-redis-cluster/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-redis-cluster/AUTHENTICATION.md b/google-cloud-redis-cluster/AUTHENTICATION.md index abbea76e382f..b6045d2796c1 100644 --- a/google-cloud-redis-cluster/AUTHENTICATION.md +++ b/google-cloud-redis-cluster/AUTHENTICATION.md @@ -1,149 +1,122 @@ # Authentication -In general, the google-cloud-redis-cluster 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. +The recommended way to authenticate to the google-cloud-redis-cluster library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export GOOGLE_CLOUD_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/redis/cluster" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::Redis::Cluster.cloud_redis_cluster +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-redis-cluster library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-redis-cluster library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-redis-cluster -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::Redis::Cluster::V1::CloudRedisCluster::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/redis/cluster" - -ENV["GOOGLE_CLOUD_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::Redis::Cluster.cloud_redis_cluster -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/redis/cluster" client = Google::Cloud::Redis::Cluster.cloud_redis_cluster do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/redis/cluster" Google::Cloud::Redis::Cluster.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::Redis::Cluster.cloud_redis_cluster ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-redis-cluster +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/redis/cluster" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-redis-cluster. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::Redis::Cluster.cloud_redis_cluster +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). diff --git a/google-cloud-redis/.owlbot-manifest.json b/google-cloud-redis/.owlbot-manifest.json index a17298c70bec..34e9cdc1727f 100644 --- a/google-cloud-redis/.owlbot-manifest.json +++ b/google-cloud-redis/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-redis/.toys.rb b/google-cloud-redis/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-redis/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-redis/AUTHENTICATION.md b/google-cloud-redis/AUTHENTICATION.md index fd6bb55a7617..ea9c72a70bac 100644 --- a/google-cloud-redis/AUTHENTICATION.md +++ b/google-cloud-redis/AUTHENTICATION.md @@ -1,151 +1,122 @@ # 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. +The recommended way to authenticate to the google-cloud-redis library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export REDIS_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/redis" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::Redis.cloud_redis +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-redis library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-redis library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-redis -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::Redis::V1::CloudRedis::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `REDIS_CREDENTIALS` - Path to JSON file, or JSON contents -* `REDIS_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/redis" - -ENV["REDIS_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::Redis.cloud_redis -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/redis" client = Google::Cloud::Redis.cloud_redis do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/redis" Google::Cloud::Redis.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::Redis.cloud_redis ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-redis +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/redis" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-redis. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::Redis.cloud_redis +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). diff --git a/google-cloud-resource_settings/.owlbot-manifest.json b/google-cloud-resource_settings/.owlbot-manifest.json index 4f554df50ce6..bf043074cbc9 100644 --- a/google-cloud-resource_settings/.owlbot-manifest.json +++ b/google-cloud-resource_settings/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-resource_settings/.toys.rb b/google-cloud-resource_settings/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-resource_settings/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-resource_settings/AUTHENTICATION.md b/google-cloud-resource_settings/AUTHENTICATION.md index 4e49c9d858d7..c3ccedb3fefe 100644 --- a/google-cloud-resource_settings/AUTHENTICATION.md +++ b/google-cloud-resource_settings/AUTHENTICATION.md @@ -1,151 +1,122 @@ # Authentication -In general, the google-cloud-resource_settings 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. +The recommended way to authenticate to the google-cloud-resource_settings library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export RESOURCE_SETTINGS_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/resource_settings" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::ResourceSettings.resource_settings_service +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-resource_settings library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-resource_settings library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-resource_settings -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::ResourceSettings::V1::ResourceSettingsService::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `RESOURCE_SETTINGS_CREDENTIALS` - Path to JSON file, or JSON contents -* `RESOURCE_SETTINGS_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/resource_settings" - -ENV["RESOURCE_SETTINGS_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::ResourceSettings.resource_settings_service -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/resource_settings" client = Google::Cloud::ResourceSettings.resource_settings_service do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/resource_settings" Google::Cloud::ResourceSettings.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::ResourceSettings.resource_settings_service ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-resource_settings +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/resource_settings" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-resource_settings. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::ResourceSettings.resource_settings_service +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). diff --git a/google-cloud-retail/.owlbot-manifest.json b/google-cloud-retail/.owlbot-manifest.json index d4fd414cbff6..aec5964b0587 100644 --- a/google-cloud-retail/.owlbot-manifest.json +++ b/google-cloud-retail/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-retail/.toys.rb b/google-cloud-retail/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-retail/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-retail/AUTHENTICATION.md b/google-cloud-retail/AUTHENTICATION.md index 55b06888067c..2cdbf1701fd9 100644 --- a/google-cloud-retail/AUTHENTICATION.md +++ b/google-cloud-retail/AUTHENTICATION.md @@ -1,151 +1,122 @@ # Authentication -In general, the google-cloud-retail 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. +The recommended way to authenticate to the google-cloud-retail library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export RETAIL_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/retail" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::Retail.catalog_service +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-retail library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-retail library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-retail -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::Retail::V2::CatalogService::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `RETAIL_CREDENTIALS` - Path to JSON file, or JSON contents -* `RETAIL_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/retail" - -ENV["RETAIL_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::Retail.catalog_service -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/retail" client = Google::Cloud::Retail.catalog_service do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/retail" Google::Cloud::Retail.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::Retail.catalog_service ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-retail +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/retail" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-retail. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::Retail.catalog_service +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa). diff --git a/google-cloud-run-client/.owlbot-manifest.json b/google-cloud-run-client/.owlbot-manifest.json index 24321e433e75..b87b2d5c02f8 100644 --- a/google-cloud-run-client/.owlbot-manifest.json +++ b/google-cloud-run-client/.owlbot-manifest.json @@ -3,6 +3,7 @@ ".gitignore", ".repo-metadata.json", ".rubocop.yml", + ".toys.rb", ".yardopts", "AUTHENTICATION.md", "CHANGELOG.md", diff --git a/google-cloud-run-client/.toys.rb b/google-cloud-run-client/.toys.rb new file mode 100644 index 000000000000..23434bdd5d5b --- /dev/null +++ b/google-cloud-run-client/.toys.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright 2024 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 +# +# https://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. + +# Auto-generated by gapic-generator-ruby. DO NOT EDIT! + +toys_version! ">= 0.15.3" + +if ENV["RUBY_COMMON_TOOLS"] + common_tools_dir = File.expand_path ENV["RUBY_COMMON_TOOLS"] + load File.join(common_tools_dir, "toys", "gapic") +else + load_git remote: "https://github.com/googleapis/ruby-common-tools.git", + path: "toys/gapic", + update: true +end diff --git a/google-cloud-run-client/AUTHENTICATION.md b/google-cloud-run-client/AUTHENTICATION.md index fec24db82ceb..fce7edd96e28 100644 --- a/google-cloud-run-client/AUTHENTICATION.md +++ b/google-cloud-run-client/AUTHENTICATION.md @@ -1,149 +1,122 @@ # Authentication -In general, the google-cloud-run-client 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. +The recommended way to authenticate to the google-cloud-run-client library is to use +[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). +To review all of your authentication options, see [Credentials lookup](#credential-lookup). ## Quickstart -1. [Create a service account and credentials](#creating-a-service-account). -2. Set the [environment variable](#environment-variables). +The following example shows how to set up authentication for a local development +environment with your user credentials. -```sh -export GOOGLE_CLOUD_CREDENTIALS=path/to/keyfile.json -``` - -3. Initialize the client. +**NOTE:** This method is _not_ recommended for running in production. User credentials +should be used only during development. -```ruby -require "google/cloud/run" +1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk). +2. Set up a local ADC file with your user credentials: -client = Google::Cloud::Run.executions +```sh +gcloud auth application-default login ``` -## Credential Lookup - -The google-cloud-run-client library aims to make authentication -as simple as possible, and provides several mechanisms to configure your system -without requiring **Service Account Credentials** directly in code. - -**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 GCP credentials - -### Google Cloud Platform environments +3. Write code as if already authenticated. -When running on Google Cloud Platform (GCP), including Google Compute Engine -(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud -Functions (GCF) and Cloud Run, **Credentials** are discovered automatically. -Code should be written as if already authenticated. +For more information about setting up authentication for a local development environment, see +[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev). -### Environment Variables +## Credential Lookup -The **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 google-cloud-run-client library provides several mechanisms to configure your system. +Generally, using Application Default Credentials to facilitate automatic +credentials discovery is the easist method. But if you need to explicitly specify +credentials, there are several methods available to you. -The environment variables that google-cloud-run-client -checks for credentials are configured on the service Credentials class (such as -`::Google::Cloud::Run::V2::Executions::Credentials`): +Credentials are accepted in the following ways, in the following order or precedence: -* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents -* `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents -* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file +1. Credentials specified in method arguments +2. Credentials specified in configuration +3. Credentials pointed to or included in environment variables +4. Credentials found in local ADC file +5. Credentials returned by the metadata server for the attached service account (GCP) -```ruby -require "google/cloud/run" - -ENV["GOOGLE_CLOUD_CREDENTIALS"] = "path/to/keyfile.json" +### Configuration -client = Google::Cloud::Run.executions -``` +You can configure a path to a JSON credentials file, either for an individual client object or +globally, for all client objects. The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -### Configuration +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. -The path to the **Credentials JSON** file can be configured instead of storing -it in an environment variable. Either on an individual client initialization: +To configure a credentials file for an individual client initialization: ```ruby require "google/cloud/run" client = Google::Cloud::Run.executions do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end ``` -Or globally for all clients: +To configure a credentials file globally for all clients: ```ruby require "google/cloud/run" Google::Cloud::Run.configure do |config| - config.credentials = "path/to/keyfile.json" + config.credentials = "path/to/credentialfile.json" end client = Google::Cloud::Run.executions ``` -### Cloud SDK +### Environment Variables -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. +You can also use an environment variable to provide a JSON credentials file. +The environment variable can contain a path to the credentials file or, for +environments such as Docker containers where writing files is not encouraged, +you can include the credentials file itself. -To configure your system for this, simply: +The JSON file can contain credentials created for +[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation), +[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a +[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key). -1. [Download and install the Cloud SDK](https://cloud.google.com/sdk) -2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login` -3. Write code as if already authenticated. +Note: Service account keys are a security risk if not managed correctly. You should +[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree) +whenever possible. + +The environment variables that google-cloud-run-client +checks for credentials are: -**NOTE:** This is _not_ recommended for running in production. The Cloud SDK -*should* only be used during development. +* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents +* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file -## Creating a Service Account +```ruby +require "google/cloud/run" -Google Cloud requires **Service Account Credentials** to -connect to the APIs. You will use the **JSON key file** to -connect to most services with google-cloud-run-client. +ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json" -If you are not running this client within -[Google Cloud Platform environments](#google-cloud-platform-environments), you -need a Google Developers service account. +client = Google::Cloud::Run.executions +``` -1. Visit the [Google Cloud Console](https://console.cloud.google.com/project). -2. Create a new project or click on an existing project. -3. Activate the menu in the upper left and select **APIs & Services**. From - here, you will enable the APIs that your application requires. +### Local ADC file - *Note: You may need to enable billing in order to use these services.* +You can set up a local ADC file with your user credentials for authentication during +development. If credentials are not provided in code or in environment variables, +then the local ADC credentials are discovered. -4. Select **Credentials** from the side navigation. +Follow the steps in [Quickstart](#quickstart) to set up a local ADC file. - Find the "Create credentials" drop down near the top of the page, and select - "Service account" to be guided through downloading a new JSON key file. +### Google Cloud Platform environments - 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, click the pencil - tool on the right side to edit the service account, select the **Keys** tab, - and then select **Add Key**. +When running on Google Cloud Platform (GCP), including Google Compute Engine +(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud +Functions (GCF) and Cloud Run, credentials are retrieved from the attached +service account automatically. Code should be written as if already authenticated. - The key file you download will be used by this library to authenticate API - requests and should be stored in a secure location. +For more information, see +[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa).