Secrets reference

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.

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.

Env provider example

This example shows a resource definition for a secret that uses Sensu’s Env secrets provider:

---
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"
  }
}

CyberArk Conjur example

Configure secrets that target CyberArk Conjur as shown in the following example:

---
type: Secret
api_version: secrets/v1
metadata:
  name: sensu-ansible
spec:
  id: Sensu/ansibleToken
  provider: cyberark

{
  "type": "Secret",
  "api_version": "secrets/v1",
  "metadata": {
    "name": "sensu-ansible"
  },
  "spec": {
    "id": "Sensu/ansibleToken",
    "provider": "cyberark"
  }
}

The id value for secrets that target CyberArk Conjur includes the id and variable values specified in the Conjur policy.

HashiCorp Vault example

Configure secrets that target 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: secrets/v1

{
  "api_version": "secrets/v1"
}

metadata:
  name: sensu-ansible-token
  namespace: default
  created_by: admin

{
  "metadata": {
    "name": "sensu-ansible-token",
    "namespace": "default",
    "created_by": "admin"
  }
}

spec:
  id: ANSIBLE_TOKEN
  provider: env

{
  "spec": {
    "id": "ANSIBLE_TOKEN",
    "provider": "env"
  }
}

type: Secret

{
  "type": "Secret"
}

Metadata attributes

created_by: admin

{
  "created_by": "admin"
}

name: sensu-ansible-token

{
  "name": "sensu-ansible-token"
}

namespace: default

{
  "namespace": "default"
}

Spec attributes

id: ANSIBLE_TOKEN

{
  "id": "ANSIBLE_TOKEN"
}

id: Sensu/ansibleToken

{
  "id": "Sensu/ansibleToken"
}

id: secret/ansible#token

{
  "id": "secret/ansible#token"
}

id: secrets/sensu#ansible#token

{
  "id": "secrets/sensu#ansible#token"
}

provider: vault

{
  "provider": "vault"
}