Organizing namespaces

Before you start

• You understand the tenancy model — every namespace must start with your tenant prefix.
• You know that all namespaces in a tenant share a single ResourcePool — splitting namespaces does not split quota.

The prefix rule

Every namespace inside your tenant must be named <your-tenant>-*. If your tenant is def-profname, a namespace called experiments is rejected at admission time; def-profname-experiments is allowed.

This is enforced by Capsule’s forceTenantPrefix: true setting — the admission webhook rejects non-prefixed names regardless of whether the request comes from kubectl, ArgoCD, or a CI pipeline. See Known limitations for the full rule.

Naming conventions

Pick names that describe the workload stage or logical boundary:

<your-tenant>-prod
<your-tenant>-staging
<your-tenant>-experiments
<your-tenant>-batch
<your-tenant>-notebooks

Keep names lowercase, use hyphens as separators, and stay under the Kubernetes 63-character limit for namespace names. The tenant prefix counts toward that limit.

When to split vs. single namespace

A single namespace is fine for most small-to-medium workloads. Split into multiple namespaces when you need:

• RBAC separation — different team members need different access levels (e.g. read-only on prod, full access on experiments).
• Network policy scoping — you want to restrict pod-to-pod traffic between workload groups within your tenant. See Network policies for the default rules.
• Logical organization — you want kubectl get pods to show only the workloads relevant to a specific project phase.

Splitting namespaces does not give you:

• Quota isolation — all namespaces pull from the same ResourcePool. A runaway Job in one namespace can exhaust the quota for the whole tenant.
• Priority class isolation — every namespace sees the same three priority classes (uber-user-significant, uber-user-preempt-medium, and uber-user-preempt-high).

If you need quota isolation between workload groups, you need separate tenants (backed by separate Cloud RAPs), not separate namespaces.

Creating a namespace

Tenant owners can create namespaces directly:

namespace.yaml

apiVersion: v1
kind: Namespace
metadata:
  name: <your-tenant>-experiments

kubectl apply -f namespace.yaml

Or inline:

kubectl create namespace <your-tenant>-experiments

If you use ArgoCD, you can also declare the namespace in your app-of-apps repo and let ArgoCD reconcile it. Both paths hit the same Capsule admission rule.

Labels and annotations

Capsule automatically applies the label capsule.clastix.io/tenant: <your-tenant> to every namespace in your tenant. This label drives the ResourcePool quota selector and the default network policy allow rules — do not remove or modify it.

You can add your own labels and annotations freely:

apiVersion: v1
kind: Namespace
metadata:
  name: <your-tenant>-prod
  labels:
    environment: production
    team: ml-pipeline
  annotations:
    description: "Production workloads for the ML pipeline"

Deleting a namespace

Tenant owners can delete namespaces they created:

kubectl delete namespace <your-tenant>-experiments

This deletes everything in the namespace — all Pods, Services, ConfigMaps, Secrets, PVCs, and any other resources. Kubernetes does not ask for confirmation; the delete is immediate and irreversible.

Deleting a namespace destroys all resources inside it

There is no undo. If you have PersistentVolumeClaims in the namespace, check the reclaim policy for your storage class before deleting — Delete (the default for csi-cinder-sc-delete) destroys the backing volume along with the PVC. Use csi-cinder-sc-retain if you need the backing volume to survive PVC deletion.

Deleting the tenant itself (the Capsule Tenant resource) is a different operation — it is blocked by preventDeletion: true and requires an RCS procedure. See Known limitations.