helmfile/docs
yxxhero 58df057dcc
fix: skip cache refresh for shared cache paths to prevent race conditions (#2396)
* 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>
2026-02-14 10:46:05 +08:00
..
proposals feat(docs): add proposal to remove charts and delete subcommands (#1936) 2025-02-24 08:11:15 -05:00
advanced-features.md chore: documentation updates: grammar & rm whitespace (#1639) 2024-07-21 13:31:41 +08:00
builtin-objects.md Expose release version as .Release.ChartVersion for templating (#2080) 2025-06-17 19:41:42 +08:00
contributing.md Documentation site based on mkdocs and Read the Docs 2022-04-03 05:04:54 +00:00
experimental-features.md v1: Document experimental features (#1512) 2024-05-09 10:18:29 +08:00
hcl_funcs.md Feature/support env hcl and interpolations (#1423) 2024-04-22 08:02:14 +08:00
index.md fix: skip cache refresh for shared cache paths to prevent race conditions (#2396) 2026-02-14 10:46:05 +08:00
license.md Documentation site based on mkdocs and Read the Docs 2022-04-03 05:04:54 +00:00
paths.md update examples info (#658) 2023-01-26 07:34:43 +09:00
remote-secrets.md update example chart URL in remote-secrets doc (#1809) 2024-11-28 13:19:08 +08:00
requirements.txt build(deps): bump jinja2 from 3.1.5 to 3.1.6 in /docs (#1956) 2025-03-05 23:20:16 +00:00
shared-configuration-across-teams.md chore: documentation updates: grammar & rm whitespace (#1639) 2024-07-21 13:31:41 +08:00
templating_funcs.md feat: add isDir template function (#1657) 2024-08-06 21:39:00 +08:00
users.md Documentation site based on mkdocs and Read the Docs 2022-04-03 05:04:54 +00:00
writing-helmfile.md Allow secrets to be excluded from release template inheritance (#1189) 2023-12-05 18:17:48 +08:00