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

New Issue

MrUnknownDE · 2026-04-05T18:01:53+02:00

MrUnknownDE commented

2026-04-05 18:01:53 +02:00

Originally created by @marcschaeferger on 9/8/2025

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.

*Originally created by @marcschaeferger on 9/8/2025* ## 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.

MrUnknownDE closed this issue

2026-04-05 18:01:53 +02:00

Sign in to join this conversation.

Branches Tags

main

dev

dependabot/npm_and_yarn/dev-minor-updates-b4e5d6b9c5

revert-2766-feature/systemd-install-instructions

dependabot/npm_and_yarn/prod-patch-updates-05702d39f2

dependabot/npm_and_yarn/next-16.2.1

dependabot/npm_and_yarn/recharts-3.8.1

alerting-rules

private-site-ha

dependabot/docker/docker/library/node-25-slim

ssh

delete-account

msg-delivery

org-only-idp

cicd

patch

site-targets-auto-login

No Label

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github/pangolin#941