Helm

What Pangolin deploysCopy Anchor Link

The Pangolin Helm chart deploys the Pangolin control plane and related Kubernetes components.

Depending on the selected values, the chart can deploy:

• Pangolin application: dashboard, API, authentication, configuration, and application state.
• pangolin-kube-controller: Kubernetes controller used in controller mode.
• Gerbil: WireGuard tunnel manager used by the Pangolin tunnel stack.
• Traefik integration: Traefik CRD-based routing in controller mode, bundled Traefik controller when enabled, or standalone Traefik mode.
• Database backend: CloudNativePG, external PostgreSQL, embedded PostgreSQL, or SQLite.

See Version Matrix for chart and default app version references.

Gerbil setup in the Pangolin chartCopy Anchor Link

This chart deploys Gerbil when gerbil.enabled=true. This is the default when using deployment.type=controller and recommended.

PrerequisitesCopy Anchor Link

Before installing Pangolin, you need:

• Kubernetes 1.30.14 or newer.
• Helm 3.x.
• kubectl access to the target cluster.
• A namespace prepared for the install.
• A StorageClass if you use chart-managed persistent storage.
• DNS records for the Pangolin dashboard and tunnel endpoint.
• Traefik CRDs and a Traefik controller when using deployment.type=controller.
• A database plan: CloudNativePG, external PostgreSQL, embedded PostgreSQL, or SQLite.

See Prerequisites for detailed cluster, namespace, storage, networking, and security requirements.

Recommended quick installCopy Anchor Link

This quick install uses:

• deployment.type=controller
• deployment.mode=multi
• database.mode=cloudnativepg
• chart-managed CloudNativePG operator and cluster
• chart-managed dashboard IngressRoute
• Traefik cert resolver for TLS

Step 1: Create the namespaceCopy Anchor Link

Create the namespace before installing the chart:

kubectl create namespace pangolin

Gerbil requires NET_ADMIN for WireGuard interface management. If your cluster enforces Pod Security Admission, label the namespace accordingly:

kubectl label namespace pangolin \
  pod-security.kubernetes.io/enforce=privileged \
  pod-security.kubernetes.io/warn=baseline \
  pod-security.kubernetes.io/audit=restricted \
  --overwrite

Step 2: Create a Pangolin app secretCopy Anchor Link

Create a Secret for SERVER_SECRET:

kubectl create secret generic pangolin-app-secret \
  --namespace pangolin \
  --from-literal=SERVER_SECRET='<strong-random-secret>'

Use a long random value. Do not commit this secret to Git.

Step 3: Create a values fileCopy Anchor Link

Create values-pangolin.yaml:

deployment:
  type: controller
  mode: multi
  installTraefikController: false

database:
  mode: cloudnativepg
  cloudnativepg:
    cluster:
      name: pangolin-db

cnpg-operator:
  enabled: true

cnpg-cluster:
  enabled: true
  fullnameOverride: pangolin-db
  cluster:
    instances: 1
    storage:
      size: 8Gi

pangolin:
  secret:
    existingSecretName: pangolin-app-secret
    existingSecretKey: SERVER_SECRET

  config:
    app:
      dashboard_url: https://pangolin.example.com
    domains:
      domain1:
        base_domain: example.com
        cert_resolver: letsencrypt
    gerbil:
      base_endpoint: vpn.example.com
      start_port: 51820
      clients_start_port: 21820
    traefik:
      enabled: true
      http_entrypoint: web
      https_entrypoint: websecure
      cert_resolver: letsencrypt

  ingressRoute:
    dashboard:
      enabled: true
      host: pangolin.example.com
      entryPoints:
        - websecure
      tls:
        enabled: true
        certResolver: letsencrypt
        secretName: ""

gerbil:
  enabled: true
  startupMode: delayed
  persistence:
    enabled: true
    size: 1Gi

Important points:

• Replace pangolin.example.com, example.com, and vpn.example.com.
• Keep pangolin.config.gerbil.start_port aligned with gerbil.ports.wg1.
• Keep pangolin.config.gerbil.clients_start_port aligned with gerbil.ports.wg2.
• Use gerbil.startupMode=delayed for the first install if Gerbil should not start before the initial Pangolin setup is complete.

