How to Set Up Vault for Governance

This guide shows you how to initialise and unseal HashiCorp Vault, enable the AppRole auth method and the key-value secrets engine, create the policy and AppRole that Platform Manager authenticates with, and put the resulting credentials into the governance values.

Type

How-to guide

Goal

Give Platform Manager a Vault AppRole it can use to read and write governance secrets.

Audience

Platform Operator with a Vault root token, or shell access to the Vault pod.

When to use

Use this guide once per Vault, before installing the governance layer.

Platform Manager stores three kinds of secret in Vault: cluster details and superuser credentials, Simple Authentication and Security Layer (SASL) credentials, and connector credentials. It needs a write/read role to set them. Axual Connect and Kafka Connect need only a read role, which is a separate AppRole.

The steps below use the governance secret engine, which is required when running Platform Manager with the Streaming charts. Any other engine name works if you change it consistently.

Contents

The sections below cover each task in this guide:

Which Vault applies to which setup

Three setups use Vault, and they do not all use the same one. Reading the wrong guide produces credentials in the wrong Vault, which fails at runtime rather than at setup time.

Governance Vault

The control-plane Vault, which Platform Manager reads and writes. This guide sets it up. One Vault can serve several tenant instances, and Vault Enterprise works as well.

Connector Vault for Axual Connect

A connectors engine holding the certificates connectors use, read by the shared Axual Connect cluster. It can live in the same Vault as Governance. See How to Set Up Vault for Axual Connect.

Connector Vault for Kafka Connect

A data-plane Vault, deliberately separate from the control plane so that a network blocking data-plane-to-control-plane traffic does not break connector credentials. See How to Set Up the Connector Vault for Kafka Connect, and Understanding the two-Vault model for why they are separate.

Prerequisites

Confirm the following before you begin.

Access and permissions required

You need the following access and permissions:

  • Shell access to the Vault pod, or browser access to the Vault user interface.

  • The Vault root token, which the initialisation step produces when the Vault is new.

  • Permission to edit the governance values and apply them.

Tools and versions required

You need the following tools:

  • kubectl >= 1.28, with access to the namespace Vault runs in, for the terminal path.

  • A password manager to hold the unseal keys, the root token, the Role ID and the Secret ID.

Resources that must exist before starting

The following must already exist:

  • A deployed HashiCorp Vault for the control plane. The Axual Governance chart deploys one as platform-manager-vault; see Install Axual Governance.

  • The namespace and pod name of that Vault, which the terminal commands below need.

  • The governance values.yaml you applied that chart with, which the last section edits.

Choose the setup path

The same setup appears twice below and both paths produce the same Vault, so follow one of them:

  • Terminal (faster): Run the whole setup as kubectl exec commands against the Vault pod. Choose this path when you have shell access to the pod and want the setup in a single block. Start at Fast Vault setup via terminal.

  • Vault user interface: Click through the same steps in the browser, with a screenshot for each. Choose this path when you reach Vault through a browser rather than a shell, or when you want to see what each step changes. Start at Initialise and unseal the HashiCorp Vault.

Both paths converge at Verify the AppRole.

Fast Vault setup via terminal

The commands below do the whole setup in one go with kubectl.

Copy and store every command output. The unseal keys, the Role ID and the Secret ID are shown once and are needed later. 
# First create an alias to speed up interaction with the vault
alias v='kubectl --context <kube-context> -n <vault-namespace> exec --stdin=true <vault-pod-name> -- '

# The first time only, initialise the vault
# Use -key-shares=3 and -key-threshold=2 for production
v vault operator init -key-shares=1 -key-threshold=1
# Save the key(s) in password manager!

# Unseal vault (may require multiple keys)
v vault operator unseal <key>
v vault login <root-token>

# Set up vault for Self-Service
v vault secrets enable -path=governance kv-v2
v vault auth enable approle
echo 'path "governance/*" {capabilities = ["read","create","update","delete"]}' | v vault policy write platform-manager -
v vault write auth/approle/role/platform-manager token_policies="platform-manager"
v vault read auth/approle/role/platform-manager/role-id
v vault write -force auth/approle/role/platform-manager/secret-id
# Save Role ID and Secret ID in password manager!
Replace every <…​> placeholder with your own value before running a command. <vault-pod-name> is the Vault pod of the governance release, for example axual-governance-platform-manager-vault-0.

An installation that includes Axual Connect needs a second engine and a second AppRole in the same Vault, which How to Set Up Vault for Axual Connect covers.

Then continue with Verify the AppRole.

Initialise and unseal the HashiCorp Vault

The first time you install HashiCorp Vault, initialise it to produce the unseal keys and the root token. Two figures decide how the keys work:

  • Key Shares: the number of issued keys that can unseal Vault (Local: 1, Prod: 3)

  • Key Threshold: the minimum number of keys needed to unseal Vault (Local: 1, Prod: 2)

For details, see the Vault documentation.

  1. Access the Vault user interface

    Vault UI init screen

  2. Provide the key shares and the key threshold and press Initialise button

    For a production environment, use at least key_shares=3 and key_threshold=2.
    Vault UI init screen with values

  3. Download the generated keys

    You need these keys to unseal Vault and to reach the Vault user interface.
    Vault UI download keys screen

  4. Press the Continue to Unseal button

  5. Paste the Key(s) and press the Unseal button

    Vault UI unseal screen

    Depending on the key shares and key threshold you chose, repeat the step above with a different key.

    For details, see the Vault documentation.

