How to Set Up Vault for Axual Connect

This guide shows you how to add the connectors secrets engine to Vault, create the read-only AppRole that Axual Connect authenticates with, extend the Platform Manager policy to write into that engine, and put the resulting credentials into the Axual Connect values.

Type

How-to guide

Goal

Give Axual Connect a Vault AppRole it can use to read the certificates its connectors need.

Audience

Platform Operator with shell access to the Vault pod.

When to use

Use this guide once per tenant instance, before deploying Axual Connect.

Axual Connect is deprecated (see Why Kafka Connect replaces Axual Connect for the timeline). For Kafka Connect, which replaces it, the Connector Vault is a separate data-plane Vault set up differently. See How to Set Up the Connector Vault for Kafka Connect.

This guide covers the connector Vault for Axual Connect: the connectors engine and the AppRoles that read from and write to it. The governance Vault, which holds the cluster, SASL and connector credentials Platform Manager manages, is set up in How to Set Up Vault for Governance. Both can live in the same Vault.

Axual Connect gets a read role only. Platform Manager writes the connector credentials, and Axual Connect reads them at runtime, which is why two AppRoles are involved rather than one.

Contents

The sections below cover each task in this guide:

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 a Vault admin token.

  • Permission to edit the Axual Connect and 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.

Resources that must exist before starting

The following must already exist:

Copy every command output below into a password manager. The Secret ID is shown once and cannot be read back.

Create the connectors engine and the read-only AppRole

Axual Connect reads the certificates its connectors use from Vault, so it needs an engine to hold them and a role that can read that engine.

# Execute the following commands in the terminal and store the role and secret id
alias v='kubectl --context <context> -n <namespace> exec --stdin=true <vault-pod-name> -- '

v vault secrets enable -path=connectors kv-v2

echo 'path "connectors/data/<tenant>/<instance>/*" {capabilities = ["read"]}' | v vault policy write connect-<tenant>-<instance> -
echo 'path "connectors/*" { capabilities = ["read", "create", "update", "delete"] }' | v vault policy write pm-connect -

# Read the AppRole's current policies first: this write replaces the whole list.
v vault read -field=token_policies auth/approle/role/platform-manager
v vault write auth/approle/role/platform-manager token_policies="<EXISTING_POLICIES>,pm-connect"

v vault write auth/approle/role/connect-<tenant>-<instance> token_policies="connect-<tenant>-<instance>"
v vault read auth/approle/role/connect-<tenant>-<instance>/role-id
v vault write -force auth/approle/role/connect-<tenant>-<instance>/secret-id

The commands above also rewrite the Platform Manager AppRole to carry the pm-connect policy alongside its existing ones. That is what lets Platform Manager write into the connectors engine that Axual Connect reads from.

vault write …​ token_policies= replaces the whole policy list rather than adding to it. Read the current list with the command above and include every policy it returns, or Platform Manager loses the access those policies granted, including to other clusters. On a fresh installation the list is platform-manager, so the value becomes platform-manager,pm-connect.

Verify the connectors engine and the AppRole

Confirm that the engine exists, that both AppRoles carry their policy, and that the credentials you stored authenticate. Run the commands from the Vault pod, reusing the v alias from the previous section:

v vault secrets list
v vault read -field=token_policies auth/approle/role/connect-<tenant>-<instance>
v vault read -field=token_policies auth/approle/role/platform-manager
v vault write auth/approle/login role_id=<connect-role-id> secret_id=<connect-secret-id>

Expected results, one per command:

  • vault secrets list includes a connectors/ path of type kv. A missing path means vault secrets enable did not run, so there is nowhere for Platform Manager to write the connector certificates.

  • The connect-<tenant>-<instance> policy list holds connect-<tenant>-<instance>. An empty list means the AppRole was created without token_policies. Axual Connect then authenticates and is refused on every connectors/ path, which surfaces as an authorisation failure at runtime rather than here.

  • The platform-manager policy list holds pm-connect alongside the policies it carried before. A list without pm-connect means the write above dropped it, so Platform Manager cannot store the certificates Axual Connect reads.

  • The login returns a token whose token_policies list holds connect-<tenant>-<instance>. A failed login means the Role ID and Secret ID pair you stored does not match the AppRole, so re-read the Role ID and generate a new Secret ID.

The Secret ID is created with unlimited uses, so logging in here does not consume it.

Put the IDs in the Axual Connect values

Update the connect-values.yaml file you used to deploy the axual-stable/axual-connect Helm chart, or create it in your working directory with the contents below. Replace the role and secret IDs with the connect IDs you created earlier.

connect-values.yaml
# The roleId and secretId authenticate against Vault and
# authorise Axual Connect to retrieve secrets from it.
  axual-connect:
    vault:
      approleRoleId: <connect-<tenant>-<instance> role ID>
      approleSecretId: <connect-<tenant>-<instance> secret ID>

To keep the IDs out of connect-values.yaml, store them in a Kubernetes Secret with the keys roleId and secretId, in the namespace Axual Connect runs in. Write each ID to a file first, with no trailing newline, so neither reaches your shell history. The commands below use kafka, as in How to Deploy Axual Connect:

kubectl create secret generic connect-vault-approle -n kafka \
  --from-file=roleId=./role-id --from-file=secretId=./secret-id
rm ./role-id ./secret-id

Then name the Secret in vault.secretName and leave approleRoleId and approleSecretId out. The chart reads both IDs from the Secret when secretName is set.

connect-values.yaml
vault:
  secretName: connect-vault-approle

Platform Manager writes the certificates that Axual Connect then reads, so the same Role ID and Secret ID also go into the governance values. Use a single vault block when one Vault serves every tenant instance, or one entry under connector-vault.instances when each tenant instance has its own Vault. How to Deploy Axual Connect shows where that block sits, and Platform Manager 16.0.0 Readme lists every field either form takes. To keep the IDs out of the governance values as well, see How to Store Component Credentials in a Kubernetes Secret.

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