Secrets providers reference

COMMERCIAL FEATURE: Access the Env and VaultProvider secrets provider datatypes 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 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 dynamic runtime 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 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.

VaultProvider secrets provider 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 secrets provider example

Sensu’s 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. Read Use secrets management to learn 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": {}
}

Secrets provider configuration

You can use the enterprise/secrets/v1 API endpoints to create, view, and manage your secrets provider 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: Key $SENSU_API_KEY"

Secrets provider specification

NOTE: The attribute descriptions in this section use the VaultProvider datatype. Review the Env secrets provider example for an example definition for the Env datatype.

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 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
{
  "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
      burst: 100
    timeout: 20s
    tls:
      ca_cert: "/etc/ssl/certs/vault_ca_cert.pem"
    token: VAULT_TOKEN
    version: v1
{
  "spec": {
    "client": {
      "address": "https://vaultserver.example.com:8200",
      "max_retries": 2,
      "rate_limiter": {
        "limit": 10,
        "burst": 100
      },
      "timeout": "20s",
      "tls": {
        "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem"
      },
      "token": "VAULT_TOKEN",
      "version": "v1"
    }
  }
}
type
description Top-level attribute that specifies the resource type. May be either Env (if you are using Sensu’s 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
{
  "type": "VaultProvider"
}

Metadata attributes

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
{
  "created_by": "admin"
}
name
description Provider name used internally by Sensu.
required true
type String
example 
name: vault
{
  "name": "vault"
}

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
    burst: 100
  timeout: 20s
  tls:
    ca_cert: "/etc/ssl/certs/vault_ca_cert.pem"
  token: VAULT_TOKEN
  version: v1
{
  "client": {
    "address": "https://vaultserver.example.com:8200",
    "max_retries": 2,
    "rate_limiter": {
      "limit": 10,
      "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
{
  "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
{
  "max_retries": 2
}
rate_limiter
description Maximum rate and burst limits for the enterprise/secrets/v1 API endpoint. Read rate_limiter attributes for more information.
required false
type Map of key-value pairs
example 
rate_limiter:
  limit: 10
  burst: 100
{
  "rate_limiter": {
    "limit": 10,
    "burst": 100
  }
}
timeout
description Provider connection timeout (hard stop).
required false
type String
default 60s
example 
timeout: 20s
{
  "timeout": "20s"
}

tls
description TLS object. Vault only works with TLS configured. You may need to set up a Certificate Authority (CA) certificate 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
{
  "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
{
  "token": "VAULT_TOKEN"
}
version
description HashiCorp Vault key/value store version.
required true
type String
allowed values v1 and v2
example 
version: v1
{
  "version": "v1"
}
Rate limiter attributes
burst
description Maximum amount of burst allowed in a rate interval for the enterprise/secrets/v1 API endpoint.
required false
type Integer
example 
burst: 100
{
  "burst": 100
}
limit
description Maximum number of secrets requests per second that can be transmitted to the backend with the enterprise/secrets/v1 API endpoint.
required false
type Float
example 
limit: 10.0
{
  "limit": 10.0
}