New to KubeVault? Please start here.

VaultServer

What is VaultServer

A VaultServer is a Kubernetes CustomResourceDefinition (CRD) which is used to deploy a HashiCorp Vault server on Kubernetes clusters in a Kubernetes native way.

When a VaultServer is created, the KubeVault operator will deploy a Vault server and create necessary Kubernetes resources required for the Vault server.

VaultServer CRD Specification

Like any official Kubernetes resource, a VaultServer object has TypeMeta, ObjectMeta, Spec and Status sections.

A sample VaultServer object is shown below:

apiVersion: kubevault.com/v1alpha1
kind: VaultServer
metadata:
  name: vault
  namespace: demo
spec:
  tls:
    issuerRef:
      apiGroup: "cert-manager.io"
      kind: Issuer
      name: vault-issuer
  allowedSecretEngines:
    namespaces:
      from: All
    secretEngines:
      - mysql
  version: 1.8.2
  replicas: 3
  backend:
    raft:
      path: "/vault/data"
      storage:
        storageClassName: "standard"
        resources:
          requests:
            storage: 1Gi
  unsealer:
    secretShares: 5
    secretThreshold: 3
    mode:
      kubernetesSecret:
        secretName: vault-keys
  monitor:
    agent: prometheus.io
    prometheus:
      exporter:
        resources: {}
  terminationPolicy: DoNotTerminate

Here, we are going to describe the various sections of the VaultServer crd.

VaultServer Spec

VaultServer Spec contains the configuration about how to deploy Vault in the Kubernetes cluster. It also covers automate unsealing of Vault.

The spec section has following parts:

spec.replicas

spec.replicas specifies the number of Vault nodes to deploy. It has to be a positive number.

spec:
  replicas: 3 # 3 vault server will be deployed in Kubernetes cluster

spec.version

Specifies the name of the VaultServerVersion CRD. This CRD holds the image name and version of the Vault, Unsealer, and Exporter. To know more information about VaultServerVersion CRD see here.

spec:
  version: "1.7.2"

spec.tls

spec.tls is an optional field that specifies the TLS policy of Vault nodes. If this is not specified, the KubeVault operator will run in insecure mode.

spec:
  tls:
    issuerRef:
      apiGroup: "cert-manager.io"
      kind: Issuer
      name: vault-issuer

The server certificate must allow the following wildcard domains:

• localhost

• *.<namespace>.pod

• <vaultServer-name>.<namespace>.svc

  The server certificate must allow the following IP:

• 127.0.0.1

spec.configSecret

spec.configSecret is an optional field that allows the user to provide extra configuration for Vault. This field accepts a VolumeSource. You can use any Kubernetes supported volume source such as configMap, secret, azureDisk, etc.

Please note that the config file name must be vault.hcl to work.

spec:
  configSecret:
    <type of volume>: # for example `configSecret`
      name: <name of volume>

spec.dataSources

spec.dataSources is an optional field that allows the user to provide a list of VolumeSources (i.e. secrets, configmaps, etc.) which will be mounted into the VaultServer pods. These volumes will be mounted into /etc/vault/data/<name> directory. The first data will be named as data-0, the second one will be named as data-1 and so on.

spec:
  dataSources:
  - secret:  # mounted on /etc/vault/data/data-0
      secretName: custom-cert
  - configMap: # mounted on /etc/vault/data/data-1
      name: special-config

spec.monitor

spec.monitor is an optional field that is used to monitor the vaultserver instances.

monitor:
    agent: prometheus.io
    prometheus:
      exporter:
        resources: {}

spec.terminationPolicy

spec.terminationPolicy is an optional field that gives flexibility whether to nullify(reject) the delete operation of VaultServer crd or which resources KubeVault operator should keep or delete when you delete VaultServer crd. KubeVault provides following four termination policies:

• DoNotTerminate
• Halt
• Delete (Default)
• WipeOut

When, terminationPolicy is DoNotTerminate, KubeVault takes advantage of ValidationWebhook feature in Kubernetes 1.9.0 or later clusters to provide safety from accidental deletion of VaultServer. If admission webhook is enabled, KubeVault prevents users from deleting the VaultServer as long as the spec.terminationPolicy is set to DoNotTerminate.

spec.backend

spec.backend is a required field that specifies the Vault backend storage configuration. KubeVault operator generates storage configuration according to this spec.backend.

spec:
  backend:
    ...

List of supported backends:

• Azure
• Consul
• DynamoDB
• Etcd
• GCS
• In Memory
• MySQL
• PosgreSQL
• AWS S3
• Swift
• Filesystem
• Raft

spec.unsealer

spec.unsealer is an optional field that specifies Unsealer configuration. Unsealer handles automatic initializing and unsealing of Vault. See here for Unsealer documentation.

