Installing and upgrading the Vault Secrets Operator

Prerequisites

A Kubernetes cluster running 1.23+
Helm 3.7+
[Optional] Kustomize 4.5.7+

Installation using Helm

Install Helm before beginning.

The Helm chart is the recommended way of installing and configuring the Vault Secrets Operator.

To install a new instance of the Vault Secrets Operator, first add the HashiCorp Helm repository and ensure you have access to the chart:

$ helm repo add hashicorp https://helm.releases.hashicorp.com
"hashicorp" has been added to your repositories

$ helm search repo hashicorp/vault-secrets-operator
NAME            CHART VERSION   APP VERSION DESCRIPTION
hashicorp/vault-secrets-operator    0.9.1           0.9.1       Official HashiCorp Vault Secrets Operator Chart

Then install the Operator:

$ helm install --version 0.9.1 --create-namespace --namespace vault-secrets-operator vault-secrets-operator hashicorp/vault-secrets-operator

Updating CRDs when using Helm

Important

As of VSO 0.8.0, VSO will automatically update its CRDs. The manual upgrade step Updating CRDs below is no longer required before upgrading to VSO 0.8.0+.

Upgrading using Helm

You can upgrade an existing installation with the helm upgrade command. Please always run Helm with the --dry-run option before any install or upgrade to verify changes.

Update the hashicorp Helm repo:

$ helm repo update hashicorp
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "hashicorp" chart repository
Update Complete. ⎈Happy Helming!⎈

To upgrade your VSO release, replace <TARGET_VSO_VERSION> with the VSO version you are upgrading to:

$ helm upgrade --version <TARGET_VSO_VERSION> --namespace vault-secrets-operator vault-secrets-operator hashicorp/vault-secrets-operator

For example, if you are upgrading to VSO 0.9.1:

$ helm upgrade --version 0.9.1 --namespace vault-secrets-operator vault-secrets-operator hashicorp/vault-secrets-operator

The VSO Helm chart will automatically upgrade the CRDs to match the VSO version being deployed. There should be no need to manually update the CRDs prior to upgrading VSO using Helm.

Chart values

Refer to the Helm chart overview for a full list of supported chart values.

Installation using Kustomize

You can install and update your installation using kustomize which allows you to extend the config/ path of the VSO repository using Kustomize primitives.

To install using Kustomize, download and untar/unzip the latest release from the Releases Page.

$ wget -q https://github.com/hashicorp/vault-secrets-operator/archive/refs/tags/v0.9.1.tar.gz
$ tar -zxf v0.9.1.tar.gz
$ cd vault-secrets-operator-0.9.1/

Next install using kustomize build:

$ kustomize build config/default | kubectl apply -f -
namespace/vault-secrets-operator-system created
customresourcedefinition.apiextensions.k8s.io/hcpauths.secrets.hashicorp.com created
customresourcedefinition.apiextensions.k8s.io/hcpvaultsecretsapps.secrets.hashicorp.com created
customresourcedefinition.apiextensions.k8s.io/vaultauths.secrets.hashicorp.com created
customresourcedefinition.apiextensions.k8s.io/vaultconnections.secrets.hashicorp.com created
customresourcedefinition.apiextensions.k8s.io/vaultdynamicsecrets.secrets.hashicorp.com created
customresourcedefinition.apiextensions.k8s.io/vaultpkisecrets.secrets.hashicorp.com created
customresourcedefinition.apiextensions.k8s.io/vaultstaticsecrets.secrets.hashicorp.com created
serviceaccount/vault-secrets-operator-controller-manager created
role.rbac.authorization.k8s.io/vault-secrets-operator-leader-election-role created
clusterrole.rbac.authorization.k8s.io/vault-secrets-operator-manager-role created
clusterrole.rbac.authorization.k8s.io/vault-secrets-operator-metrics-reader created
clusterrole.rbac.authorization.k8s.io/vault-secrets-operator-proxy-role created
rolebinding.rbac.authorization.k8s.io/vault-secrets-operator-leader-election-rolebinding created
clusterrolebinding.rbac.authorization.k8s.io/vault-secrets-operator-manager-rolebinding created
clusterrolebinding.rbac.authorization.k8s.io/vault-secrets-operator-proxy-rolebinding created
configmap/vault-secrets-operator-manager-config created
service/vault-secrets-operator-controller-manager-metrics-service created
deployment.apps/vault-secrets-operator-controller-manager created

Confirm the operator has been installed by examining the pods:

$ kubectl get pods -n vault-secrets-operator-system
NAMESPACE                       NAME                                                         READY   STATUS    RESTARTS   AGE
vault-secrets-operator-system   vault-secrets-operator-controller-manager-56754d5496-cq69s   2/2     Running   0          1m17s

Kustomize does not support all features of the Helm chart

Notably it will not deploy default VaultAuthMethod, VaultConnection or Transit related resources. Kustomize also does not support pre-delete hooks that the Helm chart uses to cleanup resources and remove finalizers on the uninstall path. Please see config/samples or config/samples in the downloaded release artifacts for additional resources.

Upgrade using Kustomize

Upgrading using Kustomize is similar to installation: simply download the new release from github and follow the same steps as outlined in Installation using Kustomize. No additional steps are required to update the CRDs.

Legacy notes

The following notes provide guidance for installing/upgrading older versions of VSO.

Updating CRDs when using Helm prior to VSO 0.8.0

This step can be skipped if you are upgrading to VSO 0.8.0 or later.

Helm does not automatically update CRDs

You must update all CRDs manually before upgrading VSO to a version prior to 0.8.0.

You must update the CRDs for VSO manually before you upgrade the operator when the operator is managed by Helm.

Any kubectl warnings related to last-applied-configuration should be safe to ignore.

To update the VSO CRDs, replace <TARGET_VSO_VERSION> with the VSO version you are upgrading to:

$ helm show crds --version <TARGET_VSO_VERSION> hashicorp/vault-secrets-operator | kubectl apply -f -

For example, if you are upgrading to VSO 0.7.1:

$ helm show crds --version 0.7.1 hashicorp/vault-secrets-operator | kubectl apply -f -

customresourcedefinition.apiextensions.k8s.io/hcpauths.secrets.hashicorp.com created
customresourcedefinition.apiextensions.k8s.io/hcpvaultsecretsapps.secrets.hashicorp.com created
Warning: resource customresourcedefinitions/vaultauths.secrets.hashicorp.com is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
customresourcedefinition.apiextensions.k8s.io/vaultauths.secrets.hashicorp.com configured
Warning: resource customresourcedefinitions/vaultconnections.secrets.hashicorp.com is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
customresourcedefinition.apiextensions.k8s.io/vaultconnections.secrets.hashicorp.com configured
Warning: resource customresourcedefinitions/vaultdynamicsecrets.secrets.hashicorp.com is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
customresourcedefinition.apiextensions.k8s.io/vaultdynamicsecrets.secrets.hashicorp.com configured
Warning: resource customresourcedefinitions/vaultpkisecrets.secrets.hashicorp.com is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
customresourcedefinition.apiextensions.k8s.io/vaultpkisecrets.secrets.hashicorp.com configured
Warning: resource customresourcedefinitions/vaultstaticsecrets.secrets.hashicorp.com is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
customresourcedefinition.apiextensions.k8s.io/vaultstaticsecrets.secrets.hashicorp.com configured