You are looking at the documentation of a prior release. To read the documentation of the latest release, please visit here.

New to KubeVault? Please start here.

Reconfigure VaultServer TLS/SSL

KubeVault supports reconfigure i.e. add, remove, update and rotation of TLS/SSL certificates for existing VaultServer via a VaultOpsRequest. This tutorial will show you how to use KubeVault to reconfigure TLS/SSL encryption.

Before You Begin

  • At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using kind.

  • Install cert-manger v1.0.0 or later to your cluster to manage your SSL/TLS certificates.

  • Now, install KubeVault cli on your workstation and KubeVault operator in your cluster following the steps here.

  • To keep things isolated, this tutorial uses a separate namespace called demo throughout this tutorial.

$ kubectl create ns demo
namespace/demo created

Note: YAML files used in this tutorial are stored in docs/examples/guides/vault-ops-request folder in GitHub repository kubevault/kubevault.

Add TLS to a VaultServer

Here, We are going to create a VaultServer without TLS and then reconfigure the VaultServer to use TLS.

Deploy VaultServer without TLS

In this section, we are going to deploy a VaultServer without TLS. In the next few sections we will reconfigure TLS using VaultOpsRequest CRD. Below is the YAML of the VaultServer CR that we are going to create,

apiVersion: kubevault.com/v1alpha2
kind: VaultServer
metadata:
  name: vault
  namespace: demo
spec:
  version: 1.10.3
  replicas: 3
  allowedSecretEngines:
    namespaces:
      from: All
    secretEngines:
      - gcp
  backend:
    raft:
      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: WipeOut

Let’s create the VaultServer CR we have shown above,

$ kubectl create -f https://github.com/kubevault/kubevault/raw/v2024.3.12/docs/examples/guides/vault-ops-request/vaultserver.yaml
vaultserver.kubevault.com/vault created

Now, wait until VaultServer has status Ready. i.e,

$ kubectl get vs -n demo
NAME    REPLICAS   VERSION   STATUS   AGE
vault   3          1.12.1    Ready    128m

Create Issuer/ ClusterIssuer

Now, We are going to create an example Issuer that will be used to enable SSL/TLS in VaultServer. Alternatively, you can follow this cert-manager tutorial to create your own Issuer.

  • Start off by generating a ca certificates using openssl.
$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=vault/O=kubevault"
Generating a RSA private key
................+++++
........................+++++
writing new private key to './ca.key'
-----
  • Now we are going to create a ca-secret using the certificate files that we have just generated.
$ kubectl create secret tls vault-ca --cert=ca.crt --key=ca.key --namespace=demo

secret/vault-ca created

Now, Let’s create an Issuer using the vault-ca secret that we have just created. The YAML file looks like this:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: issuer
  namespace: demo
spec:
  ca:
    secretName: vault-ca

Let’s apply the YAML file:

$ kubectl create -f https://github.com/kubevault/kubevault/raw/v2024.3.12/docs/examples/guides/vault-ops-request/issuer.yaml
issuer.cert-manager.io/issuer created

Create VaultOpsRequest

In order to add TLS to the VaultServer, we have to create a VaultOpsRequest CRO with our created issuer. Below is the YAML of the VaultOpsRequest CRO that we are going to create,

apiVersion: ops.kubevault.com/v1alpha1
kind: VaultOpsRequest
metadata:
  name: vault-ops-add-tls
  namespace: demo
spec:
  type: ReconfigureTLS
  vaultRef:
    name: vault
  tls:
    issuerRef:
      name: issuer
      kind: Issuer
      apiGroup: "cert-manager.io"
    certificates:
      - alias: client
        subject:
          organizations:
            - appscode
          organizationalUnits:
            - client

Here,

  • spec.vaultRef.name specifies that we are performing reconfigure TLS operation on vault VaultServer.
  • spec.type specifies that we are performing ReconfigureTLS on our VaultServer.
  • spec.tls.issuerRef specifies the issuer name, kind and api group.
  • spec.tls.certificates specifies the certificates.

