Secrets providers

COMMERCIAL FEATURE: Access the Env and VaultProvider secrets provider datatypes 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 like usernames, passwords, and access keys in your Sensu configuration. With Sensu’s secrets management, you can obtain secrets from one or more external secrets providers, 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. Secrets are only transmitted over a transport layer security (TLS) websocket connection. Unencrypted connections must not transmit privileged information. For checks, hooks, and assets, you must enable mutual TLS (mTLS). Sensu will not transmit secrets to agents that do not use mTLS.

The Sensu Go commercial distribution includes a built-in secrets provider, Env, that exposes secrets from environment variables on your Sensu backend nodes. You can also use the secrets provider VaultProvider to authenticate via the HashiCorp Vault integration’s token auth method or TLS certificate auth method.

You can configure any number of VaultProvider secrets providers. However, you can only have a single Env secrets provider: the one that is included with the Sensu Go commercial distribution.

Secrets providers are cluster-wide resources and compatible with generic functions.

Secrets providers specification

NOTE: The attribute descriptions in this section use the VaultProvider datatype. The secrets providers examples section includes an example for the Env datatype.

Top-level attributes

type
description Top-level attribute that specifies the resource type. May be either Env (if you are using Sensu’s built-in secrets provider) or VaultProvider (if you are using HashiCorp Vault as the secrets provider).
required Required for secrets configuration in wrapped-json or yaml format.
type String
example
"type": "VaultProvider"
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"
metadata
description Top-level scope that contains the secrets provider name and created_by field. Namespace is not supported in the metadata because secrets providers are cluster-wide resources.
required true
type Map of key-value pairs
example
"metadata": {
  "name": "vault",
  "created_by": "admin"
}
spec
description Top-level map that includes secrets provider configuration spec attributes.
required Required for secrets configuration in wrapped-json or yaml format.
type Map of key-value pairs
example
"spec": {
  "client": {
    "address": "https://vaultserver.example.com:8200",
    "max_retries": 2,
    "rate_limiter": {
      "limit": 10.0,
      "burst": 100
    },
    "timeout": "20s",
    "tls": {
      "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem"
    },
    "token": "VAULT_TOKEN",
    "version": "v1"
  }
}

Metadata attributes

name
description Provider name used internally by Sensu.
required true
type String
example
"name": "vault"
created_by
description Username of the Sensu user who created the secrets provider or last updated the secrets provider. Sensu automatically populates the created_by field when the secrets provider is created or updated.
required false
type String
example
"created_by": "admin"

Spec attributes

client
description Map that includes secrets provider configuration client attributes.
required true
type Map of key-value pairs
example
"client": {
  "address": "https://vaultserver.example.com:8200",
  "max_retries": 2,
  "rate_limiter": {
    "limit": 10.0,
    "burst": 100
  },
  "timeout": "20s",
  "tls": {
    "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem"
  },
  "token": "VAULT_TOKEN",
  "version": "v1"
}  

Client attributes

address
description Vault server address.
required true
type String
example
"address": "https://vaultserver.example.com:8200"
max_retries
description Number of times to retry connecting to the vault provider.
required true
type Integer
default 2
example
"max_retries": 2
rate_limiter
description Maximum rate and burst limits for the secrets API.
required false
type Map of key-value pairs
example
"rate_limiter": {
  "limit": 10.0,
  "burst": 100
}
timeout
description Provider connection timeout (hard stop).
required false
type String
default 60s
example
"timeout": "20s"

tls
description TLS object. Vault only works with TLS configured. You may need to set up a CA cert if it is not already stored in your operating system’s trust store. To do this, set the TLS object and provide the ca_cert path. You may also need to set up client_cert, client_key, or cname.
required false
type Map of key-value pairs
example
"tls": {
  "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem",
  "client_cert": "/etc/ssl/certs/vault_cert.pem",
  "client_key": "/etc/ssl/certs/vault_key.pem",
  "cname": "vault_client.example.com"
}
token
description Vault token to use for authentication.
required true
type String
example
"token": "VAULT_TOKEN"
version
description HashiCorp Vault key/value store version.
required true
type String
example
"version": "v1"

Rate limiter attributes

limit
description Maximum number of secrets requests per second that can be transmitted to the backend with the secrets API.
required false
type Float
example
"limit": 10.0
burst
description Maximum amount of burst allowed in a rate interval for the secrets API.
required false
type Integer
example
"burst": 100

Secrets providers configuration

You can use the Secrets API to create, view, and manage your secrets providers configuration.

For example, to retrieve the list of secrets providers:

curl -X GET \
http://127.0.0.1:8080/api/enterprise/secrets/v1/providers \
-H "Authorization: Bearer $SENSU_ACCESS_TOKEN"

Secrets providers examples

VaultProvider example

The VaultProvider secrets provider is a vendor-specific implementation for HashiCorp Vault secrets management.

---
type: VaultProvider
api_version: secrets/v1
metadata:
  name: vault
spec:
  client:
    address: https://vaultserver.example.com:8200
    token: VAULT_TOKEN
    version: v1
    tls:
      ca_cert: "/etc/ssl/certs/vault_ca_cert.pem"
    max_retries: 2
    timeout: 20s
    rate_limiter:
      limit: 10
      burst: 100
{
  "type": "VaultProvider",
  "api_version": "secrets/v1",
  "metadata": {
    "name": "vault"
  },
  "spec": {
    "client": {
      "address": "https://vaultserver.example.com:8200",
      "token": "VAULT_TOKEN",
      "version": "v1",
      "tls": {
        "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem"
      },
      "max_retries": 2,
      "timeout": "20s",
      "rate_limiter": {
        "limit": 10.0,
        "burst": 100
      }
    }
  }
}

Env example

Sensu’s built-in Env secrets provider exposes secrets from backend environment variables. The Env secrets provider is automatically created with an empty spec when you start your Sensu backend.

Using the Env secrets provider may require you to synchronize environment variables in Sensu backend clusters. The Use secrets management guide demonstrates how to configure the Env secrets provider.

---
type: Env
api_version: secrets/v1
metadata:
  name: env
spec: {}
{
  "type": "Env",
  "api_version": "secrets/v1",
  "metadata": {
    "name": "env"
  },
  "spec": {}
}