Tenant System
Introduction
A tenant in Cozystack is the primary unit of isolation and security, analogous to a Kubernetes namespace but with enhanced scope. Each tenant represents an isolated environment with its own resources, networking, and RBAC (role-based access control). Some cloud providers use the term “projects” for a similar entity.
Cozystack administrators and users create tenants using the
Tenant application
from the application catalog.
Tenants can be created via the Cozystack dashboard (UI), kubectl
, or directly via Cozystack API.
Tenant Nesting
All user tenants belong to the base root
tenant.
This root
tenant is used only to deploy user tenants and system components.
All user-side applications are deployed in their respective tenants.
Tenants can be nested further: an administrator of a tenant can create sub-tenants as applications in the Cozystack catalog. Parent tenants can share their resources with their children and oversee their applications. In turn, children can use their parent’s services.
Sharing Cluster Services
Lower-level tenants can access the cluster services of their parent in case they do not run their own.
The root
tenant has a set of services like etcd
, ingress
, and monitoring
by default.
User can can create a tenant foo
inside of tenant root
and a nested tenant bar
inside of foo
.
Let’s see what happens when
tenant Kubernetes and
Postgres applications run under the bar
namespace.
Since tenant bar
does not have its own cluster services like ingress
and monitoring
,
the applications will use the cluster services of the parent tenant foo
.
This in turn means:
- The tenant Kubernetes cluster data will be stored in the
bar
tenant’s own etcd. - All metrics will be collected in the monitoring stack of the parent tenant
foo
. - Access to the cluster will be through the common ingress deployed in the tenant
root
.
Unique Domain Names
Each tenant has its own domain.
By default, (unless otherwise specified), it inherits the domain of its parent with a prefix of its name.
For example, if the root
tenant has domain example.org
, then tenant foo
gets the domain foo.example.org
by default.
However, it can be redefined to have another domain, such as example.com
.
Kubernetes clusters created in this tenant namespace would get domains like: kubernetes-cluster.foo.example.org
Tenant Naming Limitations
Tenant names must be alphanumeric.
Using dashes (-
) in tenant names is not allowed, unlike with other services.
This limitation exists to keep consistent naming in tenants, nested tenants, and services deployed in them.
For example:
- The root tenant is named
root
, but internally it’s referenced astenant-root
. - A user tenant is named
foo
, which results intenant-foo
. - However, a tenant cannot be named
foo-bar
, because parsing names liketenant-foo-bar
can be ambiguous.
Reference
See the reference for the application implementing tenant management:
tenant