Migrating from the IntegrationConfig integration#
The older Vault integration is configured through IntegrationConfig.spec.integrations.vault and reconciled by MTO itself (see the older page). This extension replaces it. Both keep each tenant's secrets in a KV v2 mount at <tenant>/kv, so the secrets can stay where they are. The access model around them changes: per-application policies instead of one read policy per tenant, and SSO roles instead of identity groups.
Never set enabled: false on the old integration
Setting integrations.vault.enabled: false makes MTO unmount every tenant's <tenant>/kv engine, which deletes the secrets in it — the same secrets the extension serves. To turn the old integration off, delete the vault block from the IntegrationConfig; that leaves Vault as it stands.
What changes#
Old (IntegrationConfig) |
This extension | |
|---|---|---|
| Configured in | IntegrationConfig.spec.integrations.vault |
bootstrap chart values |
| Who reconciles | MTO's controller | Template Operator v2 and VCO, from the charts |
| Tenant's KV mount | <tenant>/kv |
<tenant>/kv — the same mount |
| Workload opt-in | label stakater.com/vault-access: "true" on a ServiceAccount |
annotations vault.stakater.com/kv and vault.stakater.com/role on a ServiceAccount |
| Workload access | <tenant>-read on the whole mount |
one policy per app, on its own prefix, at the role it asks for |
| Workload login | auth/kubernetes, role <namespace>-<tenant>-mto |
auth/<tenant>/kubernetes/workloads, role kv.<tenant>.<namespace>.<sa> |
| People | identity groups from the Tenant's accessControl groups; Owners admin, Viewers read, Editors nothing |
an OIDC mount per tenant; roles admin, editor, viewer, audit-read, each bound to an IdP group by pattern |
| Common path | one commonSecretsPath, shared by every tenant |
directional shares in shared/kv, opt-in on both sides |
| Custom policies | the policies block |
none — tenants never administer Vault; platform-wide access is a policy a Vault admin writes |
| Delivery | — | Kubernetes Secrets through External Secrets |
| Turning off or deleting | enabled: false deletes every tenant's secrets |
access ends; the mount and its secrets stay until a Vault admin purges them |
Before you start#
Rehearse it first
The extension's test suite proves a fresh install. It does not run this migration. Rehearse it on a copy of your Vault before you run it in production, and take a backup of Vault's storage (with integrated storage, vault operator raft snapshot save).
- Check every tenant's name. The extension skips a tenant whose name is not a DNS label of at most 29 characters, or is reserved (Security → what the extension validates). A skipped tenant keeps its old access but gets no new access.
- Reserve the old mounts. Add your
commonSecretsPath(defaultcommon-shared-secrets) and every other mount your Vault has toparent.reservedPaths. - Plan the IdP groups. The old integration took group names from each
Tenant. The extension binds each role to a group named by a pattern that holds the tenant's name, such as{tenant}-owner-group. If your groups do not follow such a pattern, create groups that do.
1. Install the extension next to the old integration#
Follow Installation. The parent renders a mount CR for every tenant's <tenant>/kv. VCO finds the mount already in place and keeps it with its secrets: it creates a mount only when none exists at the path, and otherwise only tunes its config. Check both:
kubectl -n vault-config get templateinstances.templates.v2.stakater.com \
mto-extension-vault-community-parent -o jsonpath='{.status.outputs.enginesSucceeded}'
vault kv list acme/kv # the old secrets are still there
The old access keeps working while you move workloads and people.
2. Move each workload#
The old layout is free-form (acme/kv/db-creds). The extension grants each app only its own prefix, <tenant>/kv/data/<env>/<namespace>/<app>/. For each app:
-
Annotate its ServiceAccount.
viewergives the read-only access it had before:metadata: annotations: vault.stakater.com/kv: "true" vault.stakater.com/role: viewer -
Copy each secret the app reads to its new path. A Vault admin, or a tenant Owner signed in through the old OIDC login, can do it:
vault kv get -format=json -mount=acme/kv db-creds | jq .data.data \ | vault kv put -mount=acme/kv dev/acme-shop/checkout/db-creds - -
Point the app at the new values: mount the
vault-config-<serviceaccount>ConfigMap(Giving an application a secret), or annotate the Deployment for delivery (Delivery and login). - Remove the
stakater.com/vault-accesslabel from the ServiceAccount.
3. Move people#
Turn on human SSO and map your groups to roles. For groups named like the old example's acme-owner-group and acme-viewer-group:
tenantValues:
sso:
roles: [admin, viewer]
tenantRoleMapping:
admin: { pattern: "{tenant}-owner-group" }
viewer: { pattern: "{tenant}-viewer-group" }
Add each tenant's redirect URI to the IdP client (redirect URIs are per tenant). Members then sign in on their tenant's own mount: vault login -method=oidc -path=<tenant>/oidc/sso role=sso.<tenant>.<role>.
4. Turn off the old integration#
When no workload uses a -mto role and no person needs the old login:
- Delete the
vaultblock from theIntegrationConfig. Do not setenabled: false. -
A Vault admin deletes what the old integration left. Until then, the old
<tenant>-adminpolicy still lets a tenant's Owners managesys/mounts/<tenant>/*— including disabling the mount — which the extension never grants:vault policy delete acme-admin vault policy delete acme-read vault list auth/kubernetes/role # the old roles end in -mto vault delete auth/kubernetes/role/acme-shop-acme-mto vault list identity/group/name # the old identity groupsDelete the old identity groups and their aliases, any custom policies from the
policiesblock, and the Vault role and policy MTO logged in with (accessInfo.roleName). Do not disable<tenant>/kv— the extension uses it. -
Disable the
commonSecretsPathmount once nothing reads it. Move a secret that one tenant gives another to a cross-tenant share. - Delete the old secret paths in each
<tenant>/kvonce every app reads from its new path.
Deliberate differences from the old integration#
- Workloads get least privilege. Each app reaches its own prefix at its own role, not the whole tenant mount.
- Editors get access. The
editorrole is a real role, from its own group. - No path shared by every tenant. Sharing is directional and both sides opt in.
- No custom tenant policies. On Community Edition the policy is the only wall between tenants, so only the extension writes tenant policies.
- Data outlives the tenant. Deleting a tenant, or the extension, never deletes secrets; a Vault admin purges them (Operating → deletion).
Previous: Reference