--- title: "Helmfile" description: "Advanced Kubernetes installation using Helmfile for multi-release orchestration." --- 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 # macOS/Linux with brew brew install helmfile # or download from releases wget https://github.com/helmfile/helmfile/releases/download/v/helmfile__ chmod +x helmfile sudo mv helmfile /usr/local/bin/ ``` Verify: ```bash helmfile --version ``` ## Basic Helmfile structure A Helmfile is a YAML file (typically named `helmfile.yaml`) that declares multiple releases: ```yaml # 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 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 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 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 newtInstances: - name: main-tunnel enabled: true auth: existingSecretName: newt-auth ``` ### 4. Create Newt auth secret Before applying Helmfile: ```bash kubectl create namespace pangolin kubectl create secret generic newt-auth \ -n pangolin \ --from-literal=PANGOLIN_ENDPOINT=https://pangolin.example.com \ --from-literal=NEWT_ID= \ --from-literal=NEWT_SECRET= ``` ### 5. Deploy with Helmfile ```bash # Preview changes helmfile diff # Apply releases helmfile sync # or helmfile apply ``` ### 6. Verify deployment ```bash 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 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 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 helmfile lint ``` ### Debug release dependencies ```bash helmfile template ``` ### See what will be deployed ```bash helmfile diff ``` ### Remove releases ```bash 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 ```yaml releases: - name: pangolin namespace: pangolin chart: ./charts/pangolin # local path values: - values.yaml ``` ### Helmfile with inline values ```yaml releases: - name: pangolin namespace: pangolin chart: fossorial/pangolin set: deployment.type: controller deployment.mode: multi ``` ### Helmfile with conditional releases ```yaml 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