> ## 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.

# Helmfile

> Advanced Kubernetes installation using Helmfile for multi-release orchestration.

<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
  <Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
    Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
  </Card>
</div>

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](/self-host/manual/kubernetes/helm) 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](https://github.com/helmfile/helmfile)
* Basic knowledge of Helm values and YAML

Install helmfile:

```bash theme={"theme":"gruvbox-light-hard"}
# 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:

```bash theme={"theme":"gruvbox-light-hard"}
helmfile --version
```

## Basic Helmfile structure

A Helmfile is a YAML file (typically named `helmfile.yaml`) that declares multiple releases:

```yaml theme={"theme":"gruvbox-light-hard"}
# 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

```bash theme={"theme":"gruvbox-light-hard"}
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`:

```yaml theme={"theme":"gruvbox-light-hard"}
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`:

```yaml theme={"theme":"gruvbox-light-hard"}
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`:

```yaml theme={"theme":"gruvbox-light-hard"}
newtInstances:
  - name: main-tunnel
    enabled: true
    auth:
      existingSecretName: newt-auth
```

### 4. Create Newt auth secret

Before applying Helmfile:

```bash theme={"theme":"gruvbox-light-hard"}
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

```bash theme={"theme":"gruvbox-light-hard"}
# Preview changes
helmfile diff

# Apply releases
helmfile sync

# or
helmfile apply
```

### 6. Verify deployment

```bash theme={"theme":"gruvbox-light-hard"}
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:

```yaml theme={"theme":"gruvbox-light-hard"}
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:

```bash theme={"theme":"gruvbox-light-hard"}
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](/self-host/manual/kubernetes/gitops/flux) 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

```bash theme={"theme":"gruvbox-light-hard"}
helmfile lint
```

### Debug release dependencies

```bash theme={"theme":"gruvbox-light-hard"}
helmfile template
```

### See what will be deployed

```bash theme={"theme":"gruvbox-light-hard"}
helmfile diff
```

### Remove releases

```bash theme={"theme":"gruvbox-light-hard"}
helmfile destroy
```

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

## Common patterns

### Helmfile with local chart overrides

```yaml theme={"theme":"gruvbox-light-hard"}
releases:
  - name: pangolin
    namespace: pangolin
    chart: ./charts/pangolin  # local path
    values:
      - values.yaml
```

### Helmfile with inline values

```yaml theme={"theme":"gruvbox-light-hard"}
releases:
  - name: pangolin
    namespace: pangolin
    chart: fossorial/pangolin
    set:
      deployment.type: controller
      deployment.mode: multi
```

### Helmfile with conditional releases

```yaml theme={"theme":"gruvbox-light-hard"}
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](https://github.com/roboll/helmfile) 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

<CardGroup cols={2}>
  <Card title="Helm Quick-Start" href="/self-host/manual/kubernetes/helm" icon="box" />

  <Card title="Pangolin Configuration" href="/self-host/manual/kubernetes/pangolin/configuration" icon="sliders" />

  <Card title="GitOps with Flux" href="/self-host/manual/kubernetes/gitops/flux" icon="code-branch" />

  <Card title="Troubleshooting" href="/self-host/manual/kubernetes/pangolin/troubleshooting" icon="circle-question" />
</CardGroup>