Vault Kubernetes Key Management parameters

Beta feature

Beta functionality is stable but possibly incomplete and subject to change. We strongly discourage using beta features in production deployments of Vault.

Configure the vault-kube-kms process to control how it exposes the KMS v2 gRPC endpoint to Kubernetes, connects to Vault, authenticates, selects a Transit key, and emits logs and metrics.

The vault-kube-kms process reads and validates the configuration at startup using command-line flags. If you start Vault Kubernetes with missing or invalid required parameters, the process exits with an error.

Connection parameters

--listen-address (string : "unix:///tmp/vault-kube-kms.socket")
Unix domain socket address where the vault-kube-kms process listens for requests from the Kubernetes API server. The kube-apiserver process must have filesystem access to the socket to communicate with the vault-kube-kms process.
Environment variable: VAULT_KUBE_KMS_LISTEN_ADDRESS

--vault-address (string : <required>)
HTTP(S) address where the vault-kube-kms process can reach your Vault server to authenticate and perform cryptographic operations with the Transit plugin.
Environment variable: VAULT_KUBE_KMS_VAULT_ADDRESS

--vault-namespace (string : "")
Vault namespace where you have the Transit plugin mounted. Leave vault-namespace unset if you have the plugin mounted in the root namespace. If you use namespaces with your Vault deployment, you must provide the plugin namespace with vault-namespace rather than including it in the mount path.
Environment variable: VAULT_KUBE_KMS_VAULT_NAMESPACE

--transit-mount (string: "transit")
Mount path to the Vault Transit plugin. The vault-kube-kms process uses transit-mount to craft Vault requests to encrypt and decrypt data encryption keys (DEKs).
Environment variable: VAULT_KUBE_KMS_TRANSIT_MOUNT

--transit-key (string: <required>) Name of an existing key in the Transit plugin that the vault-kube-kms process should use for crafting requests to Vault during DEK encryption and decryption. You must have a Vault policy configured that grants the vault-kube-kms process permission to access the named key. Environment variable: VAULT_KUBE_KMS_TRANSIT_KEY

--tls-ca-file (string: "")
Path to a CA certificate file that the vault-kube-kms process can use to validate the TLS certificate used by Vault. Leave tls-ca-file unset to use the system trust store.
Environment variable: VAULT_KUBE_KMS_TLS_CA_FILE

--tls-skip-verify (bool: false)
Tells the vault-kube-kms process to skip TLS certificate verification when connecting to Vault in non-production environments.
Environment variable: VAULT_KUBE_KMS_TLS_SKIP_VERIFY

--tls-sni (string: "") SNI (server name indication) used by the vault-kube-kms process when connecting to Vault via TLS. Environment variable: VAULT_KUBE_KMS_TLS_SNI

--vault-connection-timeout (string: "30s") Timeout for establishing a connection to Vault in duration notation (e.g., '15s', '30s'). Environment variable: VAULT_KUBE_KMS_VAULT_CONNECTION_TIMEOUT

Authentication parameters

The vault-kube-kms process currently supports AppRole authentication only.

AppRole parameters

You must include the following parameters for AppRole authentication:

--auth-mount (string: "approle") Mount path to the Vault auth method plugin that the vault-kube-kms process uses to authenticate to Vault. Required. Environment variable: VAULT_KUBE_KMS_AUTH_MOUNT

--approle-role-id (string: <required>) Non-sensitive AppRole role ID that the vault-kube-kms process uses to identify itself when authenticating to Vault. Environment variable: VAULT_KUBE_KMS_APPROLE_ROLE_ID

--approle-secret-id-path (string: <required>) Filesystem path to a file containing the sensitive AppRole secret ID associated with approle-role-id. Always protect the target file with appropriate filesystem permissions. The vault-kube-kms process reads the secret ID from approle-secret-id-path at startup. Environment variable: VAULT_KUBE_KMS_APPROLE_SECRET_ID_PATH

Logging, metrics, and telemetry parameters

--zap-log-level (string: "info") Log verbosity level. Can be one of 'debug', 'info', 'error', or 'panic', or specific integer values for custom verbosity levels. See the controller-runtime zap package documentation for more details.
- debug - Development mode logging with high-level details
- info - Production mode logging with general operational context (default)
- error - Log only errors and critical failures
- panic - Log only panic-level events
- 4 - Warning level logging
- 5 - Debug level logging
- 6 - Trace level logging (most verbose)

--metrics-port (int: 9090) TCP port local to the vault-kube-kms process that exposes a Prometheus-compatible /metrics endpoint. The endpoint binds to localhost. Set to 0 or a negative value to disable the metrics endpoint. Environment variable: VAULT_KUBE_KMS_METRICS_PORT

--disable-runtime-metrics (bool: false) Tells the vault-kube-kms process to disable Go runtime and process-level metrics in the /metrics endpoint. When set to false (default), runtime metrics including garbage collection statistics, goroutine counts, and memory usage are exposed. Environment variable: VAULT_KUBE_KMS_DISABLE_RUNTIME_METRICS

Minimal configuration example

Basic example ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: vault-kms-config
data:
  listen-address:         "/var/run/kms/vault-kms.sock"
  vault-address:          "https://vault.example.com:8200"
  transit-mount:          "transit"
  transit-key:            "kubernetes-etcd"
  approle-role-id:        "example-role-id"
  approle-secret-id-path: "/var/run/secrets/vault/secret-id"