ControlPlane API & Projector

The ControlPlane API and the Projector work together to give external clients — such as the Control Plane UI — read-only access to the platform's state. While the operators and custom resources remain the source of truth inside Kubernetes, these two components make that state available through a standard GraphQL API backed by a PostgreSQL database.

When do I need this?

If you only manage the Control Plane through kubectl and Rover-CTL, you do not strictly need these components. They become essential when you want to offer a web-based UI or any external tooling that queries the platform state without direct Kubernetes API access.

How They Work Together

• The Projector runs inside the Kubernetes cluster as a read-only controller. It watches custom resources (teams, applications, API exposures, subscriptions, approvals) and continuously projects their current state into PostgreSQL. It never writes back to the cluster.
• The ControlPlane API is a read-only GraphQL server that queries the same PostgreSQL database. It provides paginated, filterable access to all projected resources.

Neither component modifies the Kubernetes state. All mutations continue to flow through Rover-CTL, Rover Server, or kubectl.

Prerequisites

Before enabling the ControlPlane API and Projector, ensure you have:

• A running PostgreSQL instance — in production use a managed database service; the database component provides one for local development (see below)
• The Control Plane operators installed and running (see Installation)

Both components connect to the same database through the controlplane-db Secret. The Projector creates and manages the schema automatically on startup — no manual migration is needed.

Enabling in the local overlay

The local overlay includes the ControlPlane API, Projector, and an in-cluster PostgreSQL instance out of the box. No additional steps are needed — just deploy using the local overlay as described in the Quickstart:

kubectl apply -k install/overlays/local

The local overlay also:

• Includes the database component, which deploys a PostgreSQL pod with default credentials into the controlplane-system namespace
• Provides a pre-configured ControlPlane API config with the external listener's JWT auth set to mock and the GraphQL Playground enabled
• Sets all images to the latest tag with IfNotPresent pull policy

Enabling in the default overlay

The default overlay (install/overlays/default/kustomization.yaml) does not include the ControlPlane API and Projector by default — the relevant resource and image entries are present but commented out. The simplest way to enable them is to uncomment these lines directly in your copy of the overlay:

resources:
  # ...existing controllers...
  # Uncomment to enable the controlplane-api and projector:
  - https://github.com/telekom/controlplane//controlplane-api/config/default/?timeout=120&ref=v0.18.0
  - https://github.com/telekom/controlplane//projector/config/default/?timeout=120&ref=v0.18.0

# Uncomment to deploy an in-cluster PostgreSQL (development only):
components:
  - ../../components/database

images:
  # ...existing images...
  - name: ghcr.io/telekom/controlplane/controlplane-api
    newTag: v0.18.0
  - name: ghcr.io/telekom/controlplane/projector
    newTag: v0.18.0

Alternatively, if you prefer to keep the upstream overlay untouched, create a custom overlay in your own repository that builds on the bundle — the same pattern used for optional capabilities and other customisations. This bundle-based workflow requires Control Plane v0.22.0 or newer.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: controlplane-system

resources:
  - https://github.com/telekom/controlplane//install/bundle/?ref=v0.22.0
  - https://github.com/telekom/controlplane//controlplane-api/config/default/?timeout=120&ref=v0.22.0
  - https://github.com/telekom/controlplane//projector/config/default/?timeout=120&ref=v0.22.0

configMapGenerator:
  - name: controlplane-env
    literals:
      - FEATURE_PUBSUB_ENABLED=false
      - FEATURE_PERMISSION_ENABLED=false
      - FEATURE_AI_GATEWAY_ENABLED=false

images:
  - name: ghcr.io/telekom/controlplane/controlplane-api
    newTag: v0.22.0
  - name: ghcr.io/telekom/controlplane/projector
    newTag: v0.22.0

Database

Both components expect a Kubernetes Secret named controlplane-db with a url key containing the PostgreSQL connection string. For production, create this Secret with your managed database credentials:

apiVersion: v1
kind: Secret
metadata:
  name: controlplane-db
  namespace: controlplane-system
stringData:
  url: postgres://user:password@your-db-host:5432/controlplane?sslmode=require

For development or testing, you can include the database component instead, which deploys an in-cluster PostgreSQL and creates the Secret automatically:

components:
  - https://github.com/telekom/controlplane//install/components/database/?ref=v0.18.0

caution

The database component uses hardcoded credentials and is intended for development only. Always use a managed database service with secure credentials in production.

ControlPlane API configuration

The ControlPlane API reads its configuration from a ConfigMap named controlplane-api-config. When the custom overlay consumes the remote bundle, patch that generated ConfigMap:

patches:
  - target:
      kind: ConfigMap
      name: controlplane-api-config
    path: controlplane-api-config.yaml

