Skip to content
SHC Docs

Tenants

A tenant is the boundary around deployments, secrets and users. Each tenant has its own filesystem tree, its own overlay network and its own Keycloak realm. The app ladder left tenant prod selected and master holding the platform apps.

home01
$ shc tenant ls
ACTIVE NAME DEPLOYMENTS
master 3
* prod 6
$ shc tenant info
NAME ACTIVE DEPLOYMENTS TOTAL DEPLOYMENTS RUNNING DEPLOYMENTS STOPPED DATA DIR CONFIG DIR
prod true 6 6 0 /var/lib/shc/deployments/prod /var/lib/shc/deployments/prod

shc tenant info with no name reads the active tenant: how many deployments it holds and where they live on disk.

Add two tenants. acme gets an admin user with a password you choose; lab gets no admin user. A tenant of your own needs a licence that includes tenancy: shc license status lists tenancy among its features. Without it shc tenant add is refused with X403029LICENT.

home01
$ shc tenant add acme --admin-user owner --admin-password P@ssw0rd
✔ created tenant "acme" with admin user "owner"
the admin password is in tenant acme's vault as keycloak_admin_password
warning: keycloak realm and admin user "owner" provisioning still in progress
$ shc tenant add lab --no-admin
✔ created tenant "lab"
warning: keycloak realm provisioning still in progress
$ shc tenant ls
...

Without --admin-password the admin’s password is generated and sealed in the vault. Realm provisioning finishes in the background.

Adding a tenant does not select it: every command still reads prod. A tenant is named per command with -t, or the context is pointed at it with shc ctx -t, the one way to select a tenant. Point it at acme and install the nginx directory from the first app page there. The deployment is named web, like the one in prod: a name is unique within a tenant, not across them.

home01
$ shc ctx -t acme
...
$ shc ls
...
$ shc install ~/learn/nginx -s web --expose 18081=nginx:80
installing deployment "web"
[web] Healthy 1/1
✔ nginx healthy
✔ installed deployment "web"
exposure: lan
home01
$ shc ls
STACK TENANT ENV APP STATUS NODE
web acme prod /root/learn/nginx running home01
$ shc ls -t prod
STACK TENANT ENV APP STATUS NODE
cloud prod prod nextcloud running home01
db prod prod postgres running home01
pgweb prod prod /root/learn/pgweb running home01
placed prod prod notes running home01
store prod prod /root/learn/versitygw running home01
web prod prod /root/learn/nginx running home01
$ shc ls --all-tenants
STACK TENANT ENV APP STATUS NODE
web acme prod /root/learn/nginx running home01
keycloak master default keycloak running home01
postgres master default postgres running home01
traefik master default traefik running home01
cloud prod prod nextcloud running home01
db prod prod postgres running home01
pgweb prod prod /root/learn/pgweb running home01
placed prod prod notes running home01
store prod prod /root/learn/versitygw running home01
web prod prod /root/learn/nginx running home01
$ shc tenant info acme
NAME ACTIVE DEPLOYMENTS TOTAL DEPLOYMENTS RUNNING DEPLOYMENTS STOPPED DATA DIR CONFIG DIR
acme true 1 1 0 /var/lib/shc/deployments/acme /var/lib/shc/deployments/acme

-t names a tenant for one command without switching. --all-tenants lists every tenant’s deployments in one table. A name that is no tenant is refused: shc tenant info on a missing name does not read as an empty tenant.

home01
$ shc tenant info nosuch
shc: [X404973TNTNXS] tenant nosuch does not exist, run `shc tenant ls` to list the tenants on this estate, or `shc tenant add nosuch` to create it

A tenant that still holds a deployment cannot be removed, and --force does not change that.

home01
$ shc tenant rm acme --yes --force
shc: [X400958TNTREQ] tenant acme has 1 deployment to uninstall first
$ shc uninstall web --yes
uninstalling deployment "web"
[web] Complete 4/4
✔ remove from home01
✔ take the safety backup
✔ leave every node's service VIP table
✔ tear down
✔ uninstalled deployment "web"
$ shc tenant rm acme --yes
✔ removed tenant "acme"
$ shc tenant rm lab --yes
✔ removed tenant "lab"
$ shc ctx -t prod
...
home01
$ shc tenant ls
ACTIVE NAME DEPLOYMENTS
master 3
* prod 6
$ shc ls
STACK TENANT ENV APP STATUS NODE
cloud prod prod nextcloud running home01
db prod prod postgres running home01
pgweb prod prod /root/learn/pgweb running home01
placed prod prod notes running home01
store prod prod /root/learn/versitygw running home01
web prod prod /root/learn/nginx running home01

A tenant can be given quotas: caps on CPU, memory, disk and counts, read and set per scope. shc quota scan measures the disk a deployment uses and records it. The Pro licence the app ladder installed carries the feature.

home01
$ shc quota status
...
$ shc quota set --scope tenant --cpu 4 --memory 8G --disk 50G --max-deployments 10 --max-apps 10 --max-environments 2 --max-vdeployments 10
✔ set 7 quota limits at tenant scope
$ shc quota status
...
$ shc quota scan -s web -e prod
...
$ shc quota unset --scope tenant --cpu --memory --disk --max-deployments --max-apps --max-environments --max-vdeployments
✔ removed 7 quota limits at tenant scope
$ shc quota status
...

The cluster can also be registered with the vendor Portal, an outbound channel for heartbeats and install dispatches; a code from the Portal dashboard opts it in, and status reads the registration either way.

home01
$ shc portal status
...
explained, not walked: --all unsets what the line above unset one by one, and a Portal code comes from an account this walk has none of
$ shc quota unset --scope tenant --all
$ shc portal register PTL-4X9Q-72KM
$ shc portal deregister --local

shc tenant and shc portal typed alone answer for the whole group.

home01
$ shc tenant
...
$ shc portal
...

Removing a tenant drops its realm and its tree. The context still named acme, so shc ctx -t prod selects prod again. The cluster is back to master and prod, with prod selected, no quota set and prod’s deployments running.

Next: Environments.