---
title: "Kubernetes Operator"
---

# Kubernetes Operator

:::note[Not publicly released]
The Kubernetes operator is a companion project to HeliosProxy that is **not
publicly released** — there is no public repository, container image or Helm
chart for it. It is available on request: contact
[sales@heliosdb.com](mailto:sales@heliosdb.com).

To run HeliosProxy on Kubernetes today, use the plain manifests in
[Kubernetes Deployment](/docs/proxy/deployment/kubernetes/). The CRD design
contract is published in the public repository at
[`operator/README.md`](https://github.com/HeliosDatabase/HeliosDB-Proxy/blob/main/operator/README.md).
:::

The operator declares five CRDs under `heliosproxy.dev/v1alpha1`:

| Kind | Purpose |
|---|---|
| `HeliosProxy` | The proxy instance + node list |
| `PoolProfile` | Per-instance pool tuning (mode, max_pool_size, etc.) |
| `RoutingRule` | Routing-hints configuration |
| `AuditPolicy` | `audit-chain` plugin + masking rules + audit backend |
| `TenantQuota` | Per-tenant limits + cost budgets seeded into plugin KV |

## Apply a HeliosProxy

```yaml
apiVersion: heliosproxy.dev/v1alpha1
kind: HeliosProxy
metadata:
  name: analytics
  namespace: data
spec:
  replicas: 2
  image: ghcr.io/heliosdatabase/hdb-heliosdb-proxy:latest   # pin a release tag in production
  nodes:
    - host: pg-primary.db.svc
      port: 5432
      role: primary
      weight: 100
    - host: pg-standby.db.svc
      port: 5432
      role: standby
      weight: 100
  poolProfileRef: default-pool
  plugins:
    - name: cost-governor
      source: oci://registry.example.com/org/cost-governor:1.0.0
```

## What the reconciler does

1. **Resolves refs.** Looks up referenced sub-CRDs; surfaces a `RefMissing` condition for each unresolved ref but proceeds (the proxy can boot from inline-spec values).
2. **Renders proxy.toml** from the merged spec.
3. **Owns three objects**: a `ConfigMap` with the rendered TOML, a `Deployment` with the right replicas + image + ports + CM mount + liveness/readiness probes, and a ClusterIP `Service` exposing the postgres + admin ports. All have `OwnerReference`s so `kubectl delete heliosproxy <name>` cleans up the stack.
4. **Drives a config-hash annotation** on the pod template — when the rendered TOML changes the deployment rolls automatically.
5. **Polls `/topology`** on a 5-second cadence and updates `status.currentPrimary` / `healthyNodes` / `unhealthyNodes`.

State transitions are honest: `Pending` until any pod is ready, `Degraded` while `ReadyReplicas < spec.Replicas`, `Ready` when they match. The polling client hard-fails over after 3 seconds so a hung proxy doesn't block reconcile.