Secret (GCP)

Secrets tell the engine where a secret manager keeps the values plugins reference.

In the console SecretsEngine resource secret

What a secret is

A secret tells the gateway where a secret manager keeps the values plugins reference. This one reads them from Google Cloud Secret Manager, signed in as a service account. Under Credentials you choose Service account written here or Service account file on the gateway host.

A plugin field then carries a reference in place of the value, for example $secret://gcp/production/<secret name>/<json key> for this secret under the ID production. When Secret Manager cannot answer, the reference resolves to nothing and a plugin receives the reference text instead of the value.

When to use it

• The passwords and keys plugins send on, to a log service or a backend for example, are kept in Secret Manager by your security team rather than written on routes.
• A service account of your project, orders-prod for example, written into the secret with its client email and private key.
• A key file your platform team places on every gateway host, read from the path under Service account file instead of being stored in the secret.

Not for values kept in a Vault key-value store — see Secret (Secrets tell the engine where a secret manager keeps the values plugins reference) or values kept in AWS Secrets Manager — see Secret (Secrets tell the engine where a secret manager keeps the values plugins reference).

Set it up

Read secrets from Secret Manager with a service account written here

A plugin field reads a value as $secret://gcp/production/<secret name>/<json key>.

Under General set ID to gcp/production. Under Credentials choose Service account written here and fill Service account as in the JSON below.

secret · GCP · as the console saves it

{
  "id": "gcp/production",
  "auth_config": {
    "client_email": "gateway@orders-prod.iam.gserviceaccount.com",
    "private_key": "<private key PEM>",
    "project_id": "orders-prod"
  }
}

More scenarios

Read secrets from Secret Manager with a service account file on the gateway host

The file must exist at this path on every gateway node; a plugin field reads a value as $secret://gcp/production-file/<secret name>/<json key>.

Under General set ID to gcp/production-file. Under Credentials choose Service account file on the gateway host and set Service account file to /etc/gateway/google/secret-manager.json.

secret · GCP · as the console saves it

{
  "id": "gcp/production-file",
  "auth_file": "/etc/gateway/google/secret-manager.json"
}

Things to know

• When the manager cannot answer, a reference to this secret resolves to nothing: a plugin receives the reference text, and a consumer whose credential names it is skipped. A manager that never answers holds the request for sixty seconds first.
• Service account — The engine keeps these settings per email and project for five minutes: edits, TLS verification included, apply late, and a second secret with the same pair reads the first's.
• Private key — A non-RSA key answers 500 to requests reading this secret and, once a plugin's credential names it, to every request and consumer or credential save of that plugin.
• Service account file — A file without entries_uri answers 500 to requests reading this secret and, once a plugin's credential names it, to every request and consumer or credential save of that plugin.
• Service account — The secret holds one of the two: a service account written here and a Service account file together are refused when you save.
• ID — The secret is stored as its manager and this ID joined by a slash, gcp/production for the ID production. A reference names the secret by that ID.
• Deleting a secret makes every reference to it stop resolving. g8 does not see a certificate whose private key is read from the secret, so deleting the secret can break TLS for that certificate.

Referring to a value

Any string setting of a plugin, a credential or an upstream's TLS block may carry a reference the engine resolves when it runs: $secret://gcp/<id>/<secret name>/<json key>, where <id> is the part of this secret's ID after the manager's name, the next part is the name of the secret in Secret Manager, without slashes, and the last is one key of a secret whose value is a JSON object; left out, the whole value is read. A reference that resolves to nothing is kept as its own text.

Settings

The fields as the console shows them, section by section.

General

IDidstringRequired

Letters, digits, dots, hyphens and underscores, up to 64 characters. It cannot be changed later. The secret is stored as its manager and this ID joined by a slash. In JSON it carries the manager's name and a slash in front, as the pattern shows; the console asks only for the part after the slash.

the manager name, a slash and the ID

pattern

^gcp/.+

Credentials

Choose one:

• Service account written hereThe account and its private key are stored in this secret.
• Service account file on the gateway hostThe engine reads the account from a key file at a path on its host.

Service account written here

Service accountauth_configobjectRequired

Client emailauth_config.client_emailstringRequired

Private keyauth_config.private_keystringRequired

An RSA key in PEM. Sent to the engine and never shown again.

pattern

^-----BEGIN RSA PRIVATE KEY-----|^-----BEGIN PRIVATE KEY-----\r?\nMII[A-Za-z0-9+/]{3}IBADANBgkqhkiG9w0BAQEFAAS

Project IDauth_config.project_idstringRequired

Secret Manager APIauth_config.entries_uristringdefault https://secretmanager.googleapis.com/v1

The engine always reads the latest version of a secret.

Scopesauth_config.scopearray of stringsdefault ["https://www.googleapis.com/auth/cloud-platform"]

Token URIauth_config.token_uristringdefault https://oauth2.googleapis.com/token

Service account file on the gateway host

Service account fileauth_filestringRequired

A path on the gateway host, read at each lookup. The key file Google issues carries no entries_uri; add one.

Connection

When the manager cannot answer, a reference to this secret resolves to nothing: a plugin receives the reference text, and a consumer whose credential names it is skipped. A manager that never answers holds the request first: Vault for five seconds, AWS and GCP for sixty.

Verify TLS certificatesssl_verifybooleandefault true