Configuration

Authentication

Currently, the following authentication methods are supported

• Token
• Kubernetes
• UserPass
• AppRole
• JWT/OIDC
• Certificate

Configuration of auth methods is done using the environment variables listed below.

# Path defined for the authentication route, ex: auth/custom-auth-path/...
#  if not set, will default to the associated auth method, ex: auth/userpass/.. or auth/kubernetes/..
VAULT_AUTH_MOUNT = "custom-auth-path"

# Vault token for vault access
VAULT_TOKEN = "SiQOECxwSDCeQt1r0n5kqQCr"
# path to file containing vault token
VAULT_TOKEN_PATH = "/path/to/vault/token"

# user and password for userpass authentication
VAULT_USER = "vault-kms-provider"
VAULT_PASSWORD = "some-password"
# path to file containing vault password
VAULT_PASSWORD_PATH = "/path/to/vault/password"

# path to mounted JWT for kubernetes auth
VAULT_KUBERNETES_JWT_PATH = "/path/to/vault.jwt"
# jwt for kubernetes auth
VAULT_KUBERNETES_JWT = "jwt"
# role for kubernetes auth 
VAULT_KUBERNETES_ROLE = "vault-kms-provider"

# role_id and secret_id for approle authentication
VAULT_ROLE_ID = "role"
VAULT_SECRET_ID = "secret"
# path to file containing secret id
VAULT_SECRET_ID_PATH = "/path/to/secret/id"

# jwt for jwt auth
VAULT_JWT = "jwt"
# path to mounted jwt for jwt auth
VAULT_JWT_PATH = "/path/to/jwt"
# role for jwt, optional
VAULT_JWT_ROLE = "vault-kms-provider"

# name of the trusted certificate created in vault for authentication
VAULT_CERTIFICATE_NAME = "vault-kms-provider"
# path to client cert and key for certificate authentication
VAULT_CLIENT_CERT = "/path/to/client/public.crt"
VAULT_CLIENT_KEY = "/path/to/client/private.key"

Environment variables can be configured using the env property in the values.yaml, ex:

env:
  - name: VAULT_TOKEN
    valueFrom:
      secretKeyRef:
        name: vault-token-secret
        key: token

The envFrom property is also configurable in the values.yaml file, allowing configMaps, etc to be added. ex:

envFrom:
  - configMapRef:
    name: my-custom-config-map

Configure Kubernetes

Create an encryption configuration for the Kubernetes api server

./encryption-configuration.yaml

apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
  - resources:
      - secrets
    providers:
      - kms:
          apiVersion: v2
          name: vault-kms-provider
          endpoint: unix:///mnt/vault-kms-provider.sock
          timeout: 3s
      - identity: {}

Point the api server to your encryption configuration

/etc/kubernetes/manifests/kube-apiserver.yaml

# add these commands to your Kubernetes api server configuration
spec:
  containers:
    - command:
        - kube-apiserver
        # Point to your encryption file
        - --encryption-provider-config="/path/to/your/encryption-configuration.yaml"

This is done in differently in some flavors of kubernetes, if yours is different, consult the documentation of your Kubernetes distro for instructions on how to point Kubernetes to your configuration file.

Plugin

Helm values

When deploying via helm, it is important to ensure that the vault.address is set correctly.

helm install vault-kms-provider --set "vault.address=https://vault.default.svc.cluster.local:8200"

Depending on the type of authentication you require you may want to disable the service account.

helm install vault-kms-provider --set "serviceAccount.create=false"

Environment variables

Below are some general environment variables and their defaults for configuration of the KMS provider

# Url of the vault service
VAULT_ADDRESS = "https://vault.vault.svc.cluster.local:8200"

# The endpoint that the health checks will listen on
HEALTH_ENDPOINT = "0.0.0.0:8080"

# Path to the socket used for communication with the Kubernetes API server. Can be either abstract (@path/to/abstract.sock) or file path.
# Abstract socket paths must be prefixed with the "@" symbol
SOCKET_PATH = "./sockets/vault-kms-provider.sock"

# The level of permissions granted to the socket (does not apply to abstract sockets)
SOCKET_PERMISSIONS = "666"

# The string identifier used to store the encryption keys in the vault transit gateway
VAULT_TRANSIT_KEY = "vault-kms-provider"

# path defined for the transit gateway, ex: auth/transit/... or auth/transit-path/...
VAULT_TRANSIT_MOUNT = "transit"

Set up TLS communication

Add Vault's CA file(s) to the KMS provider

To allow TLS encrypted communication with vault, Vault's CA (certificate authority) file(s) need to be installed in the KMS provider. This can be set in the values.yaml for the helm chart.

vault:
  ca:
    # full path to a specific CA file
    file: "/path/to/ca.crt"
    # full path to a directory containing CA file(s)
    directory: "/path/to/ca/directory"

If you have a single CA file for vault, you can set a specific path to it.

helm install vault-kms-provider --set "vault.ca.file=/path/to/ca.crt"

If you have more than one file, or would rather just point to a directory, you can also specify a directory path. All certificates in the directory path will be installed in the KMS provider.

helm install vault-kms-provider --set "vault.ca.directory=/path/to/directory"

Mount Vault's CA files into the KMS provider

In order for Vault's CA files to be installed, they must be present in the container, we can mount the CA file(s) by defining volumes and volumeMounts in our values.yaml.

The following are examples of how to mount Vault CA file(s) into the KMS provider.

Secrets

volumes:
  # name of the volume, should match the volumeMount name
  - name: vault-ca-certificate
    secret:
      # The name of the secret that contains the Vault CA certificate(s)
      secretName: vault-ca-certs

volumeMounts:
  # Match with volume name
  - name: vault-ca-certificate
    # path where the files will be in the KMS provider
    mountPath: /etc/ssl/certs

Volumes

volumes:
  # name of the volume, should match the volumeMount name
  - name: vault-ca-certificates
    hostPath:
      # Path to the directory where the Vault CA certificate(s) are located on the host machine
      path: /path/to/host/certificates
      type: Directory

volumeMounts:
  # Match with volume name
  - name: vault-ca-certificate
    # path where the files will be in the KMS provider
    mountPath: /etc/ssl/certs

Set up Vault

Encryption

Enable the transit gateway in Vault for encryption/decryption of data for Kubernetes.

vault secrets enable transit

Create a policy granting the permissions to the KMS provider to encrypt/decrypt data.

./transit.hcl

path "/transit/decrypt/vault-kms-provider" {
  capabilities = ["update", "create"]
}
path "/transit/encrypt/vault-kms-provider" {
  capabilities = ["update", "create"]
}
path "/transit/keys/vault-kms-provider" {
  capabilities = ["read"]
}

Add the policy to vault

vault policy write vault-kms-provider transit.hcl

Authentication

Enable authentication via kubernetes

vault auth enable kubernetes

Set the host URL to the kubernetes API

vault write auth/kubernetes/config kubernetes_host="https://kubernetes.default.svc/"

Create a role for the KMS provider's service account so that it can authenticate with vault.

vault write auth/kubernetes/role/vault-kms-provider \
    bound_service_account_names=vault-kms-provider \
    bound_service_account_namespaces=default \
    audience=vault \
    token_policies=vault-kms-provider \
    ttl=1h

With vault configured you should be able to deploy the vault-kms-provider to kubernetes without error.