Add kustomize manifests for Kubernetes deployment #144

New Issue

MrUnknownDE · 2026-04-05T17:01:27+02:00

MrUnknownDE commented

2026-04-05 17:01:27 +02:00

Originally created by @Br1an67 on 3/7/2026

Fixes #921

Community Contribution License Agreement

By creating this pull request, I grant the project maintainers an unlimited,
perpetual license to use, modify, and redistribute these contributions under any terms they
choose, including both the AGPLv3 and the Fossorial Commercial license terms. I
represent that I have the right to grant this license for all contributed content.

Description

This PR adds Kubernetes deployment manifests using kustomize, enabling users to deploy Pangolin on Kubernetes clusters. This addresses the community request for Kubernetes support as discussed in #921.

The implementation includes:

Pangolin server deployment with health checks and resource limits
Gerbil + Traefik deployment using a sidecar pattern (matching the docker-compose architecture where traefik shares gerbil's network namespace)
Persistent storage for configuration and data
LoadBalancer service for external access (WireGuard ports + HTTP/HTTPS)
Comprehensive documentation with deployment guides and troubleshooting tips

Architecture

The deployment follows the docker-compose structure:

Pangolin - Main application server (port 3001)
Gerbil + Traefik - Combined pod with sidecar pattern:
- Gerbil: WireGuard VPN tunnel (ports 51820, 21820 UDP)
- Traefik: Reverse proxy (ports 80, 443 TCP)
- Shares network namespace like in docker-compose

Key Features

Uses official images: fosrl/pangolin:latest, fosrl/gerbil:latest, traefik:v3.6
Proper capability management (NET_ADMIN, SYS_MODULE for Gerbil)
Health checks and readiness probes
Configurable resource limits
Single PVC for all config data (can be separated for production)
Kustomize-ready structure with base layer

How to test?

Prerequisites

Kubernetes cluster (1.24+)
kubectl configured
Persistent volume provisioner
LoadBalancer support (or use NodePort/Ingress)

Quick Test

Create namespace and deploy:
```
kubectl apply -k kustomize/base
```

Verify deployment:

kubectl get all -n pangolin
kubectl logs -n pangolin -l app.kubernetes.io/name=pangolin

Check pod status:

kubectl get pods -n pangolin

Expected output:

NAME                       READY   STATUS    RESTARTS   AGE
pangolin-xxx-xxx          1/1     Running   0          1m
gerbil-xxx-xxx            2/2     Running   0          1m

Verify services:
```
kubectl get svc -n pangolin
```
Expected services:
- pangolin (ClusterIP on port 3001)
- gerbil (LoadBalancer with ports 80, 443, 51820, 21820)

Configuration Testing

Before production use, you'll need to:

Create a config.yml based on config/config.example.yml
Set up Traefik configuration in config/traefik/
Configure database (SQLite or external PostgreSQL)

See kustomize/README.md for detailed configuration instructions.

Validation

All YAML files have been validated for syntax:

# Validate YAML syntax
python3 -c "import yaml; list(yaml.safe_load_all(open('kustomize/base/pangolin-deployment.yaml')))"

# List resources
find kustomize -type f

Files Changed

kustomize/README.md                     | 294 ++++++++++++++++++++++++++++++++
kustomize/base/gerbil-deployment.yaml   | 118 +++++++++++++
kustomize/base/kustomization.yaml       |  11 ++
kustomize/base/namespace.yaml           |   7 +
kustomize/base/pangolin-deployment.yaml |  96 +++++++++++
5 files changed, 526 insertions(+)

Production Considerations

This is an initial implementation suitable for testing and development. For production:

Use separate PVCs for different components
Configure external PostgreSQL database
Implement proper RBAC and network policies
Add monitoring with Prometheus ServiceMonitor
Use GitOps tools (ArgoCD, Flux) for deployment

See the comprehensive README in kustomize/README.md for production best practices.

*Originally created by @Br1an67 on 3/7/2026* Fixes #921 ## Community Contribution License Agreement By creating this pull request, I grant the project maintainers an unlimited, perpetual license to use, modify, and redistribute these contributions under any terms they choose, including both the AGPLv3 and the Fossorial Commercial license terms. I represent that I have the right to grant this license for all contributed content. ## Description This PR adds Kubernetes deployment manifests using kustomize, enabling users to deploy Pangolin on Kubernetes clusters. This addresses the community request for Kubernetes support as discussed in #921. The implementation includes: - **Pangolin server deployment** with health checks and resource limits - **Gerbil + Traefik deployment** using a sidecar pattern (matching the docker-compose architecture where traefik shares gerbil's network namespace) - **Persistent storage** for configuration and data - **LoadBalancer service** for external access (WireGuard ports + HTTP/HTTPS) - **Comprehensive documentation** with deployment guides and troubleshooting tips ### Architecture The deployment follows the docker-compose structure: 1. **Pangolin** - Main application server (port 3001) 2. **Gerbil + Traefik** - Combined pod with sidecar pattern: - Gerbil: WireGuard VPN tunnel (ports 51820, 21820 UDP) - Traefik: Reverse proxy (ports 80, 443 TCP) - Shares network namespace like in docker-compose ### Key Features - Uses official images: `fosrl/pangolin:latest`, `fosrl/gerbil:latest`, `traefik:v3.6` - Proper capability management (NET_ADMIN, SYS_MODULE for Gerbil) - Health checks and readiness probes - Configurable resource limits - Single PVC for all config data (can be separated for production) - Kustomize-ready structure with base layer ## How to test? ### Prerequisites - Kubernetes cluster (1.24+) - kubectl configured - Persistent volume provisioner - LoadBalancer support (or use NodePort/Ingress) ### Quick Test 1. **Create namespace and deploy**: ```bash kubectl apply -k kustomize/base ``` 2. **Verify deployment**: ```bash kubectl get all -n pangolin kubectl logs -n pangolin -l app.kubernetes.io/name=pangolin ``` 3. **Check pod status**: ```bash kubectl get pods -n pangolin ``` Expected output: ``` NAME READY STATUS RESTARTS AGE pangolin-xxx-xxx 1/1 Running 0 1m gerbil-xxx-xxx 2/2 Running 0 1m ``` 4. **Verify services**: ```bash kubectl get svc -n pangolin ``` Expected services: - `pangolin` (ClusterIP on port 3001) - `gerbil` (LoadBalancer with ports 80, 443, 51820, 21820) ### Configuration Testing Before production use, you'll need to: 1. Create a config.yml based on `config/config.example.yml` 2. Set up Traefik configuration in `config/traefik/` 3. Configure database (SQLite or external PostgreSQL) See `kustomize/README.md` for detailed configuration instructions. ### Validation All YAML files have been validated for syntax: ```bash # Validate YAML syntax python3 -c "import yaml; list(yaml.safe_load_all(open('kustomize/base/pangolin-deployment.yaml')))" # List resources find kustomize -type f ``` ## Files Changed ``` kustomize/README.md | 294 ++++++++++++++++++++++++++++++++ kustomize/base/gerbil-deployment.yaml | 118 +++++++++++++ kustomize/base/kustomization.yaml | 11 ++ kustomize/base/namespace.yaml | 7 + kustomize/base/pangolin-deployment.yaml | 96 +++++++++++ 5 files changed, 526 insertions(+) ``` ## Production Considerations This is an initial implementation suitable for testing and development. For production: - Use separate PVCs for different components - Configure external PostgreSQL database - Implement proper RBAC and network policies - Add monitoring with Prometheus ServiceMonitor - Use GitOps tools (ArgoCD, Flux) for deployment See the comprehensive README in `kustomize/README.md` for production best practices.

MrUnknownDE closed this issue

2026-04-05 17:01:27 +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#144