Vault Installation to Red Hat OpenShift via Helm
Red Hat's OpenShift is a distribution of the Kubernetes platform that provides a number of usability and security enhancements
In this tutorial, you login to an OpenShift cluster, install Vault via the Helm chart and then configure the authentication between Vault and the cluster. Then you deploy two web applications. One that authenticates and requests secrets directly from the Vault server. The other that employs deployment annotations that enable it to remain Vault unaware.
Prerequisites
This tutorial requires the OpenShift command-line interface (CLI) and the Helm CLI installed, OpenShift and additional configuration to bring it all together.
This tutorial was last tested 14 Jul 2020 on a macOS 10.15.5 using this configuration.
CodeReady Containers version.
Helm version.
These are recommended software versions and the output displayed may vary depending on your environment and the software versions you use.
First, follow the directions to install CodeReady Containers.
Next, install the helm CLI.
Install helm
with Homebrew.
Next, retrieve the web application and additional configuration by cloning the hashicorp/vault-guides repository from GitHub.
This repository contains supporting content for all of the Vault learn guides. The content specific to this tutorial can be found within a sub-directory.
Go into the
vault-guides/operations/provision-vault/kubernetes/openshift
directory.
Working directory
This tutorial assumes that the remainder of commands are executed within this directory.
Configure and start the OpenShift cluster
CloudReady Containers (CRC) is a CLI tool that provisions and manages the lifecycle of OpenShift clusters running on your local system.
Configure CloudReady Containers.
Start the OpenShift cluster,
Image Pull Secret
This secret is generated and stored in your Red Hat account.
The cluster starts and describes how to setup the environment and login as an administrator.
Apply the oc-env
into the current shell session.
The OpenShift CLI is accessed using the command oc
. From here, you can
administrate the entire OpenShift cluster and deploy new applications. The CLI
exposes the underlying Kubernetes orchestration system with the enhancements
made by OpenShift.
Login to the OpenShift cluster with as the user admin with the command provided
by the crc start
command.
Example:
The output displays that you are logged in as an admin within the default
project.
Install the Vault Helm chart
The recommended way to run Vault on OpenShift is via the Helm chart. Helm is a package manager that installs and configures all the necessary components to run Vault in several different modes. To install Vault via the Helm chart in the next step requires that you are logged in as administrator within a project.
Add the Hashicorp Helm repository.
Update all the repositories to ensure helm
is aware of the latest versions.
Install the latest version of the Vault server running in development mode configured to work with OpenShift.
The Vault pod and Vault Agent Injector pod are deployed in the default namespace.
Display all the pods within the default namespace.
The vault-0
pod runs a Vault server in development mode. The
vault-agent-injector
pod performs the injection based on the annotations
present or patched on a deployment.
Wait until the vault-0
pod and vault-agent-injector
pod are running and
ready (1/1
).
Configure Kubernetes authentication
Vault provides a Kubernetes authentication method that enables clients to authenticate with Vault within an OpenShift cluster. This authentication method configuration requires the location of the Kubernetes API, which is available in environment variables within the pod.
Start an interactive shell session on the vault-0
pod.
Your system prompt is replaced with a new prompt / #
. Commands issued at this
prompt are executed on the vault-0
container.
Enable the Kubernetes authentication method.
Configure the Kubernetes authentication method to use the location of the Kubernetes host. It will automatically use the pod's own identity to authenticate with Kubernetes when querying the token review API.
For the best compatibility with recent Kubernetes versions, ensure you are using Vault v1.9.3 or greater.
The authentication method is now configured.
Exit the vault-0
pod.
Deployment: Request secrets directly from Vault
Applications on pods can directly communicate with Vault to authenticate and request secrets. An application needs:
- a service accont
- a Vault secret
- a Vault policy to read the secret
- a Kubernetes authentication role
Create the service account
Display the service account defined in service-account-webapp.yml
.
This definition of the service account creates the account with the name
webapp
.
Apply the service account.
Get all the service accounts within the default namespace.
The webapp
service account is displayed.
Create the secret
Start an interactive shell session on the vault-0
pod.
Your system prompt is replaced with a new prompt / #
. Commands issued at this
prompt are executed on the vault-0
container.
Create a secret at path secret/webapp/config
with a username
and password
.
Get the secret at path secret/webapp/config
.
The secret with the username and password is displayed.
Define the read policy
Write out the policy named webapp
that enables the read
capability for
secrets at path secret/data/webapp/config
.
The policy webapp
is used in the Kubernetes authentication role definition.
Create a Kubernetes authentication role
Create a Kubernetes authentication role, named webapp
, that connects the
Kubernetes service account name and webapp
policy.
The role connects the Kubernetes service account, webapp
, the namespace,
default
, with the Vault policy, webapp
. The tokens returned are valid for 24
hours.
Exit the vault-0
pod.
Deploy the application
Display the webapp deployment defined in deployment-webapp.yml
.
The deployment deploys a pod with a web application running under the webapp
service account that talks directly to the Vault service created by the Vault
Helm chart http://vault:8200
.
Apply the webapp deployment.
Display all the pods within the default namespace.
Wait until the webapp
pod is running and ready (1/1
).
This web application runs an HTTP service that listens on port 8080.
Perform a curl
request at http://localhost:8080
on the webapp
pod.
The web application running on port 8080 in the webapp pod:
- authenticates with the Kubernetes service account token
- receives a Vault token with the read capability at the
secret/data/webapp/config
path - retrieves the secrets from
secret/data/webapp/config
path - displays the secrets as JSON
Deployment: Secrets through Annotations
Applications on pods can remain Vault unaware if they provide deployment annotations that the Vault Agent Injector detects. This injector service leverages the Kubernetes mutating admission webhook to intercept pods that define specific annotations and inject a Vault Agent container to manage these secrets. An application needs:
- a service accont
- a Vault secret
- a Vault policy to read the secret
- a Kubernetes authentication role
- a deployment with Vault Agent Injector annotations
Create the service account
Display the service account defined in service-account-issues.yml
.
This definition of the service account creates the account with the name
issues
.
Apply the service account.
Get all the service accounts within the default namespace.
The issues
service account is displayed.
Create the secret
Start an interactive shell session on the vault-0
pod.
Your system prompt is replaced with a new prompt / #
. Commands issued at this
prompt are executed on the vault-0
container.
Create a secret at path secret/issues/config
with a username
and password
.
Get the secret at path secret/issues/config
.
The secret with the username and password is displayed.
Define the read policy
Write out the policy named issues
that enables the read
capability for
secrets at path secret/data/issues/config
.
The policy issues
is used in the Kubernetes authentication role definition.
Create a Kubernetes authentication role
Create a Kubernetes authentication role, named issues
, that connects the
Kubernetes service account name and issues
policy.
The role connects the Kubernetes service account, issues
, the namespace,
default
, with the Vault policy, issues
. The tokens returned are valid for 24
hours.
Exit the vault-0
pod.
Deploy the application
Display the issues deployment defined in deployment-issues.yml
.
The Vault Agent Injector service reads the metadata annotations prefixed with
vault.hashicorp.com
.
agent-inject
enables the Vault Agent injector servicerole
is the Vault Kubernetes authentication roleagent-inject-secret-FILEPATH
prefixes the path of the file,issues-config.txt
written to the/vault/secrets
directory. The value is the path to the Vault secret.agent-inject-template-FILEPATH
formats the secret with a provided template.
Apply the issues deployment.
Display all the pods within the default namespace.
Wait until the issues
pod is running and ready (2/2
).
This new pod now launches two containers. The application container, named
issues
, and the Vault Agent container, named vault-agent
.
Display the logs of the vault-agent
container in the issues
pod.
Display the secret written to the issues
container.
The secrets are rendered in a PostgreSQL connection string is present on the container.
Next Steps
You launched Vault within OpenShift with a Helm chart. Learn more about the Vault Helm chart by reading the documentation or exploring the project source code.
Then you deployed a web application that authenticated and requested a secret directly from Vault. And finally, deployed a web application that injected secrets based on deployment annotations supported by the Vault Agent Injector service. Learn more by reading the blog post announcing the "Injecting Vault Secrets into Kubernetes Pods via a Sidecar", or the documentation for Vault Agent Injector service.