Tenant Onboarding and Offboarding
Platform administrators provision new tenants and retire them safely—including identity setup in Keycloak, platform resources, and coordination with tenant administrators.
Onboarding a Tenant
Onboarding a new tenant involves the following steps:
- Add entry to infrastructure repository: Create a new entry for the tenant in the infrastructure Git repository.
- Add chart from template: Add the OLIVE Platform Helm chart for the tenant using the template provided in the template Git repository.
- Configure values.yaml: Customize the
values.yamlfile for the new tenant with appropriate configuration values. - Import connectivity bundle: Import the foundational OLIVE connectivity bundle for the corresponding platform version. This bundle provides the base connectivity and integration capabilities required for the tenant.
- Automatic deployment: Once changes are checked in and ArgoCD is correctly configured, the new tenant is automatically deployed to the platform.
Nothing in the list above sets up Keycloak or Vault by hand. Two charts in the tenant's deployment do it on every sync:
| Chart | What it creates for the tenant |
|---|---|
keycloak-setup | The tenant's Keycloak realm, named after the tenant: its four confidential clients, the realm roles, the groups and the administrator account. It also mirrors two client secrets into Vault. |
vault-secrets-setup | The tenant's Vault policies, Kubernetes auth roles and KV paths, and the ServiceAccount bindings the pods authenticate with. |
Both run as Jobs, and both are idempotent — a re-sync reconciles rather than recreates. What that means for you is that a tenant whose realm or Vault entries are missing is a failed Job, not a missing step: check the Jobs in the tenant's namespace and in the Vault namespace before adding anything manually.
Three things to confirm before handing the tenant over:
- The realm exists and you can sign in to it — see Verify the Deployment.
- The tenant's
<tenant>-oauth2-proxy-secretentry exists in Vault with all five values; without it, users cannot sign in. - The tenant administrator has what they need: the Keycloak host, their realm administrator credentials, and the tenant's OLIVE address. Reusing a tenant name whose Vault and Keycloak state was never cleaned up is the usual cause of an onboarding that half-succeeds — see Uninstall and Teardown.
The tenant administrator account and its initial password
The keycloak-setup Job creates one administrator account in the new realm, and the realm is named after the tenant:
| Username | <tenant>_admin |
| Realm | <tenant> |
| Realm roles | admin, editor |
| Keycloak permissions | realm-management: realm-admin — full administration of this realm, and no access to any other |
| Password | Generated by the Job, 24 random characters, flagged temporary |
The generated password is written to Vault, which is where you retrieve it in order to hand it over:
kubectl exec -it <vault-pod> -n <vault-namespace> -- \
vault kv get secret/shared-secrets-<tenant>/keycloak-credentials-<tenant>
The entry holds two fields, username and password.
The account is created with the required action Update Password, so the value from Vault works for exactly one sign-in and the tenant administrator then chooses their own. Nothing writes that new password back, so from the first sign-in onwards the Vault entry is a record of what was issued, not the current credential.
If a tenant administrator loses access later, the answer is a password reset in Keycloak — by you in the master console, or by another administrator of that realm — not a look in Vault.
The Job generates and stores the password only when it imports the realm. A realm that was created by an earlier run, or by hand, can therefore exist with nothing at that Vault path — and the password cannot be reconstructed, because the realm stores only a hash. The Job says so in its log rather than failing the sync, so a tenant that is otherwise green can still be a tenant nobody can administer. Retrieve the credential as part of onboarding rather than when the tenant administrator first asks for it.
This is recoverable. As platform administrator you hold the Keycloak master administrator credential, which administers every realm on the server: sign in to the tenant's realm with it, reset the password of <tenant>_admin — leaving Temporary on, so the tenant administrator sets their own at first sign-in — and store the new value at the path above. The same route repairs anything else the realm needs after an unusual onboarding.
Keep it a recovery action rather than a habit:
- The master credential is yours. It is never handed to a tenant administrator — their
realm-adminrights in their own realm are what they need, and the master account would give them every other tenant as well. - Prefer a password reset over editing the realm by hand. The realm's clients, roles and groups are reconciled by the chart on every sync, so a manual change to them is either redundant or will be overwritten.
- Interventions are recorded. Admin events are enabled on every realm by the onboarding Job, so what you change in a tenant realm is auditable — which is the point of using the account deliberately and rarely.
What to hand over to the tenant administrator
Four things, none of which the tenant administrator can discover alone:
| What | Value |
|---|---|
| Their realm | <tenant> |
| Keycloak realm console | https://<keycloak-host>/admin/<tenant>/console/ |
| Initial credentials | <tenant>_admin and the password from Vault, to be changed at first sign-in |
| The tenant's OLIVE address | https://<tenant>.<cluster>.<domain> — where their users sign in |
The Keycloak host is global.keycloakBaseURL, or https://authenticate.<cluster>.<domain> when that value is not set.
Link them to Managing Users — Procedures, and point out that the realm has no SMTP server configured, so the credential-reset email they would normally send to a new user does not work until they configure one.
<tenant>_admin holds admin and editor together, which is convenient for setting a tenant up and wrong for running it. Tell the tenant administrator to create separate accounts for daily work — see Administrative accounts are not for daily use.
Development vs. Production Deployments
The deployment environment significantly impacts how tenants are configured and deployed:
-
Development Deployments use a single-tenant architecture with simplified configuration (no authentication required). Refer to Development Environment Deployment for architectural details and Development Environment Values for configuration examples.
-
Production Deployments use a multi-tenant architecture with shared stateless resources and dedicated per-tenant storage, authentication via Keycloak, and role-based access control. Refer to Production Environment Deployment for architectural details and Production Configuration for deployment examples.
Regardless of the deployment type, all tenants (both development and production) require the foundational OLIVE connectivity bundle for the corresponding platform version to be imported to ensure proper platform integration and functionality.
Removing a Tenant
To remove a tenant from the platform:
- Remove infrastructure entry: Simply remove the tenant entry from the infrastructure Git repository.
- Data considerations: Export the tenant's content first — the storage goes with the namespace.
- Clean up what the deployment does not own: the tenant's Vault policies, auth roles and KV data, and its Keycloak realm, are not removed with the deployment. Reusing the tenant name without cleaning them up is the usual cause of a tenant that onboards halfway and then fails on every retry.
Uninstall and Teardown covers all of this in detail, including removing the whole platform.
Resource Scaling
When adding or removing tenants, pay attention to monitoring infrastructure resources. Certain services may need to be scaled higher or lower based on the new tenant configuration:
- Adding tenants may require scaling up services to accommodate increased demand
- Removing tenants may allow you to scale down services if capacity is no longer needed
Refer to the Resource Scaling guide for detailed information on how to adjust resource allocations.