How to deploy Open Vault Agent Injector

Open Vault Agent Injector consists in a Webhook Admission Server, registered in the Kubernetes Mutating Admission Webhook Controller, that will mutate resources depending on defined criteriae.

Prerequisites

Note: Open Vault Agent Injector chart requires Helm 3

Installation:

Runtime:

Vault Server installation

Note: this step is optional if you already have a running Vault server. This section helps you setup a test Vault server with ready to use configuration.

We will install a test Vault server in Kubernetes cluster but an external, out of cluster, Vault server can also be used. Note that we will install Vault server in dev mode below, do not use this setup in production.

Using HashiCorp's Vault Helm chart:

git clone https://github.com/hashicorp/vault-helm.git
cd vault-helm
git checkout v0.9.1
helm install vault . --set injector.enabled=false --set server.dev.enabled=true --set ui.enabled=true --set ui.serviceType="NodePort"

Then init Vault server with our test config:

# Check status
kubectl exec -it vault-0 -- vault status
kubectl logs vault-0

# Set up needed auth methods, secrets engines, policies, roles and secrets
cd open-vault-agent-injector/test/vault
./init-test-vault-server.sh

Open Vault Agent Injector image

Note: if you don't intend to perform some tests with the image you can skip this section.

Pulling the image from Docker Hub

Official Docker images are published on Docker Hub for each Open Vault Agent Injector release. Provided Helm chart will pull the image automatically if needed.

For manual pull of a specific tag:

docker pull asaintsever/open-vault-agent-injector:<tag>
Building the image

A Dockerfile is also provided to both compile Open Vault Agent Injector and build the image locally if you prefer.

Just run following command:

make image

Note: if you have Go installed on your machine, you can use make image-from-build instead. You need Golang 1.14 or higher.

Webhook certificates

By default, the webhook certificates (CA and leaf) and private key will be generated as part of the installation. Look at the mutatingwebhook.cert.* parameters in configuration for default values.

You can also provide your own certificates and private key by following those steps:

  1. set mutatingwebhook.cert.generated parameter to false
  2. as an option, modify the name of the Kubernetes Secret that will host the certificates and private key (mutatingwebhook.cert.secretName parameter)
  3. generate the CA, leaf certificate and private key (using OpenSSL for e.g.) and save them as PEM-encoded files
  4. from those files, create a new Kubernetes Secret using default name or the one you set in step 2:
kubectl create secret generic <secret name> \
                --from-file=ca.crt=<PATH>/<CA file, PEM-encoded> \
                --from-file=tls.crt=<PATH>/<Cert file, PEM-encoded> \
                --from-file=tls.key=<PATH>/<PrivKey file, PEM-encoded>
                -n <Namespace where Open Vault Agent Injector is installed>

Installing the Chart

Several options to install the chart:

Depending on what you chose, define a CHART_LOCATION env var as follows:

export CHART_LOCATION=./open-vault-agent-injector-<x.y.z>.tgz

Note: you previously need to build the image to use this install option, refer to "Building the image" in Open Vault Agent Injector image

cd deploy/helm
export CHART_LOCATION=$(pwd)

To see Chart content before installing it, perform a dry run first:

helm install ovai $CHART_LOCATION --namespace <namespace for deployment> --set vault.addr=<Vault server address> --debug --dry-run

To install the chart on the cluster:

helm install ovai $CHART_LOCATION --namespace <namespace for deployment> --set vault.addr=<Vault server address>

Note: Open Vault Agent Injector should be deployed only once (except for testing purpose, see below). It will mutate any "OVAI annotated" pod from any namespace. It shall not be deployed in every namespaces.

Note: it is possible to deploy an instance in a given namespace and to restrict injection to this same namespace if necessary, in particular in a dev environment where each team wants its own instance of Open Vault Agent Injector for testing purpose with its dedicated configuration (including a dedicated Vault server). Refer to Installing the chart in a dev environment section below.

As an example, to install Open Vault Agent Injector on our test cluster:

helm install ovai $CHART_LOCATION --namespace kube-system --set vault.addr=http://vault:8200 --set vault.ssl.verify=false

This command deploys the component on the Kubernetes cluster with modified configuration to target our Vault server in-cluster test instance (no verification of certificates): such settings are no fit for production.

The configuration section lists all the parameters that can be configured during installation.

Installing the chart in a dev environment

In a dev environment, you may want to install your own test instance of Open Vault Agent Injector, connected to your own Vault server and limiting injection to a given namespace. To do so, use following options:

helm install ovai $CHART_LOCATION --namespace <your dev namespace> --set vault.addr=<your dev Vault server address> --set mutatingwebhook.namespaceSelector.namespaced=true

And then add a label on your namespace as follows (if not done, no injection will be performed):

kubectl label namespace <your dev namespace> vault-injection=<your dev namespace> --overwrite

# check label on namespace
kubectl get namespace -L vault-injection
Restrict injection to specific namespaces

By default Open Vault Agent Injector monitors all namespaces (except kube-system and kube-public) and looks after annotations in submitted pods.

If you want to strictly control the list of namespaces where injection is allowed, set value mutatingwebhook.namespaceSelector.boolean=true when installing the chart as follows:

helm install ovai $CHART_LOCATION --namespace <namespace for deployment> --set vault.addr=<Vault server address> --set mutatingwebhook.namespaceSelector.boolean=true

Then apply label vault-injection=enabled on all required namespaces:

kubectl label namespace <namespace> vault-injection=enabled

# check label on namespace
kubectl get namespace -L vault-injection

Uninstalling the chart

To uninstall/delete the Open Vault Agent Injector deployment:

helm delete ovai -n <namespace for deployment>

This command removes all the Kubernetes resources associated with the chart and deletes the Helm release.