In general, the google-cloud-spanner library usesServiceAccountcredentials to connect to Google Cloud services. When running withinGoogleCloud Platform environmentsthe credentials will be discovered automatically. When running on otherenvironments, the Service Account credentials can be specified by providing thepath to theJSONkeyfile forthe account (or the JSON itself) inenvironmentvariables. Additionally, Cloud SDK credentials can alsobe discovered automatically, but this is only recommended during development.

Quickstart

1. Create a service account and credentials.
2. Set theenvironment variable.

export SPANNER_CREDENTIALS=/path/to/json`

1. Initialize the client.

require"google/cloud/spanner"client=Google::Cloud::Spanner.new

Project and Credential Lookup

The google-cloud-spanner library aims to make authenticationas simple as possible, and provides several mechanisms to configure your systemwithout providingProject ID andService Account Credentials directly incode.

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

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, theProject ID andCredentials and are discoveredautomatically. Code should be written as if already authenticated.

Environment Variables

TheProject ID andCredentials JSON can be placed in environmentvariables instead of declaring them directly in code. Each service has its ownenvironment variable, allowing for different service accounts to be used fordifferent services. (See the READMEs for the individual service gems fordetails.) The path to theCredentials JSON file can be stored in theenvironment variable, or theCredentials JSON itself can be stored forenvironments such as Docker containers where writing files is difficult or notencouraged.

The environment variables that google-cloud-spanner checks for project ID are:

1. SPANNER_PROJECT
2. GOOGLE_CLOUD_PROJECT

The environment variables that google-cloud-spanner checks for credentials are configured onGoogle::Cloud::Spanner::V1::Spanner::Credentials:

1. SPANNER_CREDENTIALS - Path to JSON file, or JSON contents
2. SPANNER_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

require"google/cloud/spanner"ENV["SPANNER_PROJECT"]="my-project-id"ENV["SPANNER_CREDENTIALS"]="path/to/keyfile.json"client=Google::Cloud::Spanner.new

Configuration

TheProject ID and the path to theCredentials JSON file can be configuredinstead of placing them in environment variables or providing them as arguments.

require"google/cloud/spanner"Google::Cloud::Spanner.configuredo|config|config.project_id="my-project-id"config.credentials="path/to/keyfile.json"endclient=Google::Cloud::Spanner.new

Cloud SDK

This option allows for an easy way to authenticate during development. Ifcredentials are not provided in code or in environment variables, then Cloud SDKcredentials are discovered.

To configure your system for this, simply:

1. Download and install the Cloud SDK
2. Authenticate using OAuth 2.0$ gcloud auth login
3. Write code as if already authenticated.

NOTE: This isnot recommended for running in production. The Cloud SDKshould only be used during development.

Creating a Service Account

Google Cloud requires aProject ID andService Account Credentials toconnect to the APIs. You will use theProject ID andJSON key file toconnect to most services with google-cloud-spanner.

If you are not running this client withinGoogle Cloud Platformenvironments, you need a GoogleDevelopers service account.

1. Visit theGoogle Developers Console.
2. Create a new project or click on an existing project.

3. Activate the slide-out navigation tray and selectAPI Manager. Fromhere, you will enable the APIs that your application requires.

   

   Note: You may need to enable billing in order to use these services.

4. SelectCredentials from the side navigation.

   You should see a screen like one of the following.

   

   

   Find the "Add credentials" drop down and select "Service account" to beguided through downloading a new JSON key file.

   If you want to re-use an existing service account, you can easily generate anew key file. Just select the account you wish to re-use, and click "Generatenew JSON key":

   

   The key file you download will be used by this library to authenticate APIrequests and should be stored in a secure location.

Troubleshooting

If you're having trouble authenticating you can ask for help by following theTroubleshooting Guide.