Skip to content

ADR-013: Read-Only Client Access via Service Account

Status: Approved

Date: 2026-06-30

Decision

Clients receive read-only access to their control plane through a Kubernetes ServiceAccount and a generated kubeconfig. The primary read experience is Backstage. No Kubernetes API OIDC integration with the client's identity provider is provided in v1.

Rationale

  • Simple to implement and secure: standard Kubernetes RBAC with no external OIDC complexity
  • Avoids coupling Kubernetes API authentication to each client's identity provider
  • Backstage provides the curated read experience clients actually need
  • Easy to revoke by deleting the service account or rotating the token

Access Model

Experience Mechanism Purpose
Primary read Backstage UI Cluster resources, Hiroba claims, templates, documentation
Raw read access ServiceAccount kubeconfig Power users who need kubectl get for audit or debugging

Implementation

  1. Create a ClusterRole with read-only permissions across the client cluster (e.g., built-in view cluster role).
  2. Create a ServiceAccount per client in a dedicated namespace.
  3. Create a ClusterRoleBinding binding the service account to the read-only cluster role.
  4. Generate a kubeconfig containing the service account token.
  5. Deliver the kubeconfig to the client through a secure out-of-band channel.
  6. Document that the kubeconfig is read-only and should be treated as sensitive.

Restrictions

  • The service account has no write permissions.
  • It cannot access secrets or privileged namespaces (e.g., kube-system, ArgoCD admin secrets).
  • Token lifetime is bounded and rotation is documented in the runbook.

Scope

This access model applies to v1. Future versions may add OIDC-based kubectl access if clients require it.