Then create controlplane-api-config.yaml next to your overlay as a ConfigMap patch, with the configuration under data.config.yaml. This preserves the generated name hash and rolling restart behavior.

Security modes

The API authenticates incoming requests on its external listener. The listeners.external.jwt.mode field controls how:

Mode	JWT required	Signature validated	Use case
jwt	Yes	Yes	Production — full JWT validation against trusted issuers
mock	Yes	No	Local development / integration testing — JWT parsed but signature is not checked

The default mode is jwt (secure by default). A deployment in jwt mode with no trustedIssuers will panic at startup — fail-closed by design.

Production configuration

database:
  url: ${DATABASE_URL}

listeners:
  external:
    address: ":8443"
    jwt:
      mode: jwt
      trustedIssuers:
        - https://your-idp.example.com/realms/controlplane

The DATABASE_URL variable is injected from the controlplane-db Secret by the deployment manifest.

caution

mode: jwt requires at least one entry in trustedIssuers. The application will panic at startup if this is missing — fail-closed by design.

Development / local overlay configuration

database:
  url: ${DATABASE_URL}

listeners:
  external:
    address: ":8443"
    jwt:
      mode: mock

graphql:
  playgroundEnabled: true

warning

mode: mock accepts any JWT without validating its signature. Never use this in production.

Testing configuration

listeners:
  external:
    address: ":8443"
    jwt:
      mode: mock
      # No trustedIssuers needed — signatures are not validated

warning

mode: mock accepts JWTs without validating signatures. Only use for automated integration tests with controlled tokens.

Keycloak integration

To issue JWTs compatible with the ControlPlane API, configure Keycloak with the following protocol mappers:

Client setup

1. Create a confidential client in your Keycloak realm.
2. Enable Service Accounts for machine-to-machine authentication.
3. Add the protocol mappers below.

Required protocol mappers

Mapper name	Mapper type	Token claim name	Example value
env	Hardcoded claim	env	production
clientId	User Session Note	clientId	acme--platform--api-gateway
scope	Hardcoded claim	scope	tardis:admin:all

The clientId claim uses the format <group>--<team>--<service> and determines team-level access scoping. The scope claim controls the caller type (tardis:team:all, tardis:group:all, tardis:admin:all).

warning

When the tardis:* value (e.g. tardis:admin:all) is modeled as a Keycloak client scope, its Include in token scope setting must be enabled. If it is off, Keycloak omits the value from the scope claim and the caller is rejected or falls back to the default scope.

Legacy tardis:hub:* scopes remain accepted at runtime as deprecated aliases for the corresponding tardis:group:* scopes.

Example JWT payload

{
  "exp": 1719320400,
  "iat": 1719316800,
  "iss": "https://keycloak.example.com/realms/controlplane",
  "sub": "service-account-my-client",
  "env": "production",
  "clientId": "acme--platform--api-gateway",
  "scope": "tardis:admin:all"
}

Verify the deployment

After installation, verify that both components are running:

kubectl get pods -n controlplane-system | grep -E "projector|controlplane-api"

Check the Projector logs to confirm it is watching resources and syncing them into the database:

kubectl logs -l app.kubernetes.io/name=projector -n controlplane-system --tail=50

If the GraphQL Playground is enabled, you can access it via port-forward:

kubectl port-forward svc/controlplane-api 8443:443 -n controlplane-system
# Open https://localhost:8443/graphql in your browser

The Playground sends queries to /graphql/query, which requires a JWT bearer token regardless of security mode. In the Playground's Headers tab, add:

{ "Authorization": "Bearer <your-token>" }

For local development with mode: mock, any JWT with valid claims works — the signature is not validated.

Troubleshooting

Symptom	Likely cause	Resolution
Projector pod not starting	Database not reachable	Check that the controlplane-db Secret exists and the connection string is correct. The readiness probe at /readyz includes a database check.
Projector logs show ErrDependencyMissing	Resources synced out of order	This is normal — the Projector retries automatically when a parent resource has not been synced yet.
ControlPlane API returns empty results	Projector not running, or JWT scoping	Confirm the Projector is syncing. Otherwise check that the caller's JWT has the expected team/group claims.
GraphQL Playground not accessible	Playground disabled in config	Set graphql.playgroundEnabled: true in the ControlPlane API configuration.
Playground queries return 401	Missing or invalid Authorization header	Add { "Authorization": "Bearer <token>" } in the Playground Headers tab. With mode: mock, any JWT with valid claims works.

Next steps

• Architecture: ControlPlane API & Projector — Understand the CQRS pattern, data model, and team isolation internals
• Operations & Monitoring — General observability guidance for the Control Plane
• Components — Overview of all platform components