ruby: add AUTHENTICATION.md template

synthtool/gcp/common.py

@@ -71,6 +71,12 @@ def node_library(self, **kwargs) -> Path:
     def php_library(self, **kwargs) -> Path:
         return self._generic_library("php_library", **kwargs)
 
+    def ruby_library(self, **kwargs) -> Path:
+        # kwargs["metadata"] is required to load values from .repo-metadata.json
+        if "metadata" not in kwargs:
+            kwargs["metadata"] = {}
+        return self._generic_library("ruby_library", **kwargs)
+
     def render(self, template_name: str, **kwargs) -> Path:
         return self._templates.render(template_name, **kwargs)
 

synthtool/gcp/templates/ruby_library/AUTHENTICATION.md

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

tests/test_templates.py

@@ -22,6 +22,7 @@
 
 FIXTURES = Path(__file__).parent / "fixtures"
 NODE_TEMPLATES = Path(__file__).parent.parent / "synthtool/gcp/templates/node_library"
+RUBY_TEMPLATES = Path(__file__).parent.parent / "synthtool/gcp/templates/ruby_library"
 
 
 def test_render():
@@ -119,3 +120,21 @@ def test_readme_partials():
     )
 
     os.chdir(cwd)
+
+
+def test_ruby_authentication():
+    t = templates.Templates(RUBY_TEMPLATES)
+    # .repo-metadata.json in google-cloud-ruby package directories
+    repo_metadata = {
+        "distribution_name": "google-cloud-bigquery-data_transfer",
+        "module_name": "Bigquery::DataTransfer",
+        "module_name_credentials": "Bigquery::DataTransfer::V1",
+        "env_var_prefix": "DATA_TRANSFER",
+    }
+    metadata = {"repo": repo_metadata}
+    result = t.render("AUTHENTICATION.md", metadata=metadata).read_text()
+
+    assert 'require "google/cloud/bigquery/data_transfer"' in result
+    assert "Google::Cloud::Bigquery::DataTransfer.new" in result
+    assert "Google::Cloud::Bigquery::DataTransfer::V1::Credentials" in result
+    assert "DATA_TRANSFER_CREDENTIALS" in result