[Feature Request] Develop a Kubernetes Operator for Headless/Declarative Pangolin Setup

[marcschaeferger]

Summary

Create a Kubernetes Operator for Pangolin to enable fully headless, declarative provisioning and lifecycle management via Custom Resources (CRs/CRDs). The operator should optionally use the Pangolin HTTP API (POST/PUT) where needed and possible (e.g., to create API keys or perform actions not exposed directly via DB/config) while keeping the primary contract declarative through CRs.

Motivation

• Allow GitOps-style provisioning of Pangolin (sites, resources, tunnels etc.) without using the web UI.
• Remove manual steps (e.g., admin UI key creation) during automated installs.
• Provide reconciliation semantics (self-healing) and integrate with Kubernetes primitives (Secrets, ConfigMaps, Ingress, PVCs).

Goals / Requirements

• Define and implement CRDs to represent Pangolin concepts (example CRs: PangolinCluster, PangolinSite, PangolinResource).
• Operator performs reconciliation to ensure cluster state matches the declared CRs.
• Support bootstrap/seed behavior on first-run (apply initial sites/resources from CRs or mounted config).
• Optionally call Pangolin API endpoints for operations not possible via direct configuration (e.g., generating integration API keys) — operator should support both direct config and API-backed flows.
• Integrate with Kubernetes objects:
  • Use Secrets for credentials / API keys
  • Use ConfigMaps for static config or seed files
  • Support PVC/Storage, Ingress or Service for exposing UI/API
• Provide idempotent behavior and clear status conditions for each CR.
• Emit logs and events for troubleshooting; provide output/status for success/failure.
• Include basic validation/webhook (optional) for CRD fields.
• Provide sample YAMLs and documentation for GitOps workflows.

Operator behaviors / features

• Watch Pangolin CRs and reconcile: create/update/delete Pangolin configuration and resources.
• On create, operator can either:
  • Write config files / DB entries directly (preferred), or
  • Call Pangolin API to create resources when necessary (fallback).
• Support "seed on startup" mode: load initial resources from a ConfigMap/volume and apply them as CRs.
• Provide optional "wait for readiness" and "debug dumps" (describe pods, collect logs) on failures.
• Support disabling timeouts / manual confirmation flows via annotations or CR spec for testing scenarios.

Acceptance Criteria

• CRDs are defined and documented.
• Operator can create at least: PangolinCluster and PangolinSite resources and reconcile them.
• Operator can bootstrap an admin user and/or create an integration API key and store it in a Secret.
• Operator supports declarative creation of at least one example site end-to-end (ingress -> pangolin -> backend).
• Documentation includes sample GitOps workflow and CR examples.

Notes / Non-goals

• The operator should not require the web UI for initial provisioning (goal is headless), but may optionally interact with Pangolin's API if some operations cannot be achieved otherwise.
• Advanced UI features and any unrelated Pangolin UX items are out of scope.

[chiqors]

I recently saw someone working on a Pangolin operator: https://github.com/bovf/pangolin-operator

maybe you could try check that, see if this similar approach.

[miloschwartz]

Thanks, converting this to a discussion thread so others can upvote and participate!

[marcschaeferger]

Will come after the Pangolin Kubernetes & Pangolin Controller Release

[arantesxyz]

If they had a newt operator that setup the resources in pangolin when you deploy a loadbalancer in kube like cloud providers, that would be really cool. Would really make my home lab happy.

[arantesxyz]

But unfortunately i think this project will not live much as "free" OSS.

[chiqors]

that will be a breakthrough. I can still hope Pangolin team doesn't lock features that much to the point that the cloud will always be better

[marcschaeferger]

@arantesxyz @chiqors That’s exactly one of the capabilities of the Pangolin Kubernetes Operator.

The operator will let you create resources in Pangolin via CRDs either manually or automatically through auto-discovery (e.g., using annotations on a service) along with a few other cool features.

Regarding licensing: at the moment, all these capabilities are planned for the OSS/free version. Whether there will be a paid edition in the future hasn’t been decided yet, so for now you can expect these features to be available without restrictions.

[marcschaeferger]

Also, "Pangolin" in the name doesn't mean it's limited to Pangolin. The Operator will support all related Fossorial services and applications, and not only Kubernetes. I plan to add Openshift support by the end of this year.