Tenant Management

KSail can generate multi-tenancy manifests for platform teams that need to onboard workload teams onto a shared cluster. Each tenant gets namespace isolation, RBAC, and optional GitOps sync resources.

Tenant Types

Type	RBAC	GitOps sync resources	Requires GitOps engine
flux	✓	OCIRepository / GitRepository + Kustomization	Flux
argocd	✓	AppProject + Application	ArgoCD
kubectl	✓	None	No

The --type flag defaults to auto-detect from ksail.yaml gitOpsEngine.

Create a Tenant

# Auto-detect type (reads gitOpsEngine from ksail.yaml)
ksail tenant create my-team

# Explicit type
ksail tenant create my-team --type flux

# Custom namespace(s) — default is the tenant name
ksail tenant create my-team --namespace my-team --namespace my-team-staging

# Custom ClusterRole — default is 'edit'
ksail tenant create my-team --cluster-role view

# Output to a specific directory
ksail tenant create my-team --output platform/tenants/

The command writes manifests to <output>/<tenant-name>/:

platform/tenants/my-team/
├── kustomization.yaml
├── namespace.yaml
├── serviceaccount.yaml
├── rolebinding.yaml
└── (flux or argocd sync resources if applicable)

Register in kustomization.yaml

Add --register to automatically append the tenant to the nearest kustomization.yaml:

ksail tenant create my-team --register

Deliver via Pull Request

Use --delivery pr to deliver platform changes as a pull request against the platform repo:

ksail tenant create my-team --register --delivery pr \
  --git-provider github

The platform repo is auto-detected from the local git remote origin. Override with --platform-repo:

ksail tenant create my-team --register --delivery pr \
  --git-provider github \
  --platform-repo my-org/platform-repo

Set the PR target branch with --target-branch (defaults to the repo’s default branch):

ksail tenant create my-team --register --delivery pr \
  --git-provider github \
  --target-branch develop

Flux Tenants

For Flux tenants, specify the sync source type and registry or Git repo:

# OCI source (default)
ksail tenant create my-team --type flux \
  --sync-source oci \
  --registry oci://ghcr.io/my-org

# Git source
ksail tenant create my-team --type flux \
  --sync-source git \
  --git-provider github \
  --tenant-repo my-org/my-team-infra

To scaffold a new Git repository for the tenant (requires --git-provider github):

ksail tenant create my-team --type flux \
  --sync-source git \
  --git-provider github \
  --tenant-repo my-org/my-team-infra

KSail resolves the GitHub token automatically using the following fallback chain:

1. --git-token flag (highest priority)
2. GH_TOKEN or GITHUB_TOKEN environment variable
3. GitHub CLI config (e.g., from gh auth login)

If no token can be resolved through any of these sources, repo scaffolding is skipped with a warning and the command succeeds. In CI, ensure a non-empty token is available via --git-token, GH_TOKEN, or GITHUB_TOKEN if you want scaffolding to run. Only ksail tenant delete --delete-repo fails when no token can be resolved.

Pass --git-token explicitly only when you need to override the auto-detected token:

ksail tenant create my-team --type flux \
  --git-provider github \
  --tenant-repo my-org/my-team-infra \
  --git-token "${MY_BOT_TOKEN}"

ArgoCD Tenants

ArgoCD tenants generate RBAC isolation manifests, an AppProject, and an Application:

ksail tenant create my-team --type argocd \
  --git-provider github \
  --tenant-repo my-org/my-team-infra

platform/tenants/my-team/
├── kustomization.yaml
├── namespace.yaml
├── serviceaccount.yaml
├── rolebinding.yaml
├── project.yaml
└── app.yaml

Add --register to also merge the tenant RBAC policy into the shared argocd-rbac-cm ConfigMap:

ksail tenant create my-team --type argocd \
  --git-provider github \
  --tenant-repo my-org/my-team-infra \
  --register

KSail scans the kustomization directory for an argocd-rbac-cm ConfigMap (by content, not filename). If found, it merges the tenant policy. If not found, it creates argocd-rbac-cm.yaml in the same directory and registers it in kustomization.yaml.

kubectl Tenants

kubectl tenants generate RBAC-only platform manifests (no GitOps sync resources). When --git-provider github and --tenant-repo are provided, KSail also scaffolds a tenant repository without GitOps-specific resources — provided a GitHub token can be resolved (see the token resolution fallback chain above). If no token is available, the command still succeeds and only the local platform manifests are generated:

ksail tenant create my-team --type kubectl

# With repo scaffolding
ksail tenant create my-team --type kubectl \
  --git-provider github \
  --tenant-repo my-org/my-team-manifests

The scaffolded repo contains a plain kustomize setup for manual workflows:

/
├── README.md
└── k8s/
    └── kustomization.yaml

The tenant applies their manifests with kubectl apply -k k8s/.

Delete a Tenant

# Remove manifests and unregister from kustomization.yaml (default)
ksail tenant delete my-team

# Also delete the tenant Git repository (token resolved automatically;
# requires a valid token from the fallback chain above)
ksail tenant delete my-team --delete-repo \
  --git-provider github \
  --tenant-repo my-org/my-team-infra

# Keep kustomization.yaml entry
ksail tenant delete my-team --unregister=false

ArgoCD RBAC Cleanup

When deleting an ArgoCD tenant, KSail automatically removes the tenant’s policy entries from the argocd-rbac-cm ConfigMap. It scans YAML files in the output directory for a ConfigMap named argocd-rbac-cm (content-based detection, not filename-based) and removes lines belonging to the deleted tenant. If no RBAC ConfigMap file is found, the step is silently skipped.

Applying Tenant Manifests

After generating manifests, apply them to the cluster using the workflow that matches how the tenant was created:

# If you created the tenant without --register,
# apply the generated tenant directory directly
ksail workload apply -k platform/tenants/my-team/

# If you created the tenant with --register, or platform/tenants/kustomization.yaml
# already includes the tenant directory, apply the parent directory
ksail workload apply -k platform/tenants/

Or if using GitOps, push and reconcile:

ksail workload push
ksail workload reconcile

CLI Reference

• ksail tenant create — all flags and defaults
• ksail tenant delete — all flags and defaults