doc: update vault-helm to 0.7.0 (#9810)

* doc: update vault-helm to 0.7.0

* Fix typo in agent image

* Remove doc from sidebar

* Update website/pages/docs/platform/k8s/helm/configuration.mdx

Co-authored-by: Clint <catsby@users.noreply.github.com>

* Update website/pages/docs/platform/k8s/helm/configuration.mdx

Co-authored-by: Clint <catsby@users.noreply.github.com>

* Add note about prometheus

Co-authored-by: Clint <catsby@users.noreply.github.com>
This commit is contained in:
Jason O'Donnell 2020-08-24 19:03:36 -04:00 committed by GitHub
parent 844bb0b69a
commit 052dea6e57
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 122 additions and 191 deletions

View File

@ -331,7 +331,6 @@ export default [
'enterprise-with-raft',
'enterprise-dr-with-raft',
'enterprise-perf-with-raft',
'enterprise-best-practice',
],
},
],

View File

@ -27,6 +27,28 @@ and consider if they're appropriate for your deployment.
- `openshift` (`boolean: false`) - If `true`, enables configuration specific to OpenShift such as NetworkPolicy, SecurityContext, and Route.
- `psp` - Values that configure Pod Security Policy.
- `enable` (`boolean: false`) - When set to `true`, enables Pod Security Policies for Vault and Vault Agent Injector.
- `annotations` (`dictionary: {}`) - This value defines additional annotations to
add to the Pod Security Policies. This can either be YAML or a YAML-formatted
multi-line templated string.
```yaml
annotations:
seccomp.security.alpha.kubernetes.io/allowedProfileNames: docker/default,runtime/default
apparmor.security.beta.kubernetes.io/allowedProfileNames: runtime/default
seccomp.security.alpha.kubernetes.io/defaultProfileName: runtime/default
apparmor.security.beta.kubernetes.io/defaultProfileName: runtime/default
# or
annotations: |
seccomp.security.alpha.kubernetes.io/allowedProfileNames: docker/default,runtime/default
apparmor.security.beta.kubernetes.io/allowedProfileNames: runtime/default
seccomp.security.alpha.kubernetes.io/defaultProfileName: runtime/default
apparmor.security.beta.kubernetes.io/defaultProfileName: runtime/default
```
- `injector` - Values that configure running a Vault Agent Injector Admission Webhook Controller within Kubernetes.
- `enabled` (`boolean: true`) - When set to `true`, the Vault Agent Injector Admission Webhook controller will be created.
@ -37,7 +59,7 @@ and consider if they're appropriate for your deployment.
- `repository` (`string: "hashicorp/vault-k8s"`) - The name of the Docker image for Vault Agent Injector.
- `tag` (`string: "0.4.0"`) - The tag of the Docker image for the Vault Agent Injector. **This should be pinned to a specific version when running in production.** Otherwise, other changes to the chart may inadvertently upgrade your admission controller.
- `tag` (`string: "0.5.0"`) - The tag of the Docker image for the Vault Agent Injector. **This should be pinned to a specific version when running in production.** Otherwise, other changes to the chart may inadvertently upgrade your admission controller.
- `pullPolicy` (`string: "IfNotPresent"`) - The pull policy for container images. The default pull policy is `IfNotPresent` which causes the Kubelet to skip pulling an image if it already exists.
@ -45,7 +67,11 @@ and consider if they're appropriate for your deployment.
- `repository` (`string: "vault"`) - The name of the Docker image for the Vault Agent sidecar. This should be set to the official Vault Docker image.
- `tag` (`string: "1.4.2"`) - The tag of the Vault Docker image to use for the Vault Agent Sidecar. **Vault 1.3.1+ is required by the admission controller**.
- `tag` (`string: "1.5.2"`) - The tag of the Vault Docker image to use for the Vault Agent Sidecar. **Vault 1.3.1+ is required by the admission controller**.
- `metrics` - Values that configure the Vault Agent Injector metric exporter.
- `enabled` (`boolean: false`) - When set to `true`, the Vault Agent Injector exports Prometheus metrics at the `/metrics` path.
- `authPath` (`string: "auth/kubernetes"`) - Mount path of the Vault Kubernetes Auth Method.
@ -101,7 +127,7 @@ and consider if they're appropriate for your deployment.
- `repository` (`string: "vault"`) - The name of the Docker image for the containers running Vault.
- `tag` (`string: "1.4.2"`) - The tag of the Docker image for the containers running Vault. **This should be pinned to a specific version when running in production.** Otherwise, other changes to the chart may inadvertently upgrade your admission controller.
- `tag` (`string: "1.5.2"`) - The tag of the Docker image for the containers running Vault. **This should be pinned to a specific version when running in production.** Otherwise, other changes to the chart may inadvertently upgrade your admission controller.
- `pullPolicy` (`string: "IfNotPresent"`) - The pull policy for container images. The default pull policy is `IfNotPresent` which causes the Kubelet to skip pulling an image if it already exists.
@ -267,7 +293,7 @@ and consider if they're appropriate for your deployment.
secretKey: AWS_SECRET_ACCESS_KEY
```
- `extraVolumes` (`array: []`) - A list of extra volumes to mount to Vault servers. This is useful for bringing in extra data that can be referenced by other configurations at a well known path, such as TLS certificates. The value of this should be a list of objects. Each object supports the following keys:
- `extraVolumes` (`array: []`) - Deprecated: please use `volumes` instead. A list of extra volumes to mount to Vault servers. This is useful for bringing in extra data that can be referenced by other configurations at a well known path, such as TLS certificates. The value of this should be a list of objects. Each object supports the following keys:
- `type` (`string: required`) -
Type of the volume, must be one of "configMap" or "secret". Case sensitive.
@ -280,6 +306,9 @@ and consider if they're appropriate for your deployment.
- `path` (`string: /vault/userconfigs`) -
Name of the path where a configMap or secret is mounted. If not specified
the volume will be mounted to `/vault/userconfig/<name of volume>`.
- `defaultMode` (`string: "420"`) -
Default mode of the mounted files.
```yaml
extraVolumes:
@ -288,6 +317,24 @@ and consider if they're appropriate for your deployment.
path: '/etc/pki'
```
- `volumes` (`array: []`) - A list of volumes made available to all containers. This takes
standard Kubernetes volume definitions.
```yaml
volumes:
- name: plugins
emptyDir: {}
```
- `volumeMounts` (`array: []`) - A list of volumes mounts made available to all containers. This takes
standard Kubernetes volume definitions.
```yaml
volumeMounts:
- mountPath: /usr/local/libexec/vault
name: plugins
readOnly: true
```
- `affinity` - This value defines the [affinity](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) for server pods. It defaults to allowing only a single pod on each node, which minimizes risk of the cluster becoming unusable if a node is lost. If you need to run more pods per node (for example, testing on Minikube), set this value to `null`.
```yaml
@ -369,6 +416,10 @@ and consider if they're appropriate for your deployment.
```
- `serviceAccount` - Values that configure the Kubernetes service account created for Vault.
- `create` (`boolean: true`): If set to true, creates a service account used by Vault.
- `name` (`string: ""`): Name of the service account to use. If not set and create is true, a name is generated using the name of the installation (default is "vault").
- `annotations` (`dictionary: {}`) - This value defines additional annotations for the service account. This can either be YAML or a YAML-formatted multi-line templated string.
@ -396,6 +447,18 @@ and consider if they're appropriate for your deployment.
- `accessMode` (`string: ReadWriteOnce`) -
Type of access mode of the storage device. See the [official Kubernetes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) for more information.
- `annotations` (`dictionary: {}`) - This value defines additional annotations to
add to the data PVCs. This can either be YAML or a YAML-formatted
multi-line templated string.
```yaml
annotations:
kubernetes.io/my-pvc: foobar
# or
annotations: |
kubernetes.io/my-pvc: foobar
```
- `auditStorage` - This configures the volume used for storing Vault's audit logs. See the [Vault documentation](/docs/audit) for more information.
- `enabled` (`boolean: true`) -
@ -409,6 +472,18 @@ and consider if they're appropriate for your deployment.
- `accessMode` (`string: ReadWriteOnce`) -
Type of access mode of the storage device.
- `annotations` (`dictionary: {}`) - This value defines additional annotations to
add to the audit PVCs. This can either be YAML or a YAML-formatted
multi-line templated string.
```yaml
annotations:
kubernetes.io/my-pvc: foobar
# or
annotations: |
kubernetes.io/my-pvc: foobar
```
- `dev` - This configures `dev` mode for the Vault server.
@ -453,6 +528,9 @@ and consider if they're appropriate for your deployment.
- `enabled` (`boolean: false`) -
Enables `ha` mode for the Vault server. This mode uses a highly available backend storage (such as Consul) to store Vault's data. By default this is configured to use [Consul Helm](https://github.com/hashicorp/consul-helm). For a complete list of storage backends, see the [Vault documentation](/docs/configuration).
- `apiAddr`: (`string: "{}"`) -
Set the API address configuration for a Vault cluster. If set to an empty string, the pod IP address is used.
- `raft` - This configures `raft` integrated storage mode for the Vault server.
- `enabled` (`boolean: false`) -
@ -509,6 +587,21 @@ and consider if they're appropriate for your deployment.
this to `0`, you will need to add a `--set 'server.disruptionBudget.maxUnavailable=0'`
flag to the helm chart installation command because of a limitation in the Helm
templating language.
- `statefulset` - This configures settings for the Vault Statefulset.
- `annotations` (`dictionary: {}`) - This value defines additional annotations to
add to the Vault statefulset. This can either be YAML or a YAML-formatted
multi-line templated string.
```yaml
annotations:
kubernetes.io/my-statefulset: foobar
# or
annotations: |
kubernetes.io/my-statefulset: foobar
```
- `ui` - Values that configure the Vault UI.
@ -519,6 +612,12 @@ and consider if they're appropriate for your deployment.
The available service types are documented on
[the Kubernetes website](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types).
- `publishNotReadyAddresses` (`boolean: true`) -
If set to true, will route traffic to Vault pods that aren't ready (if they're sealed or uninitialized.
- `activeVaultPodOnly` (`boolean: false`) -
If set to true, the UI service will only route to the active pod in a Vault HA cluster.
- `serviceNodePort` (`int: null`) -
Sets the Node Port value when using `serviceType: NodePort` on the Vault UI service.

View File

@ -1,166 +0,0 @@
---
layout: 'docs'
page_title: 'Enterprise Best Practice'
sidebar_current: 'docs-platform-k8s-examples-enterprise-best-practice'
sidebar_title: 'Enterprise Best Practice'
description: |-
Describes how to set up a best practices Vault Enterprise cluster
---
# Vault Enterprise Best Practices Cluster
~> **Important Note:** This chart is not compatible with Helm 2. Please use Helm 3 with this chart.
~> **Important Note:** Only non-HSM images are supported. Image tags ending with ".hsm" will not work.
Vault's enterprise features focus around replication. Typically, one cluster is a leader, and other
clusters are followers. There are two main types of following clusters. Disaster replication clusters
serve as a warm standby should the leader cluster stop serving traffic. Performance replication
clusters increase the number of reads that Vault can service.
AWS is given here in depth as a sample for auto-unseal, but any [auto-unseal](/docs/configuration/seal)
mechanism may be used.
## Walk-Through
1. Create an EKS cluster. This walk-through will assume it's named "vault-cluster".
2. While the cluster is launching, create a role for Vault's node group to use.
[AWS's docs](https://docs.aws.amazon.com/eks/latest/userguide/worker_node_IAM_role.html)
should be considered the authority on the policies that need to be attached, but at the time
of writing, the required policies are the `AmazonEKSWorkerNodePolicy`, the `AmazonEKS_CNI_Policy`,
and the `AmazonEC2ContainerRegistryReadOnly`. For the purposes of this walk-through, we will
assume you name this new role, "EKSNodeGroupForAutoUnseal".
3. While the cluster is launching, also create a KMS key that will be used for auto-unseal.
Under "Define key usage permissions", search for "EKSNodeGroupForAutoUnseal" and add a check
next to it.
4. One you've finished creating the key, return to IAM. Create a new policy called
"UnsealKeyUsageForVault" and attach it to the "EKSNodeGroupForAutoUnseal" role. The policy
contents should be:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:Encrypt",
"kms:DescribeKey"
],
"Resource": "arn:aws:kms:us-west-2:012345678901:key/207a68f5-f100-410c-8066-EXAMPLE"
}
]
}
```
5. Return to EKS and add a node group. While launching it, under "Node IAM Role Name", select
"EKSNodeGroupForAutoUnseal".
6. While the nodes are creating, point your local `kubectl` at your new cluster as shown
[here](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html).
## Generate TLS Certificates
TLS certificate generation is covered [here](/docs/platform/k8s/helm/examples/standalone-tls).
## Setting Up the Primary Cluster
The below `values-custom.yaml` can be used to set up a three server Vault cluster using
Consul as a highly available storage backend, with AWS KMS for Auto Unseal.
```yaml
# Create a values-custom.yaml to override default values
cat << EOF > values-custom.yaml
server:
image:
repository: "hashicorp/vault-enterprise"
tag: "1.4.2_ent"
affinity: |
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchLabels:
app: {{ template "vault.name" . }}
release: "{{ .Release.Name }}"
component: server
topologyKey: kubernetes.io/hostname
ha:
enabled: true
replicas: 3
config: |
ui = true
service_registration "kubernetes" {
namespace = "my-namespace"
pod_name = "my-pod-name"
}
listener "tcp" {
tls_cert_file = "/path/to/fullchain.pem"
tls_key_file = "/path/to/privkey.pem"
tls_client_ca_file = "/vault/userconfig/vault-server-tls/vault.ca"
address = "[::]:8200"
cluster_address = "[::]:8201"
}
storage "consul" {
path = "vault-us-east"
address = "HOST_IP:8500"
token = "45a3bd52-07c7-47a4-52fd-0745e0cfe967"
}
seal "awskms" {
region = "us-east-2"
kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey"
}
EOF
```
Next, point Helm to the chart release and specify the `values-custom.yaml` file:
```
helm install vault-us-east hashicorp/vault -f values-custom.yaml
```
Note that in the above seal stanza, the AWS key and secret are omitted. That's because
Vault picks them up from the node group's Instance Metadata, which in this example has
been configured to provide credentials for the "EKSNodeGroupForAutoUnseal" role.
Also note that the `namespace` and `pod_name` in the service registration stanza can
alternatively be set using the Downward API. Please see
[Kubernetes Service Registration](/docs/configuration/service-registration/kubernetes)
for elaboration.
Lastly, note that the `path` for `consul` is set to `vault-us-east`. This is because, in
a replicated environment, we would expect other clusters to be in other regions such as
`vault-us-west`. A similar distinction was made in the `helm install` command's naming
convention.
After bringing up the first cluster (and each cluster thereafter), Vault enterprise
requires a license to be installed within a limited time window, as shown
[here](/api-docs/system/license#install-license).
## Setting Up a Disaster Replication (DR) Cluster
Setting up a DR cluster follows an identical process and configuration for
creating the cluster itself, but presumably in a different region. This would
necessitate changing the value under `consul` and `path` to one relevant to the
region for the DR cluster, such as `vault-us-west`, as well as the `[NAME]` used
in the `helm install` command.
Once the cluster is up and the license is added, add it as a follower to the leader
cluster. See [Disaster Recovery Replication Setup](https://learn.hashicorp.com/vault/operations/ops-disaster-recovery)
for more information.
## Setting Up a Performance Cluster
Setting up a performance cluster also follows an identical process and configuration
for creating the cluster itself, with the region differentiations noted above.
Once the cluster is up and the license is added, add it as a follower to the leader
cluster. See [Setting Up Performance Replication](https://learn.hashicorp.com/vault/operations/ops-replication)
for more on how to configure a cluster to follow the primary once it is up.

View File

@ -22,7 +22,7 @@ First, create the primary cluster:
```shell
helm install vault-primary hashicorp/vault \
--set='server.image.repository=hashicorp/vault-enterprise' \
--set='server.image.tag=1.4.2_ent' \
--set='server.image.tag=1.5.2_ent' \
--set='server.ha.enabled=true' \
--set='server.ha.raft.enabled=true'
```
@ -74,7 +74,7 @@ disaster recovery replication.
```shell
helm install vault-secondary hashicorp/vault \
--set='server.image.repository=hashicorp/vault-enterprise' \
--set='server.image.tag=1.4.2_ent' \
--set='server.image.tag=1.5.2_ent' \
--set='server.ha.enabled=true' \
--set='server.ha.raft.enabled=true'
```

View File

@ -22,7 +22,7 @@ First, create the primary cluster:
```shell
helm install vault-primary hashicorp/vault \
--set='server.image.repository=hashicorp/vault-enterprise' \
--set='server.image.tag=1.4.2_ent' \
--set='server.image.tag=1.5.2_ent' \
--set='server.ha.enabled=true' \
--set='server.ha.raft.enabled=true'
```
@ -73,7 +73,7 @@ With the primary cluster created, next create a secondary cluster.
```shell
helm install vault-secondary hashicorp/vault \
--set='server.image.repository=hashicorp/vault-enterprise' \
--set='server.image.tag=1.4.2_ent' \
--set='server.image.tag=1.5.2_ent' \
--set='server.ha.enabled=true' \
--set='server.ha.raft.enabled=true'
```

View File

@ -16,7 +16,7 @@ Integrated storage (raft) can be enabled using the `server.ha.raft.enabled` valu
```shell
helm install vault hashicorp/vault \
--set='server.image.repository=hashicorp/vault-enterprise' \
--set='server.image.tag=1.4.2_ent' \
--set='server.image.tag=1.5.2_ent' \
--set='server.ha.enabled=true' \
--set='server.ha.raft.enabled=true'
```

View File

@ -36,7 +36,7 @@ $ helm repo add hashicorp https://helm.releases.hashicorp.com
$ helm search repo hashicorp/vault
NAME CHART VERSION APP VERSION DESCRIPTION
hashicorp/vault 0.5.0 Install and configure Vault on Kubernetes.
hashicorp/vault 0.7.0 1.5.2 Official HashiCorp Vault Chart
```
-> **Important:** The Helm chart is new and under significant development.
@ -58,11 +58,11 @@ Installing a specific version of the chart.
# List the available releases
$ helm search repo hashicorp/vault -l
NAME CHART VERSION APP VERSION DESCRIPTION
hashicorp/vault 0.5.0 Install and configure Vault on Kubernetes.
hashicorp/vault 0.4.0 Install and configure Vault on Kubernetes.
hashicorp/vault 0.7.0 1.5.2 Official HashiCorp Vault Chart
hashicorp/vault 0.6.0 1.4.2 Official HashiCorp Vault Chart
# Install version 0.4.0
$ helm install vault hashicorp/vault --version 0.4.0
# Install version 0.7.0
$ helm install vault hashicorp/vault --version 0.7.0
```
~> **Security Warning:** By default, the chart runs in standalone mode. This

View File

@ -70,7 +70,7 @@ $ helm repo add hashicorp https://helm.releases.hashicorp.com
$ helm search repo hashicorp/vault
NAME CHART VERSION APP VERSION DESCRIPTION
hashicorp/vault 0.6.0 1.4.2 Official HashiCorp Vault Chart
hashicorp/vault 0.7.0 1.5.2 Official HashiCorp Vault Chart
```
-> **Important:** The Helm chart is new and under significant development.
@ -89,12 +89,11 @@ Or install a specific version of the chart.
# List the available releases
$ helm search repo hashicorp/vault -l
NAME CHART VERSION APP VERSION DESCRIPTION
hashicorp/vault 0.7.0 1.5.2 Official HashiCorp Vault Chart
hashicorp/vault 0.6.0 1.4.2 Official HashiCorp Vault Chart
hashicorp/vault 0.5.0 Install and configure Vault on Kubernetes.
hashicorp/vault 0.4.0 Install and configure Vault on Kubernetes.
# Install version 0.5.0
$ helm install vault hashicorp/vault --version 0.5.0
# Install version 0.7.0
$ helm install vault hashicorp/vault --version 0.7.0
```
The `helm install` command accepts parameters to override default configuration

View File

@ -54,7 +54,7 @@ $ helm repo add hashicorp https://helm.releases.hashicorp.com
$ helm search repo hashicorp/vault
NAME CHART VERSION APP VERSION DESCRIPTION
hashicorp/vault 0.5.0 Install and configure Vault on Kubernetes.
hashicorp/vault 0.7.0 1.5.2 Official HashiCorp Vault Chart
```
-> **Important:** The Helm chart is new and under significant development.
@ -76,8 +76,8 @@ NAME CHART VERSION APP VERSION DESCRIPTION
hashicorp/vault 0.5.0 Install and configure Vault on Kubernetes.
hashicorp/vault 0.4.0 Install and configure Vault on Kubernetes.
# Install version 0.4.0
$ helm install vault hashicorp/vault --version 0.4.0
# Install version 0.7.0
$ helm install vault hashicorp/vault --version 0.7.0
```
The `helm install` command accepts parameters to override default configuration
@ -420,14 +420,14 @@ Next, list the Helm versions and choose the desired version to install.
```bash
helm search repo hashicorp/vault
NAME CHART VERSION APP VERSION DESCRIPTION
hashicorp/vault 0.5.0 Install and configure Vault on Kubernetes.
hashicorp/vault 0.7.0 1.5.2 Official HashiCorp Vault Chart
```
Next, test the upgrade with `--dry-run` first to verify the changes sent to the
Kubernetes cluster.
```shell-session
$ helm upgrade vault hashicorp/vault --version=0.5.0 \
$ helm upgrade vault hashicorp/vault --version=0.7.0 \
--set='server.image.repository=vault' \
--set='server.image.tag=123.456' \
--dry-run