Let’s create the VaultOpsRequest CR we have shown above,

$ kubectl apply -f https://github.com/kubevault/kubevault/raw/v2024.3.12/docs/examples/guides/vault-ops-request/vault-ops-add-tls.yaml
vaultopsrequest.ops.kubevault.com/vault-ops-add-tls created

Verify TLS Enabled Successfully

Let’s wait for VaultOpsRequest to be Successful. Run the following command to watch VaultOpsRequest CRO,

$ kubectl get vaultopsrequest -n demo
Every 2.0s: kubectl get vaultopsrequest -n demo
NAME               TYPE             STATUS        AGE
vault-ops-add-tls  ReconfigureTLS   Successful    91s

Rotate Certificate

Now we are going to rotate the certificate of this VaultServer. First let’s check the current expiration date of the certificate.

$ kubectl exec -it -n demo vault-0 -- bin/sh
/ # cd etc/vault/tls/server
/etc/vault/tls/server # cat tls.crt
-----BEGIN CERTIFICATE-----
MIID2DCCAsCgAwIBAgIQL1rqn4OHpvchiFRI3DPXIjANBgkqhkiG9w0BAQsFADAk
...
XJRRwl5psqcyp5ZJI1ar5JP1JCGQa3QTArwstw==
-----END CERTIFICATE-----

Copy & paste the certificate in any certificates decoding tool like certlogic & check it’s expiry date.

Create VaultOpsRequest

Now we are going to increase it using a VaultOpsRequest. Below is the yaml of the ops request that we are going to create,

apiVersion: ops.kubevault.com/v1alpha1
kind: VaultOpsRequest
metadata:
  name: vault-ops-rotate
  namespace: demo
spec:
  type: ReconfigureTLS
  vaultRef:
    name: vault
  tls:
    rotateCertificates: true

Here,

  • spec.vaultRef.name specifies that we are performing reconfigure TLS operation on vault VaultServer.
  • spec.type specifies that we are performing ReconfigureTLS on our VaultServer.
  • spec.tls.rotateCertificates specifies that we want to rotate the certificate of this VaultServer.

Let’s create the VaultOpsRequest CR we have shown above,

$ kubectl apply -f https://github.com/kubevault/kubevault/raw/v2024.3.12/docs/examples/guides/vault-ops-request/vault-ops-rotate.yaml
vaultopsrequest.ops.kubevault.com/vault-ops-rotate created

Verify Certificate Rotated Successfully

Let’s wait for VaultOpsRequest to be Successful. Run the following command to watch VaultOpsRequest CRO,

$ kubectl get vaultopsrequest -n demo
Every 2.0s: kubectl get vaultopsrequest -n demo
NAME                TYPE             STATUS        AGE
vault-ops-rotate    ReconfigureTLS   Successful    112

Now, let’s check the expiration date of the certificate again, it should be updated.

$ kubectl exec -it -n demo vault-0 -- bin/sh
/ # cd etc/vault/tls/server
/etc/vault/tls/server # cat tls.crt
-----BEGIN CERTIFICATE-----
MIID2DCCAsCgAwIBAgIQL1rqn4OHpvchiFRI3DPXIjANBgkqhkiG9w0BAQsFADAk
...
XJRRwl5psqcyp5ZJI1ar5JP1JCGQa3QTArwstw==
-----END CERTIFICATE-----

Change Issuer/ClusterIssuer

Now, we are going to change the issuer of this VaultServer.

  • Let’s create a new ca certificate and key using a different subject CN=ca-updated,O=kubevault-updated.
$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=ca-updated/O=kubevault-updated"
Generating a RSA private key
..............................................................+++++
......................................................................................+++++
writing new private key to './ca.key'
-----
  • Now we are going to create a new ca-secret using the certificate files that we have just generated.
