Secrets reference
COMMERCIAL FEATURE: Access the Secret datatype in the packaged Sensu Go distribution. For more information, see Get started with commercial features.
Sensu’s secrets management eliminates the need to expose secrets in your Sensu configuration. When a Sensu resource definition requires a secret (e.g. a username or password), Sensu allows you to obtain secrets from one or more external secrets providers, so you can both refer to external secrets and consume secrets via backend environment variables.
Only Sensu backends have access to request secrets from a secrets provider. Sensu backends cache fetched secrets in memory, with no persistence to a Sensu datastore or file on disk. Secrets provided via a “lease” with a “lease duration” are deleted from Sensu’s in-memory cache after the configured number of seconds, prompting the Sensu backend to request the secret again.
Secrets are only transmitted over a transport layer security (TLS) websocket connection. Unencrypted connections must not transmit privileged information. For checks, hooks, and dynamic runtime assets, you must enable mutual TLS (mTLS). Sensu will not transmit secrets to agents that do not use mTLS.
Sensu only exposes secrets to Sensu services like environment variables and automatically redacts secrets from all logs, the API, and the web UI.
Secret examples
A secret resource definition refers to a secrets id
and a secrets provider
.
Read the secrets provider reference for the provider specification.
---
type: Secret
api_version: secrets/v1
metadata:
name: sensu-ansible-token
namespace: default
spec:
id: ANSIBLE_TOKEN
provider: env
{
"type": "Secret",
"api_version": "secrets/v1",
"metadata": {
"name": "sensu-ansible-token",
"namespace": "default"
},
"spec": {
"id": "ANSIBLE_TOKEN",
"provider": "env"
}
}
Configure secrets that target a HashiCorp Vault as shown in the following example:
---
type: Secret
api_version: secrets/v1
metadata:
name: sensu-ansible
namespace: default
spec:
id: 'secret/database#password'
provider: vault
{
"type": "Secret",
"api_version": "secrets/v1",
"metadata": {
"name": "sensu-ansible",
"namespace": "default"
},
"spec": {
"id": "secret/database#password",
"provider": "vault"
}
}
The id
value for secrets that target a HashiCorp Vault must start with the name of the secret’s path in Vault.
Sensu requires the secret/
path for the id
value, and the Vault dev server is preconfigured with the secret
keyspace already set up.
In this example, the name of the secret is database
.
The database
secret contains a key called password
, and its value is the password to our database.
Secret configuration
You can use the Secrets API and sensuctl to create, view, and manage your secrets configuration.
To manage secrets configuration with sensuctl, configure sensuctl as the default admin
user.
The standard sensuctl subcommands are available for secrets (list, info, and delete).
To list all secrets:
sensuctl secret list
To see a secret’s status:
sensuctl secret info SECRET_NAME
To delete a secret:
sensuctl secret delete SECRET_NAME
SECRET_NAME
is the value specified in the secret’s name
metadata attribute.
Secret specification
Top-level attributes
type | |
---|---|
description | Top-level attribute that specifies the resource type. For secrets configuration, the type should always be Secret . |
required | Required for secrets configuration in wrapped-json or yaml format. |
type | String |
example |
|
api_version | |
---|---|
description | Top-level attribute that specifies the Sensu API group and version. For secrets configuration in this version of Sensu, the api_version should always be secrets/v1 . |
required | Required for secrets configuration in wrapped-json or yaml format. |
type | String |
example |
|
metadata | |
---|---|
description | Top-level scope that contains the secret’s name and namespace as well as the created_by field. |
required | true |
type | Map of key-value pairs |
example |
|
spec | |
---|---|
description | Top-level map that includes secrets configuration spec attributes. |
required | Required for secrets configuration in wrapped-json or yaml format. |
type | Map of key-value pairs |
example |
|
Metadata attributes
name | |
---|---|
description | Name for the secret that is used internally by Sensu. |
required | true |
type | String |
example |
|
namespace | |
---|---|
description | Sensu RBAC namespace that the secret belongs to. |
required | true |
type | String |
example |
|
created_by | |
---|---|
description | Username of the Sensu user who created the secret or last updated the secret. Sensu automatically populates the created_by field when the secret is created or updated. |
required | false |
type | String |
example |
|
Spec attributes
id | |
---|---|
description | Identifying key for the provider to retrieve the secret. For the Env secrets provider, the id is the environment variable. For the Vault secrets provider, the id is the secret path and key name in the form of secret/path#key . |
required | true |
type | String |
example |
|
provider | |
---|---|
description | Name of the provider with the secret. |
required | true |
type | String |
example |
|