Enable the AppRole auth method

The AppRole auth method lets an application authenticate with roles defined in Vault.

For details, see the Vault documentation.

  1. Log in to the Vault user interface with your rootToken

    Vault UI login screen

  2. Open the Access menu

    Open Access Menu

  3. Press the Enable auth method button

    Enable auth method button

  4. Select the AppRole type for the new Authentication Method and press Next

    Select Authentication Method type

  5. Fill the Path with approle and press the Enable Method button

    Create AppRole

  6. The AppRole authentication method is now enabled and ready for Platform Manager.

    `platform-manager` Policy created

Create the KV secrets engine

The key-value (KV) secrets engine stores secrets in Vault storage as key and value pairs.

For details, see the Vault documentation.

  1. Log in to the Vault user interface with the rootToken

    Vault UI login screen

  2. Open the Secrets Engines menu

    Open Secrets Engines Menu

  3. Press the Enable new engine button

    Enable new engine button

  4. Select the KV type for the new engine and press Next

    Select Secrets Engine type

  5. Fill the Path with governance and press Enable Engine

    Create `governance` path

  6. The governance KV secrets engine is now configured and ready for Platform Manager.

    `governance` KV secrets engine created

Create the Platform Manager policy

The policy grants access to a path, and the AppRole ties that policy to credentials Platform Manager can authenticate with. Both halves are needed, in that order.

Create the ACL Rule

An Access Control List (ACL) rule is a Vault policy that grants access to a path declaratively.

For details, see the Vault documentation.

  1. Log in to the Vault user interface with the rootToken

    Vault UI login screen

  2. Open the Policy menu

    Open Policies Menu

  3. Press the Create ACL policy button

    ACL policy button

  4. Fill the Name with platform-manager and copy the following content as Policy

    path "governance/*" {
  capabilities = ["read","create","update","delete"]
}
    Create Platform Manager policy

  5. Press Create Policy

    `platform-manager` Policy created

  6. The Platform Manager policy now exists. The next section adds it to the Platform Manager AppRole.

Create RoleId and SecretId

The Role ID identifies the AppRole and the Secret ID is its password. Vault displays the Secret ID once, so store it before leaving the screen.

  1. Log in to the Vault user interface with the rootToken

    Vault UI login screen

  2. Open the terminal menu

    Open Terminal Menu

  3. Add the Platform Manager policy to the Platform Manager AppRole

    vault write auth/approle/role/platform-manager token_policies="platform-manager"
    Write policy to Platform Manager AppRole

  4. Read the Platform Manager policy role_id

    vault read auth/approle/role/platform-manager/role-id
    Read Platform Manager RoleID

  5. The response looks like this

    Key     Value
role_id 0b7569bd-7d8b-c33c-f759-e15231b18542

    Note the role_id. Platform Manager needs it in its configuration.

  6. Read the Platform Manager policy secret_id

    vault write -force auth/approle/role/platform-manager/secret-id
    Read Platform Manager SecretID

  7. The response looks like this

    Key                Value
secret_id          2387519d-5ac8-8af2-ad58-e89848fa3f05
secret_id_accessor a5740957-205d-7be4-23c7-e7bc57791631
secret_id_num_uses 0
secret_id_ttl      0

    Note down the secret_id and store it in a password manager. Vault does not display it again, and Platform Manager needs it in its configuration.

  8. Platform Manager can now reach the governance path.

Verify the AppRole

Whichever path you followed, confirm the AppRole exists and carries the policy before handing its credentials to Platform Manager. Run both commands from the Vault pod or the Vault user interface terminal:

vault read auth/approle/role/platform-manager/role-id
vault read -field=token_policies auth/approle/role/platform-manager

Expected output:

Key        Value
---        -----
role_id    <uuid>

[platform-manager]

A role_id field means the AppRole is registered, and platform-manager in the policy list means the policy is attached. An empty policy list means the AppRole was created without token_policies. Platform Manager then authenticates and is refused on every governance/ path, which surfaces as an authorisation failure at runtime rather than here.

Using the Role ID and Secret ID in configuration

Platform Manager reads the pair from the governance values. Edit the values.yaml file in your working directory and add the role_id and secret_id you stored earlier:

values.yaml
axual-governance:
  platform-manager:
    config:
      # Vault Configuration for Self-Service
      governance:
        vault:
          enabled: true
          uri: "http://axual-governance-platform-manager-vault:8200"
          roleId: <platform-manager role ID>
          secretId: <platform-manager secret ID>
          path: "governance"
          # namespace:

Write roleId and secretId in camelCase. With role-id and secret-id under governance.vault, Platform Manager fails to start with Could not resolve placeholder 'governance.vault.roleId'.

To keep both values out of the values file, store them in a Kubernetes Secret instead, as described in How to Store Component Credentials in a Kubernetes Secret.

Axual Connect authenticates with a second AppRole, and the values that point Platform Manager at the connectors engine belong with it. See How to Set Up Vault for Axual Connect.

For every Vault chart value, see HashiCorp Vault Chart Values Reference.