$ kubectl create secret tls vault-new-ca \
     --cert=ca.crt \
     --key=ca.key \
     --namespace=demo
secret/vault-new-ca created

Now, Let’s create a new Issuer using the vault-new-ca secret that we have just created. The YAML file looks like this:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: new-issuer
  namespace: demo
spec:
  ca:
    secretName: vault-new-ca

Let’s apply the YAML file:

$ kubectl create -f https://github.com/kubevault/kubevault/raw/v2024.3.12/docs/examples/guides/vault-ops-request/new-issuer.yaml
issuer.cert-manager.io/new-issuer created

Create VaultOpsRequest

In order to use the new issuer to issue new certificates, we have to create a VaultOpsRequest CRO with the newly created issuer. Below is the YAML of the VaultOpsRequest CRO that we are going to create,

apiVersion: ops.kubevault.com/v1alpha1
kind: VaultOpsRequest
metadata:
  name: vault-ops-change-issuer
  namespace: demo
spec:
  type: ReconfigureTLS
  vaultRef:
    name: vault
  tls:
    issuerRef:
      name: new-issuer
      kind: Issuer
      apiGroup: "cert-manager.io"

Here,

  • spec.vaultRef.name specifies that we are performing reconfigure TLS operation on vault VaultServer.
  • spec.type specifies that we are performing ReconfigureTLS on our VaultServer.
  • spec.tls.issuerRef specifies the issuer name, kind and api group.

Let’s create the VaultOpsRequest CR we have shown above,

$ kubectl apply -f https://github.com/kubevault/kubevault/raw/v2024.3.12/docs/examples/guides/vault-ops-request/vault-ops-change-issuer.yaml
vaultopsrequest.ops.kubevault.com/vault-ops-change-issuer created

Verify Issuer is changed successfully

Let’s wait for VaultOpsRequest to be Successful. Run the following command to watch VaultOpsRequest CRO,

$ kubectl get vaultopsrequest -n demo
Every 2.0s: kubectl get vaultopsrequest -n demo
NAME                       TYPE             STATUS        AGE
vault-ops-change-issuer    ReconfigureTLS   Successful    105s

Remove TLS from the VaultServer

Now, we are going to remove TLS from this VaultServer using a VaultOpsRequest.

Create VaultOpsRequest

Below is the YAML of the VaultOpsRequest CRO that we are going to create,

apiVersion: ops.kubevault.com/v1alpha1
kind: VaultOpsRequest
metadata:
  name: vault-ops-remove
  namespace: demo
spec:
  type: ReconfigureTLS
  vaultRef:
    name: vault
  tls:
    remove: true

Here,

  • spec.vaultRef.name specifies that we are performing reconfigure TLS operation on vault VaultServer.
  • spec.type specifies that we are performing ReconfigureTLS on our VaultServer.
  • spec.tls.remove specifies that we want to remove tls from this VaultServer.

Let’s create the VaultOpsRequest CR we have shown above,

$ kubectl apply -f https://github.com/kubevault/kubevault/raw/v2024.3.12/docs/examples/guides/vault-ops-request/vault-ops-remove.yaml
vaultopsrequest.ops.kubeavult.com/vault-ops-remove created

Verify TLS Removed Successfully

Let’s wait for VaultOpsRequest to be Successful. Run the following command to watch VaultOpsRequest CRO,

$ kubectl get vaultopsrequest -n demo
Every 2.0s: kubectl get vaultopsrequest -n demo
NAME               TYPE             STATUS        AGE
vault-ops-remove   ReconfigureTLS   Successful    105s

Cleaning up

To clean up the Kubernetes resources created by this tutorial, run:

kubectl delete vaultserver -n demo vault
kubectl delete issuer -n demo issuer new-issuer
kubectl delete vaultopsrequest vault-ops-add-tls vault-ops-remove vault-ops-rotate vault-ops-change-issuer
kubectl delete ns demo