Create a User Tenant and Configure Access

Tenants are the isolation mechanism in Cozystack. They are used to separate clients, teams, or environments. Each tenant has its own set of applications and one or more nested Kubernetes clusters. Tenant users have full access to their clusters. Optionally, you can configure quotas for each tenant to limit resource usage and prevent overconsumption.

To learn more about tenants, read the Core Concepts guide.

Prerequisites

You will need a running Cozystack installation. Follow the installation guide to deploy it.

During Talos installation for Cozystack, you should have obtained the kubeconfig file for your new cluster. This config was required during the bootstrap process. Keep it safe — it may be useful later for troubleshooting. However, for day-to-day operations, you’ll want to create user-specific credentials.

Make sure you can access the dashboard, as described in the installation guide.

If you’re using OIDC, users and roles must be configured. See the OIDC guide for details on how to work with the built-in OIDC server.

Create a Tenant

Tenants are created using the Cozystack application named Tenant. After installation, Cozystack includes a built-in tenant called tenant-root. This root tenant is reserved for platform administrators and should only be used to create child tenants. Although it’s technically possible to install applications in tenant-root, doing so is not recommended for production environments.

• Using Dashboard
• Using kubectl

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: tenant-team1
  namespace: tenant-root
spec:
  chart:
    spec:
      chart: tenant
      reconcileStrategy: Revision
      sourceRef:
        kind: HelmRepository
        name: cozystack-apps
        namespace: cozy-public
      version: 1.9.1
  interval: 0s
  values:
    etcd: true
    host: team1.example.org
    ingress: true
    isolated: true
    monitoring: false
    resourceQuotas: {}
    seaweedfs: false

# Use the kubeconfig for the root tenant
export KUBECONFIG=./kubeconfig-tenant-root
# Apply the manifest
kubectl -n tenant-root apply -f hr-tenant-team1.yaml

You can assist tenant users with installing database applications or nested Kubernetes clusters. As an administrator, you can switch context in the dashboard to access any tenant. Tenant users, however, can only access their own tenant and any child tenants.

Get Tenant Kubeconfig

Tenant users need a kubeconfig file to access their Kubernetes cluster. The method to retrieve it depends on whether OIDC is enabled in your Cozystack setup.

With OIDC Enabled

You can retrieve the kubeconfig file directly from the dashboard, as described in the OIDC guide.

Without OIDC

As an administrator, you’ll need to retrieve a service account token from the tenant namespace. The secret holding the token has the same name as the tenant.

To retrieve the token for a tenant named team1, run:

kubectl -n tenant-team1 get secret tenant-team1 -o json | jq -r '.data.token | @base64d'

Next, insert this token into a kubeconfig template, and save the file as kubeconfig-tenant-<name>.yaml.

Make sure to also set the default namespace to the tenant name. Many GUI clients will display permission errors if the namespace is not explicitly defined.

The same token can also be used by the tenant user to log into the Cozystack dashboard if OIDC is disabled.

Get Nested Kubernetes Kubeconfig

In general, administrators do not need to retrieve kubeconfig files for nested Kubernetes clusters.

These clusters are installed by the tenant user, within their own tenant namespace. Tenant users have full control over their nested Kubernetes environments.

To access a nested Kubernetes cluster, the tenant user can download the kubeconfig file directly from the corresponding application’s page in the dashboard.