A tenant requests a Grafana instance. After review, the template creates a new tenant namespace and a Capsule GlobalTenantResource that distributes the Flux repository, HelmRelease, and execution permissions into it. For tenant solar and instance main, the namespace is solar-grafana-main.

See Capsule’s GlobalTenantResources documentation for how the distributor selects tenant namespaces and reconciles generated resources. The permit controls the initial provisioning and its own cleanup policy.

Prerequisites

Install Capsule, Resource Permits, and Flux’s source and Helm controllers. Use an existing namespace solar-system owned by tenant solar, with the tenant label and default ServiceAccount. The requester needs ResourcePermit permissions there; the reviewer needs status-update permission and must match the template’s approvers. Change kubernetes-admin and admin to your actual reviewer identities.

The template executes as capsule in capsule-system so Capsule can assign ownership of the new namespace. Adapt that reference if your Capsule installation uses a different controller ServiceAccount. The generated distributor uses a separate permit-example-reconciler identity. Install the supporting permissions first:

# The permit controller already has namespace and GlobalTenantResource lifecycle
# permissions. This identity executes only the generated distributors.
apiVersion: v1
kind: ServiceAccount
metadata:
  name: permit-example-reconciler
  namespace: capsule-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: playground-permit-example-reconciler
rules:
  - apiGroups: [""]
    resources: ["serviceaccounts"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: ["rbac.authorization.k8s.io"]
    resources: ["rolebindings"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: ["rbac.authorization.k8s.io"]
    resources: ["clusterroles"]
    resourceNames: ["playground-gateway-api-editor", "playground-grafana-reconciler"]
    verbs: ["get", "bind"]
  - apiGroups: ["source.toolkit.fluxcd.io"]
    resources: ["helmrepositories"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: ["helm.toolkit.fluxcd.io"]
    resources: ["helmreleases"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: playground-permit-example-reconciler
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: playground-permit-example-reconciler
subjects:
  - kind: ServiceAccount
    name: permit-example-reconciler
    namespace: capsule-system
---
# Bind only with tenant namespace RoleBindings: this grants namespaced Gateway
# API CRs while GatewayClasses and CRD definitions stay under platform control.
# The Gateway API CRDs/controller are installed separately.
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: playground-gateway-api-editor
rules:
  - apiGroups: ["gateway.networking.k8s.io"]
    resources: ["*"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete", "deletecollection"]
---
# Flux receives this role only through a RoleBinding in each Grafana namespace.
# The chart's optional Kubernetes RBAC and dashboard sidecars are disabled.
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: playground-grafana-reconciler
rules:
  - apiGroups: [""]
    resources: ["configmaps", "secrets", "services", "serviceaccounts", "persistentvolumeclaims", "pods"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: ["apps"]
    resources: ["deployments", "replicasets", "statefulsets"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: ["batch"]
    resources: ["jobs"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

Download platform/globalresourcepermittemplates/rbac.yaml

These shared example permissions also include the Gateway API role used by the Gateway API walkthrough.

Define the template

Choose a new instance name for every request. The template derives the tenant from the request namespace rather than accepting a tenant name as a parameter. Its ConfigMap, Secret, and workload permissions belong to the Flux executor in the new namespace. Grafana persistence is disabled in this demonstration.

# Creates a tenant namespace, then uses GlobalTenantResource to place Flux
# resources in it. Directly creating a HelmRelease in a nonexistent namespace
# would fail the ResourcePermit's server-side dry run.
apiVersion: addons.projectcapsule.dev/v1beta2
kind: GlobalResourcePermitTemplate
metadata:
  name: grafana
  labels:
    company.com/consumer: "tenants"
  annotations:
    info.projectcapsule.dev/description: "Provision a managed Grafana instance in a new namespace belonging to the requesting tenant."
    info.projectcapsule.dev/tags: "grafana,monitoring,flux"
    info.projectcapsule.dev/icon: "https://p1.hiclipart.com/preview/950/813/299/github-logo-grafana-influxdb-dashboard-visualization-web-application-installation-data-plugin-png-clipart.jpg"
spec:
  # Capsule recognizes its controller as an administrator and adds the Tenant
  # ownerReference during namespace admission. A generic execution SA cannot.
  impersonation:
    name: capsule
    namespace: capsule-system
  namespaceSelectors:
    - matchExpressions:
        - key: capsule.clastix.io/tenant
          operator: Exists
  # No default duration: the instance stays managed until the permit is expired.
  approvals:
    auto: false
    approvers:
      - kind: User
        name: kubernetes-admin
      - kind: User
        name: admin
  paramSchema:
    type: object
    additionalProperties: false
    required:
      - instance
    properties:
      instance:
        type: string
        title: Instance name
        description: "Creates <tenant>-grafana-<instance>; choose a new name for each instance."
        pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
        maxLength: 20
  context:
    resources:
      - apiVersion: v1
        kind: ServiceAccount
        name: default
        index: localServiceAccount
        optional: false
      - apiVersion: v1
        kind: Namespace
        index: tenantNamespaces
        selector:
          matchExpressions:
            - key: capsule.clastix.io/tenant
              operator: Exists
  resources:
    - policy:
        creation: Owner
        # Capsule must be able to update the namespace's tenant metadata.
        protect: false
        force: false
        deletion: Remove
      template: |-
        {{- $source := (index $.context.resources.localServiceAccount 0).metadata.namespace }}
        {{- $sourceNamespace := mustGetResourceByName $source $.context.resources.tenantNamespaces }}
        {{- $tenant := index $sourceNamespace.metadata.labels "capsule.clastix.io/tenant" }}
        {{- $namespace := printf "%s-grafana-%s" $tenant $.params.instance }}
        {{- if gt (len $namespace) 63 }}
        {{- fail "the tenant name plus '-grafana-' plus instance must fit in 63 characters" }}
        {{- end }}
        ---
        apiVersion: v1
        kind: Namespace
        metadata:
          name: {{ $namespace | quote }}
          labels:
            capsule.clastix.io/tenant: {{ $tenant | quote }}
        ---
        apiVersion: capsule.clastix.io/v1beta2
        kind: GlobalTenantResource
        metadata:
          name: {{ $namespace | quote }}
        spec:
          scope: Namespace
          resyncPeriod: 60s
          pruningOnDelete: true
          serviceAccount:
            name: permit-example-reconciler
            namespace: capsule-system
          tenantSelector:
            matchLabels:
              kubernetes.io/metadata.name: {{ $tenant | quote }}
          resources:
            - namespaceSelector:
                matchLabels:
                  kubernetes.io/metadata.name: {{ $namespace | quote }}
              rawItems:
                - apiVersion: v1
                  kind: ServiceAccount
                  metadata:
                    name: grafana-reconciler
                    namespace: {{ $namespace | quote }}
                - apiVersion: rbac.authorization.k8s.io/v1
                  kind: RoleBinding
                  metadata:
                    name: grafana-reconciler
                    namespace: {{ $namespace | quote }}
                  roleRef:
                    apiGroup: rbac.authorization.k8s.io
                    kind: ClusterRole
                    name: playground-grafana-reconciler
                  subjects:
                    - kind: ServiceAccount
                      name: grafana-reconciler
                      namespace: {{ $namespace | quote }}
                - apiVersion: source.toolkit.fluxcd.io/v1
                  kind: HelmRepository
                  metadata:
                    name: grafana
                    namespace: {{ $namespace | quote }}
                  spec:
                    interval: 24h
                    url: https://grafana-community.github.io/helm-charts
                - apiVersion: helm.toolkit.fluxcd.io/v2
                  kind: HelmRelease
                  metadata:
                    name: grafana
                    namespace: {{ $namespace | quote }}
                  spec:
                    interval: 10m
                    timeout: 5m
                    releaseName: grafana
                    targetNamespace: {{ $namespace | quote }}
                    serviceAccountName: grafana-reconciler
                    chart:
                      spec:
                        chart: grafana
                        version: "13.2.2"
                        sourceRef:
                          kind: HelmRepository
                          name: grafana
                        interval: 24h
                    install:
                      remediation:
                        retries: -1
                    upgrade:
                      remediation:
                        retries: 3
                    driftDetection:
                      mode: enabled
                    values:
                      fullnameOverride: grafana
                      replicas: 1
                      rbac:
                        create: false
                      automountServiceAccountToken: false
                      service:
                        type: ClusterIP
                      persistence:
                        enabled: false
                      resources:
                        requests:
                          cpu: 100m
                          memory: 128Mi
                        limits:
                          cpu: 500m
                          memory: 512Mi

Download platform/globalresourcepermittemplates/managed-grafana.yaml

Apply the supporting permissions and template as a platform operator, then wait:

kubectl apply -f playground/manifests/platform/globalresourcepermittemplates/rbac.yaml
kubectl apply -f playground/manifests/platform/globalresourcepermittemplates/managed-grafana.yaml
kubectl wait --for=condition=Ready globalresourcepermittemplate/grafana --timeout=60s

Request an instance

apiVersion: addons.projectcapsule.dev/v1beta2
kind: ResourcePermit
metadata:
  name: managed-grafana
  namespace: solar-system
spec:
  template:
    kind: GlobalResourcePermitTemplate
    name: grafana
  reason: Provision a managed Grafana instance for the solar tenant.
  params:
    instance: main

Download user/solar/resourcepermits/managed-grafana.yaml

Submit the permit as the tenant requester. A configured approver reviews it with kubectl resource-permits review managed-grafana -n solar-system. See the review guide for CLI installation and approval options.

Expected outcome and cleanup

Once the permit is active, Capsule distributes the Flux resources and Flux installs Grafana. Permit activation and HelmRelease readiness are separate: inspect both the permit’s conditions and the HelmRelease in solar-grafana-main.

No default duration is set, so the instance stays managed until the permit is expired or deleted. Its deletion: Remove policy removes the namespace and distributor on cleanup, including the namespace’s contents. Use a dedicated instance namespace.