Kubernetes

This page provides instructions on how to configure the Helm chart to install the Control Plane in any cloud provider. The chart deploys one Control Plane: a Deployment, a Secret holding its environment, a Service for the HTTP API, and — if you ask for them — a ServiceAccount and a pair of Gateway API resources. It depends on no other chart. It needs a PostgreSQL you provide, and nothing else. The Control Plane carries no traffic. It serves the HTTP API and the web app and administers a fleet of Sidecars. There is no gRPC listener on 8010, no protocol proxies, and of the six transport plugins only Slack is started.

Quick Start

A Control Plane with local authentication, in three steps. At the end the web app answers on your machine and you can create the first account.

Deploy a PostgreSQL

Skip this if you already have a database to point at. This one is a throwaway with a password in plain sight.

postgres.yaml

apiVersion: apps/v1
kind: Deployment
metadata: {name: postgres}
spec:
  replicas: 1
  selector: {matchLabels: {app: postgres}}
  template:
    metadata: {labels: {app: postgres}}
    spec:
      containers:
        - name: postgres
          image: postgres:17.6
          env:
            - {name: POSTGRES_USER,     value: hoopuser}
            - {name: POSTGRES_PASSWORD, value: hooppass}
            - {name: POSTGRES_DB,       value: hoopdb}
          ports: [{containerPort: 5432}]
---
apiVersion: v1
kind: Service
metadata: {name: postgres}
spec:
  selector: {app: postgres}
  ports: [{port: 5432}]

kubectl create namespace hoop
kubectl -n hoop apply -f postgres.yaml

The Control Plane runs its migrations and the organization bootstrap before it listens, so the database has to be reachable at startup.

Write the values file

values.yaml

config:
  POSTGRES_DB_URI: 'postgres://hoopuser:hooppass@postgres:5432/hoopdb?sslmode=disable'
  API_URL: 'http://127.0.0.1:8009'

Two keys are required and the rest have defaults. API_URL is the address the web app and every Sidecar reach this on — here it is the port-forward, because that is where you will open it. Change it when you publish the service, and read API_URL before you leave it out.

Install the chart