spec:
  unsealer:
    secretShares: <num_of_secret_shares>
    secretThresold: <num_of_secret_threshold>
    retryPeriodSeconds: <retry_period>
    overwriteExisting: <true/false>
    mode:
      ...

spec.serviceTemplates

You can also provide a list of templates for the services created by KubeVault operator for VaultServer through spec.serviceTemplates. This will allow you to set the type and other properties of the services. spec.serviceTemplates is an optional field.

spec:
  serviceTemplates:
    - alias: stats
      spec:
        type: ClusterIP

VaultServer allows following fields to be set in spec.serviceTemplates:

• metadata:
  • annotations (set as annotations on Vault service)
• spec:
  • type
  • ports
  • clusterIP
  • externalIPs
  • loadBalancerIP
  • loadBalancerSourceRanges
  • externalTrafficPolicy
  • healthCheckNodePort
  • sessionAffinityConfig

spec.podTemplate

VaultServer allows providing a template for Vault pod through spec.podTemplate. KubeVault operator will pass the information provided in spec.podTemplate to the Deployment created for Vault. spec.podTemplate is an optional field.

spec:
  podTemplate:
    spec:
      resources:
        requests:
          memory: "64Mi"
          cpu: "250m"
        limits:
          memory: "128Mi"
          cpu: "500m"

VaultServer accepts the following fields to set in spec.podTemplate:

• metadata:
  • annotations (set as annotations on Vault pods)
• controller:
  • annotations (set as annotations on Vault statefulset)
• spec:
  • resources
  • imagePullSecrets
  • nodeSelector
  • affinity
  • schedulerName
  • tolerations
  • priorityClassName
  • priority
  • securityContext

You can find the full list of fields here. Some of the fields of spec.podTemplate are described below:

spec.podTemplate.spec.imagePullSecret

spec.podTemplate.spec.imagePullSecrets is an optional field that points to secrets to be used for pulling docker images if you are using a private docker registry.

spec.podTemplate.spec.nodeSelector

spec.podTemplate.spec.nodeSelector is an optional field that specifies a map of key-value pairs. For the pod to be eligible to run on a node, the node must have each of the indicated key-value pairs as labels (it can have additional labels as well). To learn more, see here .

spec.podTemplate.spec.resources

spec.podTemplate.spec.resources is an optional field. This can be used to request compute resources required by Vault pods. To learn more, visit here.

spec.authMethods

spec.authMethods is an optional field that specifies the list of auth methods to enable in Vault.

spec:
  authMethods:
    - type: kubernetes
      path: k8s
    - type: aws
      path: aws

spec.authMethods has following fields:

spec.authMethods[].type

spec.authMethods[].type is a required field that specifies the name of the authentication method type.

spec.authMethods[].path

spec.authMethods[].path is a required field that specifies the path where to enable the auth method.

spec.authMethods[].description

spec.authMethods[].description is an optional field that specifies a human-friendly description of the auth method.

spec.authMethods[].pluginName

spec.authMethods[].pluginName is an optional field that specifies the name of the auth plugin to use based on the name in the plugin catalog.

spec.authMethods[].local

spec.authMethods[].local is an optional field that specifies if the auth method is local only. Local auth methods are not replicated nor (if a secondary) removed by replication.

spec.authMethods[].config

spec.authMethods[].config is an optional field that specifies configuration options for auth method.

spec.authMethods[].config has following fields:

• defaultLeaseTTL : Optional. Specifies the default lease duration.

• maxLeaseTTL : Optional. Specifies the maximum lease duration.

• pluginName : Optional. Specifies the name of the plugin in the plugin catalog to use.

• auditNonHMACRequestKeys : Optional. Specifies the list of keys that will not be HMAC’d by audit devices in the request data object.

• auditNonHMACResponseKeys: Optional. Specifies the list of keys that will not be HMAC’d by audit devices in the response data object.

• listingVisibility: Optional. Specifies whether to show this is mount in the UI-specific listing endpoint.

• passthroughRequestHeaders: Optional. Specifies a list of headers to whitelist and pass from the request to the backend.

VaultServer Status

VaultServer Status shows the status of a Vault deployment. The status of the Vault is monitored and updated by the KubeVault operator.

status:
  phase: <phase>

• phase: Indicates the phase Vault is currently in. Possible values of status.phase:

  • Initializing
  • Sealed
  • Unsealing
  • Critical
  • NotReady
  • Ready

• authMethodStatus : Indicates the status of the auth methods specified in spec.authMethods. It has the following fields:

  • type: Specifies the name of the authentication method type

  • path: Specifies the path in which the auth method is enabled.

  • status: Specifies whether the auth method is enabled or not.

  • reason: Specifies the reason why failed to enable the auth method.