Skip to content

Kubernetes RBAC

The portal connects to Service Provider Control Planes Kubernetes APIs and requires specific RBAC permissions. This page documents the minimum required permissions for the system service account used by the portal.

Core API Resources

Namespaces

Verbs Purpose
get Check if an organization namespace already exists before creating it.
list Connection health check when testing control plane connectivity.
create Auto-create organization namespaces on first use. Labels and annotations with billing and organization metadata are set on creation.
patch Sync billing metadata (labels and annotations) to existing namespaces via the sync_billing_metadata management command.

Secrets

Verbs Purpose
get Read connection credentials (writeConnectionSecretToRef) for service instances.

Pods

Verbs Purpose
list Display pod status information on the service instance detail page.

Pods/log

Verbs Purpose
get Retrieve container logs for individual pods. Used by the pod logs viewer and log download feature on the service instance detail page.

Events

Verbs Purpose
list Display Kubernetes events related to a service instance.

PersistentVolumeClaims

Verbs Purpose
list Display PVC status and capacity on the service instance detail page.

Nodes/proxy (optional)

Verbs Purpose
get Query kubelet stats API for actual disk usage percentages. If not granted, PVC information is still shown but without usage data.

Metrics API (metrics.k8s.io, optional)

Pods

Verbs Purpose
list Fetch per-pod CPU and memory usage from the metrics server. Displayed alongside pod status in the Technical Details section. If not granted, pods are still shown but without resource usage data.

API Extensions (apiextensions.k8s.io)

CustomResourceDefinitions

Verbs Purpose
get Fetch CRD OpenAPI schemas for dynamic form generation.
list Fallback discovery when a CRD cannot be found by direct name lookup.

Custom Resources (dynamic)

The portal manages service instances as Kubernetes custom resources. The exact API groups and resource types depend on the configured ServiceDefinition objects (for example vshn.appcat.vshn.io).

Verbs Purpose
get Fetch the current state of a service instance.
create Provision a new service instance.
patch Update the spec or billing annotations of a service instance.
delete Deprovision a service instance.

Backup Resources (optional)

Required only for backup visibility and direct backup access. Without these, the backup sections on the instance detail page are hidden or show "currently unavailable".

API group Resource Verbs Purpose
k8up.io snapshots list List backups of K8up-based services (Redis, MariaDB, Nextcloud files, Codey).
k8up.io schedules list Discover endpoint, bucket and credential secrets for direct backup access.
postgresql.cnpg.io backups list List backups of PostgreSQL instances.
postgresql.cnpg.io clusters list Derive the Barman server name for direct backup access.
barmancloud.cnpg.io objectstores list Discover endpoint, bucket and credential secrets for direct backup access.

The credential secrets themselves are read with the existing secrets get permission.

API Discovery

The portal calls the Kubernetes discovery endpoint /apis/{group}/{version} to resolve resource plural names. This is typically permitted for any authenticated identity, but should be verified when using restrictive RBAC setups.

Example ClusterRole

The following ClusterRole provides the minimum permissions the portal needs. Adjust the custom resource API groups to match your configured service definitions.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: servala-portal
rules:
  # Namespaces
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get", "list", "create", "patch"]

  # Secrets (connection credentials)
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get"]

  # Pods (status display and log access)
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["list"]
  - apiGroups: [""]
    resources: ["pods/log"]
    verbs: ["get"]

  # Events (instance events)
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["list"]

  # PersistentVolumeClaims (disk usage)
  - apiGroups: [""]
    resources: ["persistentvolumeclaims"]
    verbs: ["list"]

  # Node proxy (optional: disk usage stats)
  - apiGroups: [""]
    resources: ["nodes/proxy"]
    verbs: ["get"]

  # Pod metrics (optional: CPU/memory usage display)
  - apiGroups: ["metrics.k8s.io"]
    resources: ["pods"]
    verbs: ["list"]

  # CRD schemas
  - apiGroups: ["apiextensions.k8s.io"]
    resources: ["customresourcedefinitions"]
    verbs: ["get", "list"]

  # Backup resources (optional: backup visibility and direct backup access)
  - apiGroups: ["k8up.io"]
    resources: ["snapshots", "schedules"]
    verbs: ["list"]
  - apiGroups: ["postgresql.cnpg.io"]
    resources: ["backups", "clusters"]
    verbs: ["list"]
  - apiGroups: ["barmancloud.cnpg.io"]
    resources: ["objectstores"]
    verbs: ["list"]

  # Custom resources, one rule per service API group
  - apiGroups: ["vshn.appcat.vshn.io"]
    resources: ["*"]
    verbs: ["get", "create", "patch", "delete"]
  # Add additional apiGroups for other service definitions