VERSION=$(curl -s https://releases.hoop.dev/release/latest.txt)
helm upgrade hoopcontrolplane --install \
  oci://ghcr.io/hoophq/helm-charts/hoopcontrolplane-chart --version $VERSION \
  --namespace hoop \
  -f values.yaml

kubectl -n hoop rollout status deploy/hoopcontrolplane
kubectl -n hoop logs deploy/hoopcontrolplane

The last bootstrap line names the mode and the address it will serve:

{"level":"info","msg":"gateway ready, elapsed=168ms","event":"bootstrap.ready",
 "urls":{"Control Plane":"http://127.0.0.1:8009"}}

Forward the port and open the web app:

kubectl -n hoop port-forward svc/hoopcontrolplane 8009:8009

http://127.0.0.1:8009/login — authentication is local by default, so the first visit asks you to create the account. Confirm the mode at the same time:

curl -s http://127.0.0.1:8009/api/publicserverinfo

{"auth_method":"local","setup_required":true,"application_mode":"control-plane"}

Delete everything this created with kubectl delete namespace hoop.

Helm Install

To install the latest version in a new namespace (example: hoop):

VERSION=$(curl -s https://releases.hoop.dev/release/latest.txt)
helm upgrade --install hoopcontrolplane \
  oci://ghcr.io/hoophq/helm-charts/hoopcontrolplane-chart --version $VERSION \
  -f values.yaml \
  --namespace hoop

The release name prefixes every resource the chart owns:

Resource	Name
Deployment, Service, ServiceAccount	`<release>-hoopcontrolplane`
Secret holding the environment	`<release>-hoopcontrolplane-config`
Secret holding `extraSecret`	`<release>-hoopcontrolplane-extra-env`
Gateway	`<release>-hoopcontrolplane`
HTTPRoute	`<release>-hoopcontrolplane-route`

A release named hoopcontrolplane collapses to the bare name rather than repeating it.

Overriding values

It is possible to add new attributes or overwrite an attribute from a base values.yaml file. In the example below a specific image tag is pinned and the log level is raised.

helm upgrade --install hoopcontrolplane \
  oci://ghcr.io/hoophq/helm-charts/hoopcontrolplane-chart --version $VERSION \
  -f values.yaml \
  --set image.tag=1.182.0-distroless \
  --set config.LOG_LEVEL=debug

Control Plane Configuration

Everything under config becomes an environment variable in a Secret attached with envFrom. A change to any of them rolls the pods on helm upgrade: the Deployment carries a checksum of the rendered Secret.

config:
  POSTGRES_DB_URI: 'postgres://<user>:<pwd>@<db-host>:5432/<dbname>'
  API_URL: 'https://cp.yourdomain.tld'

Those two are required. Everything else below has a default or is optional.

Database

The Control Plane stores its state in PostgreSQL, using the private schema for its own tables. This creates the database and a user with the privileges it needs:

CREATE DATABASE hoopdb;
CREATE USER hoopuser WITH ENCRYPTED PASSWORD 'my-secure-password';
-- switch to the created database
\c hoopdb
CREATE SCHEMA IF NOT EXISTS private;
GRANT ALL PRIVILEGES ON DATABASE hoopdb TO hoopuser;
GRANT ALL PRIVILEGES ON SCHEMA public to hoopuser;
GRANT ALL PRIVILEGES ON SCHEMA private to hoopuser;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO hoopuser;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA private TO hoopuser;

If the password contains special characters, URL-encode it in the connection string. Append ?sslmode=disable if your database does not support TLS.

config:
  POSTGRES_DB_URI: 'postgres://hoopuser:<passwd>@<db-host>:5432/hoopdb'

The chart provisions no database and pglite:// is refused: it is single-node and serves one connection at a time.

Authentication

Authentication is local by default. The Control Plane manages users and passwords itself and signs its own tokens, so a database and an address are the whole configuration. Setting any IDP_* key selects OIDC instead:

config:
  IDP_ISSUER: 'https://idp-issuer-url'
  IDP_CLIENT_ID: 'client-id'
  IDP_CLIENT_SECRET: 'client-secret'
  IDP_CUSTOM_SCOPES: ''
  IDP_GROUPS_CLAIM: ''
  IDP_AUDIENCE: ''

IDP_CLIENT_ID and IDP_CLIENT_SECRET become required once IDP_ISSUER is set; the chart refuses to render without them. The provider’s callback is <API_URL>/api/callback — register that URL with your identity provider. See Identity Providers for the per-provider settings.

API URL

API_URL is the address the web app and every Sidecar reach this deployment on. It is required, and it must carry a scheme.

config:
  API_URL: 'https://cp.yourdomain.tld'

The process itself falls back to http://127.0.0.1:8009 when the variable is absent, which is why the chart requires it: the fallback boots a pod that looks healthy and is not usable.

TLS

Two keys, and one rule: set both to serve HTTPS, leave both empty to serve plaintext.

config:
  TLS_CERT: 'base64://<pem-encoded-full-certificate>'
  TLS_KEY: 'base64://<pem-encoded-private-key>'

Nothing is generated, and half a pair serves plaintext rather than failing. Both values go through the environment loader, so three forms work:

Base64 encoded
Path based

echo "base64://$(cat server.crt | base64)"
echo "base64://$(cat server.key | base64)"

config:
  TLS_CERT: 'file:///etc/hoop/certs/server.crt'
  TLS_KEY: 'file:///etc/hoop/certs/server.key'

Mount the files with extraVolumes.

The certificate file may carry the root and intermediate CAs as well. Order matters:

<SERVER-CERT>
<INTERMEDIATE-CA>
<ROOT_CA>

Nothing here reaches the probes, because the chart renders none — an httpGet probe you write against a TLS listener must name scheme: HTTPS itself.

Logging

config:
  GIN_MODE: 'release'          # release | debug
  LOG_ENCODING: 'json'         # json | console
  LOG_LEVEL: 'info'            # debug | info | warn | error

Chart Configuration

Everything below is a chart attribute rather than part of the Control Plane’s environment: how the pod is built, what it is published as, and where it is scheduled.

Image Configuration

By default the chart pulls hoophq/hoopcontrolplane:latest, which is the Ubuntu flavour.

image:
  repository: hoophq/hoopcontrolplane
  pullPolicy: Always
  tag: 1.182.0

Tag	Base
`<version>`, `latest`	Ubuntu 24.04 LTS, keeps a shell
`<version>-distroless`	distroless static, no shell, no package manager, about two thirds the size

The web UI is compiled into the binary, so neither flavour carries webapp files and both serve the app with no configuration. That is also what makes a distroless flavour possible. Container Images covers what each flavour contains.

Probes

The chart renders no probe. readinessProbe and livenessProbe are both empty by default, and whatever you put under either one is rendered verbatim — any handler the Kubernetes Probe schema accepts, plus timings and thresholds.

readinessProbe:
  httpGet:
    path: /api/healthz
    port: 8009
  initialDelaySeconds: 10
  periodSeconds: 10
livenessProbe:
  httpGet:
    path: /api/healthz
    port: 8009
  initialDelaySeconds: 10
  periodSeconds: 10

Health is GET /api/healthz on 8009, under API_URL’s path if it has one. Ten seconds and not five: the listener opens only after the migrations, the organization bootstrap and the identity provider, so an answer at all means the bootstrap finished. Add scheme: HTTPS inside httpGet when TLS is configured. A tcpSocket check on 8009 serves either listener from one stanza, at the cost of not calling the endpoint:

readinessProbe:
  tcpSocket:
    port: 8009
  initialDelaySeconds: 10
  periodSeconds: 10

Why there is no default. The chart cannot know whether the listener speaks TLS. TLS_CERT and TLS_KEY decide it, and either can arrive through extraSecret or existingSecret, which no template can read. The kubelet does not negotiate, so a wrong scheme does not degrade — it stops the pod from ever becoming ready:

Readiness probe failed: HTTP probe failed with statuscode: 400

That is Go answering Client sent an HTTP request to an HTTPS server. Certificate validity is not the issue in the other direction: kubelet HTTPS probes always skip verification and there is no field to change that.With neither probe set, the kubelet treats the container as ready as soon as it starts and never restarts it for health — a pod still running migrations takes Service traffic. Set them.

Service

One Service, one port.

service:
  enabled: true
  type: ClusterIP
  annotations: {}

type: LoadBalancer with the annotations your cloud provider expects is the whole configuration for a cluster without the Gateway API:

service:
  type: LoadBalancer
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-type: nlb
    service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing

There is deliberately no source-range or traffic-policy plumbing. One HTTP port does not need it.

Exposing it with the Gateway API

The chart renders a Gateway and an HTTPRoute rather than an Ingress. This requires the Gateway API CRDs in your cluster — istioctl install for Istio, or the upstream guides for anything else.

gatewayApi:
  enabled: true
  createGateway: true
  gateway:
    gatewayClassName: istio
    listeners:
      - name: http
        hostname: cp.yourdomain.tld
        port: 80
        protocol: HTTP
        allowedRoutes:
          namespaces: {from: Same}
  httpRoute:
    hostnames: [cp.yourdomain.tld]

Both parentRefs and rules have working defaults. The default rule is a PathPrefix on API_URL’s path, backed by this chart’s Service on 8009 — which is the whole Control Plane, since it serves one HTTP port and nothing else:

rules:
  - matches:
      - path: {type: PathPrefix, value: /}
    backendRefs:
      - name: hoopcontrolplane
        port: 8009

To attach to a Gateway somebody else owns, set createGateway: false and name it:

gatewayApi:
  enabled: true
  createGateway: false
  httpRoute:
    parentRefs:
      - name: shared-ingress
        namespace: infra
        sectionName: http

The chart refuses to render createGateway: false with no parentRefs: a route with no parent attaches to nothing and looks installed. It refuses service.enabled: false with no rules for the same reason from the other end — the default route’s backend is that Service, so the route would resolve to nothing and every request would get a 500 from an install that looked fine. listeners, addresses, infrastructure and backendTLS pass through to the Gateway untouched, and setting rules replaces the default rule entirely. There is no Ingress template and no GRPCRoute.

backendTLS is the client certificate the Gateway presents to backends, for mTLS, and it lives in the Gateway API experimental channel. The standard channel’s Gateway CRD has no such field and prunes it silently, so it renders into the manifest and then disappears from the live object — check with kubectl get gateway <name> -o yaml before relying on it.Validating the backend’s own certificate is a different thing: a BackendTLSPolicy resource, which this chart does not render.

Extra Environment Variables

Anything this chart does not render goes in extraSecret, which becomes a second Secret attached with envFrom:

extraSecret:
  MY_VARIABLE: some-value

existingSecret references a Secret you manage yourself. The chart never creates or updates it:

existingSecret: hoop-controlplane-credentials

Order matters, because later entries win: the chart’s own Secret, then extraSecret, then existingSecret.

A Secret referenced by existingSecret is invisible to the chart, so editing it changes no checksum and helm upgrade rolls nothing. Run kubectl rollout restart deploy/<release>-hoopcontrolplane after you change it, or use a controller that annotates the pods for you.

Extra Volumes

For what the configuration references by path: a TLS certificate under file:///..., an identity provider CA bundle.

config:
  TLS_CERT: 'file:///etc/hoop/certs/server.crt'
  TLS_KEY: 'file:///etc/hoop/certs/server.key'

extraVolumes:
  - name: api-tls
    secret:
      secretName: hoop-controlplane-tls
      defaultMode: 0400
extraVolumeMounts:
  - name: api-tls
    mountPath: /etc/hoop/certs
    readOnly: true

Mount any Secret holding a private key with defaultMode: 0400. Kubernetes writes secret files 0644 by default.

Service Account

With create: true the chart makes one named after the release. With create: false, name points at an account that already exists — the shape workload identity wants.

serviceAccount:
  create: false
  name: hoop-controlplane
  annotations: {}

Leaving both unset means the pod uses the namespace default.

Replicas and Deployment Strategy

replicas: 1

deploymentStrategy:
  type: Recreate

Read this before raising replicas.Slack’s socket mode opens one websocket per process and nothing coordinates them — no lease, no advisory lock, only in-process mutexes. With Slack configured for an organization, two replicas post every review twice and race each other’s clicks. Slack documents that a payload may go to any open connection with no pattern to rely on, so a click can be handled by the replica that is not holding the waiting session: the verdict is written and the session is never released.Raising replicas is safe when no organization in this deployment has Slack configured. Everything else in the process is stateless HTTP over a shared database.The chart cannot enforce this — whether Slack is configured lives in a database row no chart can read — so it prints a warning above one replica and leaves the decision to you.The same constraint applies across deployments: a Gateway and a Control Plane pointed at the same database both read that row and both open a socket.

The strategy is Recreate for the same reason. At one replica, RollingUpdate’s default surge runs two pods through every upgrade, which is two Slack sockets on a timer. The Control Plane holds no sessions, so the short API gap drops nothing. A deployment already running several replicas has accepted that condition — set RollingUpdate there.

Computing Resources

The chart is API-only: it carries no sessions and runs no proxies.

resources:
  limits:
    cpu: 1024m
    memory: 1Gi
  requests:
    cpu: 256m
    memory: 512Mi

Node Selector

This configuration describes a pod that has a node selector, disktype: ssd. This means that the pod will get scheduled on a node that has a disktype=ssd label. See this documentation for more information.

# -- Node labels for pod assignment
nodeSelector:
  disktype: ssd

Tolerations

See this article explaining how to configure tolerations

# -- Toleration labels for pod assignment
tolerations:
- effect: NoExecute
  key: spot
  value: "true"
- effect: NoSchedule
  key: spot
  value: "true"

Node Affinity

See this article explaining how to configure affinity and anti-affinity rules

# -- Affinity settings for pod assignment
affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
      - matchExpressions:
        - key: topology.kubernetes.io/zone
          operator: In
          values:
          - antarctica-east1

Security Context

Both are empty by default and pass through untouched.

# -- Pod level
podSecurityContext:
  runAsNonRoot: true
  seccompProfile: {type: RuntimeDefault}

# -- Container level
securityContext:
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  capabilities: {drop: [ALL]}

The image already runs as uid 10001.

Annotations

# -- Applied to the pod template
podAnnotations:
  prometheus.io/scrape: 'true'

# -- Applied to the Deployment object
deploymentAnnotations:
  argocd.argoproj.io/sync-wave: '1'

Naming

nameOverride changes the base the resource names are built from; fullnameOverride replaces the whole name and drops the release prefix.

nameOverride: ''
fullnameOverride: ''

Both feed the Deployment’s selector, which is immutable in Kubernetes. Changing either on a live release makes helm upgrade fail. Settle them at install time.

Generating Manifests

If you prefer using manifests over Helm, we recommend this approach. It allows you to track any modifications to the chart whenever a new version appears. You can apply a diff to your versioned files to identify what has been altered.

VERSION=$(curl -s https://releases.hoop.dev/release/latest.txt)
helm template hoopcontrolplane \
  oci://ghcr.io/hoophq/helm-charts/hoopcontrolplane-chart --version $VERSION \
  -f values.yaml

Connect a Sidecar

Issue a token, point a Sidecar at the Control Plane, and confirm it picked up its configuration.

Environment Variables

Every variable the service reads.

Getting Started

Sidecar

Features

Control Plane Setup

Quick Start

Helm Install

Overriding values

Control Plane Configuration

Database

Authentication

API URL

TLS

Logging

Chart Configuration

Image Configuration

Probes

Service

Exposing it with the Gateway API

Extra Environment Variables

Extra Volumes

Service Account

Replicas and Deployment Strategy

Computing Resources

Node Selector

Tolerations

Node Affinity

Security Context

Annotations

Naming

Generating Manifests

Next

Connect a Sidecar

Environment Variables

​Quick Start

​Helm Install

​Overriding values

​Control Plane Configuration

​Database

​Authentication

​API URL

​TLS

​Logging

​Chart Configuration

​Image Configuration

​Probes

​Service

​Exposing it with the Gateway API

​Extra Environment Variables

​Extra Volumes

​Service Account

​Replicas and Deployment Strategy

​Computing Resources

​Node Selector

​Tolerations

​Node Affinity

​Security Context

​Annotations

​Naming

​Generating Manifests

​Next

Connect a Sidecar

Environment Variables

Quick Start

Helm Install

Overriding values

Control Plane Configuration

Database

Authentication

API URL

TLS

Logging

Chart Configuration

Image Configuration

Probes

Service

Exposing it with the Gateway API

Extra Environment Variables

Extra Volumes

Service Account

Replicas and Deployment Strategy

Computing Resources

Node Selector

Tolerations

Node Affinity

Security Context

Annotations

Naming

Generating Manifests

Next