58df057dcc
* fix: skip cache refresh for shared cache paths to prevent race conditions When multiple helmfile processes run in parallel (e.g., as ArgoCD plugin), they share the same OCI chart cache in ~/.cache/helmfile. One process could delete and re-download (refresh) a cached chart while another process was still using it, causing "path not found" errors. This fix: - Adds isSharedCachePath() helper to detect shared cache paths - Skips chart deletion/refresh for paths in the shared cache directory - Users can force refresh by running `helmfile cache cleanup` first Fixes #2387 Signed-off-by: yxxhero <aiopsclub@163.com> * docs: document OCI chart caching behavior and multi-process safety Add documentation for: - OCI chart cache location and behavior - How to force cache refresh with `helmfile cache cleanup` - Multi-process safety when using shared cache - Cache management commands (info, cleanup) Signed-off-by: yxxhero <aiopsclub@163.com> * fix: address review comments for shared cache handling - Return error instead of chartActionDownload for corrupted shared cache - Change refresh skip log from Debugf to Infof for user visibility - Add t.Helper() to createTestLogger test helper Signed-off-by: yxxhero <aiopsclub@163.com> * fix: handle symlinks and add debug logging in isSharedCachePath - Use filepath.EvalSymlinks to resolve symlinks before path comparison - Add debug logging when filepath.Abs fails - Add test case for symlink to shared cache directory Signed-off-by: yxxhero <aiopsclub@163.com> * fix: address copilot review comments - Include underlying error in corrupted cache error message - Add cleanup for test directories created in shared cache - Clarify --skip-refresh flag documentation Signed-off-by: yxxhero <aiopsclub@163.com> * fix: handle edge case when chartPath equals sharedCacheDir - isSharedCachePath now returns true for exact match with cache dir - Add test case for exact match with shared cache directory Signed-off-by: yxxhero <aiopsclub@163.com> * test: add integration test for acquireChartLock shared cache behavior Add TestAcquireChartLockSharedCacheSkipRefresh to verify that acquireChartLock returns chartActionUseCached instead of chartActionRefresh when the chart exists in the shared cache, even when refresh is requested. This tests the core fix for the race condition issue #2387. Signed-off-by: yxxhero <aiopsclub@163.com> --------- Signed-off-by: yxxhero <aiopsclub@163.com> |
||
|---|---|---|
| .github | ||
| cmd | ||
| docs | ||
| examples | ||
| hack | ||
| logo | ||
| pkg | ||
| test | ||
| .dockerignore | ||
| .editorconfig | ||
| .gitignore | ||
| .golangci.yaml | ||
| .goreleaser.yml | ||
| .readthedocs.yaml | ||
| AGENTS.md | ||
| CODEOWNERS | ||
| CONTRIBUTING.md | ||
| Dockerfile | ||
| Dockerfile.debian-stable-slim | ||
| Dockerfile.ubuntu | ||
| LICENSE | ||
| Makefile | ||
| README-zh_CN.md | ||
| README.md | ||
| SECURITY.md | ||
| USERS.md | ||
| go.mod | ||
| go.sum | ||
| main.go | ||
| mkdocs.yml | ||
README.md
Helmfile
Deploy Kubernetes Helm Charts
English | 简体中文
About
Helmfile is a declarative spec for deploying helm charts. It lets you...
- Keep a directory of chart value files and maintain changes in version control.
- Apply CI/CD to configuration changes.
- Periodically sync to avoid skew in environments.
To avoid upgrades for each iteration of helm, the helmfile executable delegates to helm - as a result, the following must be installed
Highlights
Declarative: Write, version-control, apply the desired state file for visibility and reproducibility.
Modules: Modularize common patterns of your infrastructure, distribute it via Git, S3, etc. to be reused across the entire company (See #648)
Versatility: Manage your cluster consisting of charts, kustomizations, and directories of Kubernetes resources, turning everything to Helm releases (See #673)
Patch: JSON/Strategic-Merge Patch Kubernetes resources before helm-installing, without forking upstream charts (See #673)
Status
May 2025 Update
- Helmfile v1.0 and v1.1 has been released. We recommend upgrading directly to v1.1 if you are still using v0.x.
- If you haven't already upgraded, please go over this v1 proposal here to see a small list of breaking changes.
Installation
1: Binary Installation
download one of releases
2: Package Manager
- Archlinux: install via
pacman -S helmfile - openSUSE: install via
zypper in helmfileassuming you are on Tumbleweed; if you are on Leap you must add the kubic repo for your distribution version once before that command, e.g.zypper ar https://download.opensuse.org/repositories/devel:/kubic/openSUSE_Leap_\$releasever kubic - Windows (using scoop):
scoop install helmfile - macOS (using homebrew):
brew install helmfile - Linux/macOS/Windows (using mise):
mise use -g helmfile@latest
3: Container
For more details, see run as a container
Make sure to run
helmfile initonce after installation. Helmfile uses the helm-diff plugin.
Getting Started
Let's start with a simple helmfile and gradually improve it to fit your use-case!
Suppose the helmfile.yaml representing the desired state of your helm releases looks like:
repositories:
- name: prometheus-community
url: https://prometheus-community.github.io/helm-charts
releases:
- name: prom-norbac-ubuntu
namespace: prometheus
chart: prometheus-community/prometheus
set:
- name: rbac.create
value: false
Sync your Kubernetes cluster state to the desired one by running:
helmfile apply
Congratulations! You now have your first Prometheus deployment running inside your cluster.
Iterate on the helmfile.yaml by referencing:
More complex examples
See: multi-env-helmfile
Docs
Please read complete documentation
Contributing
Welcome to contribute together to make helmfile better: contributing doc
Attribution
We use:
- semtag for automated semver tagging. I greatly appreciate the author(pnikosis)'s effort on creating it and their kindness to share it!
Users
Helmfile has been used by many users in production:
For more users, please see: Users