cozystack/packages/apps/tenant

Tenant

A tenant is the main unit of security on the platform. The closest analogy would be Linux kernel namespaces.

Tenants can be created recursively and are subject to the following rules:

Tenant naming

Tenant names must follow DNS-1035 naming rules:

• Must start with a lowercase letter (a-z)
• Can only contain lowercase letters, numbers, and hyphens (a-z, 0-9, -)
• Must end with a letter or number (not a hyphen)
• Maximum length depends on the cluster configuration (Helm release prefix and root domain)

Note: Using dashes (-) in tenant names is allowed but discouraged, unlike with other services. This is to keep consistent naming in tenants, nested tenants, and services deployed in them. Names with dashes (e.g., foo-bar) may lead to ambiguous parsing of internal resource names like tenant-foo-bar.

For example:

• The root tenant is named root, but internally it's referenced as tenant-root.
• A nested tenant could be named foo, which would result in tenant-foo in service names and URLs.

Unique domains

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 parent had the domain example.org, then tenant-foo would get the domain foo.example.org by default.

Kubernetes clusters created in this tenant namespace would get domains like: kubernetes-cluster.foo.example.org

Example:

tenant-root (example.org)
└── tenant-foo (foo.example.org)
    └── kubernetes-cluster1 (kubernetes-cluster1.foo.example.org)

Nesting tenants and reusing parent services

Tenants can be nested. A tenant administrator can create nested tenants using the "Tenant" application from the catalogue.

Higher-level tenants can view and manage the applications of all their children tenants. If a tenant does not run their own cluster services, it can access ones of its parent.

For example, you create:

• Tenant tenant-u1 with a set of services like etcd, ingress, monitoring.
• Tenant tenant-u2 nested in tenant-u1.

Let's see what will happen when you run Kubernetes and Postgres under tenant-u2 namespace.

Since tenant-u2 does not have its own cluster services like etcd, ingress, and monitoring, the applications running in tenant-u2 will use the cluster services of the parent tenant.

This in turn means:

• The Kubernetes cluster data will be stored in etcd for tenant-u1.
• Access to the cluster will be through the common ingress of tenant-u1.
• Essentially, all metrics will be collected in the monitoring from tenant-u1, and only that tenant will have access to them.

Example:

tenant-u1
├── etcd
├── ingress
├── monitoring
└── tenant-u2
    ├── kubernetes-cluster1
    └── postgres-db1

Parameters

Common parameters

Name	Description	Type	Value
host	The hostname used to access tenant services (defaults to using the tenant name as a subdomain for its parent tenant host).	string	""
etcd	Deploy own Etcd cluster.	bool	false
monitoring	Deploy own Monitoring Stack.	bool	false
ingress	Deploy own Ingress Controller.	bool	false
seaweedfs	Deploy own SeaweedFS.	bool	false
resourceQuotas	Define resource quotas for the tenant.	map[string]quantity	{}

Configuration

Resource Quotas

The resourceQuotas parameter allows you to limit resources available to the tenant. Supported keys include:

Compute resources (converted to requests.X and limits.X):

• cpu - Total CPU cores (e.g., "4" or "500m")
• memory - Total memory (e.g., "4Gi" or "512Mi")
• ephemeral-storage - Ephemeral storage limit (e.g., "10Gi")
• storage - Total persistent storage (e.g., "100Gi")

Object count quotas (passed as-is):

• pods - Maximum number of pods
• services - Maximum number of services
• services.loadbalancers - Maximum number of LoadBalancer services
• services.nodeports - Maximum number of NodePort services
• configmaps - Maximum number of ConfigMaps
• secrets - Maximum number of Secrets
• persistentvolumeclaims - Maximum number of PVCs

Example:

resourceQuotas:
  cpu: 4
  memory: 4Gi
  storage: 10Gi
  services.loadbalancers: "3"
  pods: "50"