Secret (AWS)

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 AWS Secrets Manager in Region, signed with Access key ID and Secret access key. A plugin field then carries a reference in place of the value, for example $secret://aws/production/<secret name>/<json key> for this secret under the ID production.

A reference names a secret of Secrets Manager and one key of the JSON it holds. When Secrets 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 Secrets Manager by your security team rather than written on routes.
• The access keys of the gateway already live in environment variables of the gateway host, and the secret names them with $env:// references.
• Access keys your account issues together with a session token, written under Session token.
• A Secrets Manager reached through an endpoint of its own, a private endpoint inside your network for example, under Endpoint.

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 Google Cloud Secret Manager — see Secret (Secrets tell the engine where a secret manager keeps the values plugins reference).

Set it up

Read secrets from Secrets Manager in one region

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

Under General set ID to aws/production. Under Credentials set Access key ID to $env://AWS_ACCESS_KEY_ID and set Secret access key to $env://AWS_SECRET_ACCESS_KEY. Under Connection set Region to eu-central-1.

secret · AWS · as the console saves it

{
  "id": "aws/production",
  "access_key_id": "$env://AWS_ACCESS_KEY_ID",
  "secret_access_key": "$env://AWS_SECRET_ACCESS_KEY",
  "region": "eu-central-1"
}

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.
• Region — Outside AWS, the first read in each engine worker waits five seconds for the EC2 metadata address.
• Endpoint — An address without http:// or https:// in front, secretsmanager.eu-central-1.amazonaws.com for example, is refused when you save.
• Endpoint — Any scheme but http(s) 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.
• ID — The secret is stored as its manager and this ID joined by a slash, aws/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.
• AdviceKeep the access keys out of the stored secret: write them as $env:// references to variables of the gateway host.

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://aws/<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 Secrets Manager, slashes included, 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

^aws/.+

Credentials

Access key IDaccess_key_idstringRequired

May be an $env:// reference to a variable of the gateway host.

Secret access keysecret_access_keystringRequired

May be an $env:// reference to a variable of the gateway host. Stored on the engine and shown only to roles that manage this object.

Session tokensession_tokenstring

May be an $env:// reference to a variable of the gateway host. Stored on the engine and shown only to roles that manage this object.

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.

Regionregionstringdefault us-east-1

Also names the default endpoint, https://secretsmanager.<region>.amazonaws.com.

Endpointendpoint_urlstring

Only its scheme, host and port are read; a path is dropped.

pattern

^https?:\/\/([\da-zA-Z.-]+|\[[\da-fA-F:]+\])(:\d+)?