Helmfile

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

Aspect	Helm	Helmfile
Purpose	Install/manage a single Helm chart release	Orchestrate multiple Helm chart releases
Command	`helm install`, `helm upgrade`	`helmfile sync`, `helmfile apply`
Use case	Quick install, single app	Multi-release, dependencies, fleet management
Complexity	Low	Medium

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:

Commit Helmfile and values to Git
Create HelmRelease for each release in your Helmfile
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:

Use Helmfile to render manifests: helmfile template > manifests.yaml
Commit manifests to Git
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.

About

Manage Pangolin

Self-host Pangolin

Development

When to use Helmfile

Helm vs. Helmfile

Helmfile prerequisites

Basic Helmfile structure

Helmfile with Pangolin and Newt

1. Add Helm repositories

2. Create Helmfile

3. Create values files

4. Create Newt auth secret

5. Deploy with Helmfile

6. Verify deployment

Advanced: Helmfile with environments

Helmfile with GitOps

Using Helmfile with FluxCD

Using Helmfile with Argo CD

Troubleshooting Helmfile

Check syntax

Debug release dependencies

See what will be deployed

Remove releases

Common patterns

Helmfile with local chart overrides

Helmfile with inline values

Helmfile with conditional releases

Important notes

Official support

Helm chart dependencies

Next steps

Helm Quick-Start

Pangolin Configuration

GitOps with Flux

Troubleshooting

​When to use Helmfile

​Helm vs. Helmfile

​Helmfile prerequisites

​Basic Helmfile structure

​Helmfile with Pangolin and Newt

​1. Add Helm repositories

​2. Create Helmfile

​3. Create values files

​4. Create Newt auth secret

​5. Deploy with Helmfile

​6. Verify deployment

​Advanced: Helmfile with environments

​Helmfile with GitOps

​Using Helmfile with FluxCD

​Using Helmfile with Argo CD

​Troubleshooting Helmfile

​Check syntax

​Debug release dependencies

​See what will be deployed

​Remove releases

​Common patterns

​Helmfile with local chart overrides

​Helmfile with inline values

​Helmfile with conditional releases

​Important notes

​Official support

​Helm chart dependencies

​Next steps

Helm Quick-Start

Pangolin Configuration

GitOps with Flux

Troubleshooting

When to use Helmfile

Helm vs. Helmfile

Helmfile prerequisites

Basic Helmfile structure

Helmfile with Pangolin and Newt

1. Add Helm repositories

2. Create Helmfile

3. Create values files

4. Create Newt auth secret

5. Deploy with Helmfile

6. Verify deployment

Advanced: Helmfile with environments

Helmfile with GitOps

Using Helmfile with FluxCD

Using Helmfile with Argo CD

Troubleshooting Helmfile

Check syntax

Debug release dependencies

See what will be deployed

Remove releases

Common patterns

Helmfile with local chart overrides

Helmfile with inline values

Helmfile with conditional releases

Important notes

Official support

Helm chart dependencies

Next steps