API reference¶

Kontinuum's API is a Kubernetes-style API: every resource below is a regular custom resource, served by the embedded apiserver, readable and writable with kubectl (see Running via Docker or Local setup) or any Kubernetes client library — there is no separate, bespoke REST API to learn.

Configuration¶

Configuration is loaded from KONTINUUM_-prefixed environment variables. Env-var names are auto-derived from the config struct path (e.g. Server.Addr → KONTINUUM_SERVER_ADDR).

Server & logging¶

Env var	Description	Default
`KONTINUUM_SERVER_ADDR`	Listener address	`:8080`
`KONTINUUM_SERVER_STORAGE`	Storage connection string (`sqlite://`, `postgres://`, `mysql://`, `etcd://`, ...)	`sqlite://kontinuum.db`
`KONTINUUM_SERVER_REGION`	Region this server manages. Leave unset, along with Zone, to run as the control-plane entrypoint.	(empty)
`KONTINUUM_SERVER_ZONE`	Availability zone this server manages. Leave unset, along with Region, to run as the control-plane entrypoint.	(empty)
`KONTINUUM_LOG_LEVEL`	Log level (`debug`, `info`, `warn`, `error`)	`warn`
`KONTINUUM_LOG_FORMAT`	Log format (`console`, `text`, `json`)	`json`

Authentication (OIDC)¶

See Authentication for how these interact and the server's startup behavior when they're missing or conflicting.

Env var	Description	Default
`KONTINUUM_OIDC_ISSUER_URL`	OIDC issuer URL. Empty disables OIDC entirely.	(empty)
`KONTINUUM_OIDC_CLIENT_ID`	OAuth 2.0 public client ID registered with the issuer	`kontinuum`
`KONTINUUM_OIDC_REDIRECT_URL`	Callback URL registered with the issuer for the `/app` login flow	`http://localhost:8080/app`
`KONTINUUM_OIDC_ADMIN_GROUPS`	Comma-delimited OIDC groups granted full (`system:masters`-equivalent) access	(empty)
`KONTINUUM_INSECURE_ALLOW_ANONYMOUS`	Explicitly acknowledges anonymous access. Must be `true` to start with no OIDC issuer configured; mutually exclusive with `KONTINUUM_OIDC_ISSUER_URL`.	`false`

Flags override environment variables when explicitly set:

kontinuum serve --addr :9090 --storage postgres://user:pass@host/db

Generated CRD reference¶

Full generated field-by-field documentation for every CRD, kept in sync with api/ automatically, is published at:

doc.crds.dev/github.com/nicklasfrahm-dev/kontinuum

Resources¶

All kinds below belong to the kontinuum.sh/v1alpha2 API group/version (kontinuum.sh/v1alpha1 also exists, for backward compatibility — the registry controller runs a conversion webhook between the two).

Kind	Owning controller	Purpose
`Kontinuum`	`pkg/domain/registry`	Self-registration record for a running kontinuum process — role, region/zone, version, heartbeat.
`Zone`	—	Groups instances by availability zone.
`Instance`	`pkg/domain/instance`	A candidate machine, discovered over the Talos maintenance-mode API.
`InstancePool`	`pkg/domain/instancepool`	Claims a set of `Instance`s matching a selector, up to `spec.replicas`.
`TalosCluster`	`pkg/domain/taloscluster`	Bootstraps a Talos Kubernetes cluster from a control-plane `InstancePool` and optional worker pools.
`Addon`	`pkg/domain/addon`	A Helm-based addon (Cilium, cert-manager) installed and health-probed as part of `TalosCluster` bootstrap.

See Architecture for how these controllers cooperate, and Cluster provisioning for the full Instance → InstancePool → TalosCluster → Addon flow.

CRD manifests in this repo¶

The raw CRD YAML manifests (source of truth for the generated reference above) live under config/crd, regenerated from api/v1alpha1 and api/v1alpha2 via make generate (controller-gen).