The chart defaults to deployment.type=controller, deployment.mode=multi, database.mode=cloudnativepg, and NetworkPolicy rendering enabled. Gerbil startupMode supports normal, delayed, and disabledUntilSetup. ([GitHub][1])

Step 4: Install PangolinCopy Anchor Link

Add the Helm repository:

helm repo add fossorial https://charts.fossorial.io
helm repo update fossorial

Install Pangolin:

helm upgrade --install pangolin fossorial/pangolin \
  --namespace pangolin \
  --values values-pangolin.yaml

Do not use --create-namespace here. The namespace was created and labeled before installation.

Step 5: Verify the deploymentCopy Anchor Link

Check Helm release status:

helm status pangolin --namespace pangolin
helm history pangolin --namespace pangolin

Check workloads:

kubectl get pods --namespace pangolin
kubectl get deploy,statefulset --namespace pangolin

Check Services:

kubectl get svc --namespace pangolin

Check Traefik IngressRoute resources:

kubectl get ingressroute --namespace pangolin

If Traefik CRDs are not installed, this command will fail. In that case, install Traefik CRDs or enable/install the Traefik controller path required by your selected deployment mode.

Wait for the Pangolin pod to become ready:

kubectl wait --for=condition=ready pod \
  -l app.kubernetes.io/name=pangolin \
  --namespace pangolin \
  --timeout=300s

Accessing the dashboardCopy Anchor Link

After DNS and Traefik routing are configured, access Pangolin through the dashboard URL:

https://pangolin.example.com

The API route is exposed under:

https://pangolin.example.com/api/v1

kubectl port-forward --namespace pangolin svc/pangolin 8080:3002

http://localhost:8080

The chart routes /api/v1 to the Pangolin external/API port and the dashboard route to the Next/UI port. The default service ports are 3000 for external/API and 3002 for the dashboard/UI. ([GitHub][1])

Switch Gerbil to normal startupCopy Anchor Link

If you installed with gerbil.startupMode=delayed, switch Gerbil to normal mode after the initial setup is complete:

helm upgrade pangolin fossorial/pangolin \
  --namespace pangolin \
  --reuse-values \
  --set gerbil.startupMode=normal

Check Gerbil resources:

kubectl get pods,svc,pvc --namespace pangolin \
  -l app.kubernetes.io/name=gerbil

UpgradeCopy Anchor Link

Update the Helm repository:

helm repo update fossorial

Upgrade the release:

helm upgrade pangolin fossorial/pangolin \
  --namespace pangolin \
  --values values-pangolin.yaml

Check upgrade status:

helm status pangolin --namespace pangolin
helm history pangolin --namespace pangolin

Rollback if needed:

helm rollback pangolin <revision> --namespace pangolin

OCI installCopy Anchor Link

The Pangolin chart is also published as an OCI chart in GHCR.

Pull the chart:

helm pull oci://ghcr.io/fosrl/helm-charts/pangolin \
  --version 0.1.0-alpha.0

Install from OCI:

helm upgrade --install pangolin oci://ghcr.io/fosrl/helm-charts/pangolin \
  --version 0.1.0-alpha.0 \
  --namespace pangolin \
  --values values-pangolin.yaml

OCI changes where Helm pulls the chart from. It does not change the values file or the release behavior.

Architecture overviewCopy Anchor Link

Recommended deployment mode:

deployment:
  type: controller
  mode: multi

In this topology:

Database modes:

The chart supports cloudnativepg, external, embedded, and sqlite database modes. The chart comments mark cloudnativepg as the preferred production mode and SQLite as development/test only. ([GitHub][1])

Chart signingCopy Anchor Link

The chart metadata includes Artifact Hub signing information:

Fingerprint: 48E7F670FCC13645FC48B08D587294B228C2EC2C
Public key: https://charts.fossorial.io/pgp_keys.asc

Use this metadata when verifying signed chart releases. The signing key and fingerprint are published in the chart annotations. ([GitHub][2])

ReferencesCopy Anchor Link

Next stepsCopy Anchor Link