Secrets reference

COMMERCIAL FEATURE: Access the Secret datatype in the packaged Sensu Go distribution. For more information, read 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 (for example, 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.

NOTE: Secrets management is implemented for checks, handlers, and mutators.

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
spec:
  id: ANSIBLE_TOKEN
  provider: env
{
  "type": "Secret",
  "api_version": "secrets/v1",
  "metadata": {
    "name": "sensu-ansible-token"
  },
  "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
spec:
  id: 'secret/database#password'
  provider: vault
{
  "type": "Secret",
  "api_version": "secrets/v1",
  "metadata": {
    "name": "sensu-ansible"
  },
  "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. The Vault dev server is preconfigured with the secret keyspace already set up. This is convenient for learning and getting started with Vault secrets management, so this example and our guide to secrets management use the secret/ path for the id value. 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 enterprise/secrets/v1 API endpoints 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 review 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

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 
api_version: secrets/v1
{
  "api_version": "secrets/v1"
}
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 
metadata:
  name: sensu-ansible-token
  namespace: default
  created_by: admin
{
  "metadata": {
    "name": "sensu-ansible-token",
    "namespace": "default",
    "created_by": "admin"
  }
}
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 
spec:
  id: ANSIBLE_TOKEN
  provider: env
{
  "spec": {
    "id": "ANSIBLE_TOKEN",
    "provider": "env"
  }
}
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 
type: Secret
{
  "type": "Secret"
}

Metadata attributes

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 
created_by: admin
{
  "created_by": "admin"
}
name
description Name for the secret that is used internally by Sensu.
required true
type String
example 
name: sensu-ansible-token
{
  "name": "sensu-ansible-token"
}
namespace
description Sensu RBAC namespace that the secret belongs to.
required true
type String
example 
namespace: default
{
  "namespace": "default"
}

Spec attributes

id
description Identifying key for the provider to use to retrieve the secret. For the Env secrets provider, the id is the environment variable. For the VaultProvider secrets provider, the id specifies the secrets engine path, the path to the secret within that secrets engine, and the field to retrieve within the secret.
required true
type String
example for Vault KV Secrets Engine v1 
id: secret/ansible#token
{
  "id": "secret/ansible#token"
}
example for Vault KV Secrets Engine v2 
id: secrets/sensu#ansible#token
{
  "id": "secrets/sensu#ansible#token"
}
provider
description Name of the provider with the secret.
required true
type String
example 
provider: vault
{
  "provider": "vault"
}