Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt

Use this file to discover all available pages before exploring further.

Try free on Pangolin Cloud

Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
Helmfile is a declarative way to manage multiple Helm releases in a single workflow. Use Helmfile when you need to install Pangolin and/or Newt alongside other Kubernetes components or manage multiple releases together.

​
When to use Helmfile

Use Helmfile if you want to:
  • Orchestrate multiple Helm releases in a single file (Pangolin + Newt + dependencies).
  • Manage dependencies between releases (e.g., install cert-manager before Pangolin).
  • Keep release definitions in version control and synchronized.
  • Avoid repeated helm install commands for complex multi-release setups.
Not using Helmfile? If you’re installing only Pangolin or only Newt without additional services, Helm quick-start is simpler.

​
Helm vs. Helmfile

AspectHelmHelmfile
PurposeInstall/manage a single Helm chart releaseOrchestrate multiple Helm chart releases
Commandhelm install, helm upgradehelmfile sync, helmfile apply
Use caseQuick install, single appMulti-release, dependencies, fleet management
ComplexityLowMedium

​
Helmfile prerequisites

  • Helm 3.10+
  • helmfile CLI installed: Helmfile GitHub
  • Basic knowledge of Helm values and YAML
Install helmfile: 
# macOS/Linux with brew
brew install helmfile

# or download from releases
wget https://github.com/helmfile/helmfile/releases/download/v<version>/helmfile_<os>_<arch>
chmod +x helmfile
sudo mv helmfile /usr/local/bin/
Verify: 
helmfile --version

​
Basic Helmfile structure

A Helmfile is a YAML file (typically named helmfile.yaml) that declares multiple releases: 
# helmfile.yaml
releases:
  - name: cert-manager
    namespace: cert-manager
    createNamespace: true
    chart: jetstack/cert-manager
    version: v1.14.0
    
  - name: pangolin
    namespace: pangolin
    createNamespace: true
    chart: fossorial/pangolin
    version: 0.1.0-alpha.0
    values:
      - pangolin-values.yaml
    
  - name: newt
    namespace: pangolin
    chart: fossorial/newt
    version: 1.4.0
    values:
      - newt-values.yaml
    dependsOn:
      - pangolin

​
Helmfile with Pangolin and Newt

​
1. Add Helm repositories

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

​
2. Create Helmfile

Create helmfile.yaml: 
helmDefaults:
  atomic: true
  cleanupOnFail: true
  wait: true
  timeout: 600
  recreatePods: true
  force: false

repositories:
  - name: jetstack
    url: https://charts.jetstack.io
  - name: fossorial
    url: https://charts.fossorial.io

releases:
  - name: cert-manager
    namespace: cert-manager
    createNamespace: true
    chart: jetstack/cert-manager
    version: v1.14.0
    set:
      installCRDs: true
    
  - name: pangolin
    namespace: pangolin
    createNamespace: true
    chart: fossorial/pangolin
    version: 0.1.0-alpha.0
    values:
      - ./values/pangolin.yaml
    dependsOn:
      - cert-manager
    
  - name: newt
    namespace: pangolin
    chart: fossorial/newt
    version: 1.4.0
    values:
      - ./values/newt.yaml
    dependsOn:
      - pangolin

​
3. Create values files

Create values/pangolin.yaml: 
deployment:
  type: controller
  mode: multi

database:
  mode: cloudnativepg

pangolin:
  config:
    app:
      dashboard_url: https://pangolin.example.com
    domains:
      domain1:
        base_domain: example.com
    gerbil:
      base_endpoint: vpn.example.com

ingress:
  enabled: true
  className: traefik
  hosts:
    - host: pangolin.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: pangolin-tls
      hosts:
        - pangolin.example.com
Create values/newt.yaml: 
newtInstances:
  - name: main-tunnel
    enabled: true
    auth:
      existingSecretName: newt-auth

​
4. Create Newt auth secret

Before applying Helmfile: 
kubectl create namespace pangolin
kubectl create secret generic newt-auth \
  -n pangolin \
  --from-literal=PANGOLIN_ENDPOINT=https://pangolin.example.com \
  --from-literal=NEWT_ID=<your-newt-id> \
  --from-literal=NEWT_SECRET=<your-newt-secret>

​
5. Deploy with Helmfile

# Preview changes
helmfile diff

# Apply releases
helmfile sync

# or
helmfile apply

​
6. Verify deployment

helmfile status

# Check individual releases
helm status cert-manager -n cert-manager
helm status pangolin -n pangolin
helm status newt -n pangolin

# Check pods
kubectl get pods -n pangolin
kubectl get pods -n cert-manager

​
Advanced: Helmfile with environments

For multi-environment setups (dev, staging, prod), use Helmfile environments: 
environments:
  dev:
    values:
      environment: dev
      domain: dev.example.com
      replicaCount: 1
  prod:
    values:
      environment: prod
      domain: pangolin.example.com
      replicaCount: 3

helmDefaults:
  atomic: true
  wait: true

repositories:
  - name: fossorial
    url: https://charts.fossorial.io

releases:
  - name: pangolin
    namespace: pangolin
    createNamespace: true
    chart: fossorial/pangolin
    version: 0.1.0-alpha.0
    values:
      - ./values/pangolin-{{ .Environment.Values.environment }}.yaml
Deploy to specific environment: 
helmfile -e dev sync
helmfile -e prod sync

​
Helmfile with GitOps

​
Using Helmfile with FluxCD

FluxCD can reconcile Helmfile declarations using the helmfile-controller. This allows Git-driven Helmfile updates:
  1. Commit Helmfile and values to Git
  2. Create HelmRelease for each release in your Helmfile
  3. Flux reconciles and applies changes
See Flux Guide for details.

​
Using Helmfile with Argo CD

While Argo CD has native Helm and Kustomize support, you can:
  1. Use Helmfile to render manifests: helmfile template > manifests.yaml
  2. Commit manifests to Git
  3. Have Argo CD manage the raw YAML
Alternatively, use Helm source in Argo CD (simpler than Helmfile for single releases).

​
Troubleshooting Helmfile

​
Check syntax

helmfile lint

​
Debug release dependencies

helmfile template

​
See what will be deployed

helmfile diff

​
Remove releases

helmfile destroy
helmfile destroy uninstalls all releases and may delete data (e.g., databases). Use with caution in production.

​
Common patterns

​
Helmfile with local chart overrides

releases:
  - name: pangolin
    namespace: pangolin
    chart: ./charts/pangolin  # local path
    values:
      - values.yaml

​
Helmfile with inline values

releases:
  - name: pangolin
    namespace: pangolin
    chart: fossorial/pangolin
    set:
      deployment.type: controller
      deployment.mode: multi

​
Helmfile with conditional releases

releases:
  - name: cert-manager
    namespace: cert-manager
    createNamespace: true
    chart: jetstack/cert-manager
    installed: {{ .Environment.Values.installCertManager | default true }}

​
Important notes

​
Official support

Helmfile for Pangolin/Newt Kubernetes deployments is advanced/community-supported. The primary supported methods are:
  • Helm directly
  • Kustomize overlays
  • GitOps tools (Argo CD, Flux)
If you encounter Helmfile-specific issues, refer to the Helmfile documentation and community.

​
Helm chart dependencies

The Pangolin Helm chart includes optional sub-chart dependencies (e.g., CloudNativePG operator). Helmfile does not manage these—they’re handled by Helm. Ensure chart dependencies are available when installing.

​
Next steps

Helm Quick-Start

Pangolin Configuration

GitOps with Flux

Troubleshooting