docs: update helmfile skill to reflect v1.1 documentation (#2577)

docs: update helmfile skill to reflect v1.1 documentation (#2576) - Add Helmfile v1.0/v1.1 status and Helm 4 support - Expand release configuration fields with tracking, templating, and ownership options - Add new CLI commands: fetch, unittest, show-dag, write-values, build, cache, create - Add values merging and data flow precedence documentation - Expand hooks with preapply, preuninstall, postuninstall events and kubectlApply - Add kubedog resource tracking (helm/helm-legacy/kubedog modes) - Add JSON patches and template partials documentation - Complete remote secrets (vals) with fetchSecretValue and expandSecretRefs - Add comprehensive repository configuration (OCI, TLS, GPG verify) - Update metadata version to 1.1.0 Signed-off-by: yxxhero <aiopsclub@163.com>
2026-05-04 14:20:17 +08:00 · 2026-05-04 14:20:17 +08:00 · 41d815aa5b
parent 420cc3ba9c
commit 41d815aa5b
3 changed files with 354 additions and 49 deletions
--- a/skills/helmfile/README.md
+++ b/skills/helmfile/README.md
@ -1,6 +1,6 @@
 # Helmfile Agent Skill

-Expert guidance for Helmfile, a declarative spec for deploying Helm charts to Kubernetes.
+Expert guidance for Helmfile v1.1, a declarative spec for deploying Helm charts to Kubernetes.

 ## Installation

@ -32,14 +32,17 @@ cp -r skills/helmfile ~/.agents/skills/

 ## What This Skill Covers

- **Configuration Structure**: Basic helmfile.yaml format and release configuration
- **CLI Commands**: sync, apply, diff, destroy, template, and more
- **Templating**: Built-in objects, template functions, values files templates
- **Environments**: Multi-environment setup and conditional releases
+- **Status**: Helmfile v1.0/v1.1 released, supports Helm 3.x and Helm 4.x
+- **Configuration Structure**: Full helmfile.yaml reference with all release fields
+- **CLI Commands**: sync, apply, diff, destroy, template, fetch, unittest, show-dag, write-values, and more
+- **Templating**: Built-in objects, template functions (env, exec, readFile, fetchSecretValue, expandSecretRefs), partials
+- **Environments**: Multi-environment setup, HCL values, conditional releases
+- **Values Merging**: Data flow and precedence (bases -> root values -> env values -> HCL -> secrets -> CLI overrides)
 - **Layering**: Bases, release templates, nested helmfiles
- **Advanced Features**: Kustomize integration, strategic merge patches, transformers, chart dependencies, remote secrets
- **Best Practices**: Directory structure, DRY configuration, labels filtering
- **Troubleshooting**: Common issues and solutions
+- **Hooks**: Lifecycle hooks (prepare, preapply, presync, preuninstall, postuninstall, postsync, cleanup) with kubectlApply
+- **Advanced Features**: Kubedog resource tracking, Kustomize integration, strategic merge patches, JSON patches, transformers, chart dependencies, remote secrets (vals)
+- **Best Practices**: Directory structure, DRY configuration, labels filtering, missing keys handling
+- **Troubleshooting**: Common issues and solutions, Helm 4 compatibility

 ## Usage

@ -49,9 +52,14 @@ Once installed, simply ask your AI agent questions about Helmfile:
 - "How do I set up multi-environment deployments?"
 - "Explain release templates and layering"
 - "Help me troubleshoot a Helmfile sync issue"
+- "How do I use kubedog for resource tracking?"
+- "Set up hooks for CRD installation before sync"
+- "How do I use vals for remote secrets?"

 ## References

 - [Helmfile Documentation](https://helmfile.readthedocs.io)
 - [Helmfile GitHub](https://github.com/helmfile/helmfile)
 - [Helm Documentation](https://helm.sh)
+- [vals - Secret References](https://github.com/helmfile/vals)
+- [kubedog - Resource Tracking](https://github.com/werf/kubedog)
--- a/skills/helmfile/SKILL.md
+++ b/skills/helmfile/SKILL.md
@ -7,6 +7,10 @@ description: Expert guidance for Helmfile declarative Helm chart deployment

 You are an expert in Helmfile, a declarative spec for deploying Helm charts to Kubernetes clusters.

+## Status
+
+Helmfile v1.0 and v1.1 have been released (May 2025). We recommend upgrading directly to v1.1 if you are still using v0.x. Helmfile supports both Helm 3.x and Helm 4.x.
+
 ## What is Helmfile

 Helmfile is a declarative configuration tool that manages Helm releases. It allows you to:
@ -22,6 +26,24 @@ Helmfile is a declarative configuration tool that manages Helm releases. It allo

 ## Configuration Structure

+### Quick Reference
+
+A `helmfile.yaml` has these top-level sections:
+
+| Section | Purpose |
+|---------|---------|
+| `repositories` | Helm chart repositories to use |
+| `releases` | The Helm releases to deploy (core of helmfile) |
+| `helmDefaults` | Default Helm options for all releases |
+| `environments` | Environment-specific values (dev, staging, prod) |
+| `helmfiles` | Include other helmfile.yaml files (nesting) |
+| `bases` | Shared base files merged before this helmfile |
+| `values` | Default values available in templates |
+| `commonLabels` | Labels applied to all releases |
+| `templates` | Reusable release templates |
+| `hooks` | Global lifecycle hooks |
+| `apiVersions` / `kubeVersion` | Kubernetes version capabilities |
+
 ### Basic helmfile.yaml
 ```yaml
 repositories:
@ -37,21 +59,65 @@ releases:
      - values.yaml
 ```

+### Repository Configuration
+```yaml
+repositories:
+  - name: stable
+    url: https://charts.helm.sh/stable
+  # Git-based repository
+  - name: polaris
+    url: git+https://github.com/reactiveops/polaris@deploy/helm?ref=master
+  # OCI registry with auth
+  - name: roboll
+    url: roboll.io/charts
+    certFile: optional_client_cert
+    keyFile: optional_client_key
+    username: optional_username
+    password: optional_password
+    oci: true
+    passCredentials: true
+    verify: true
+    keyring: path/to/keyring.gpg
+  # Self-signed certificate
+  - name: insecure
+    url: https://charts.example.com
+    caFile: optional_ca_file
+```
+
 ### Release Configuration Fields
-| Field | Description |
-|-------|-------------|
-| `name` | Release name |
-| `namespace` | Target namespace |
-| `chart` | Chart reference (repo/chart or local path) |
-| `version` | Semver constraint |
-| `values` | Values files or inline values |
-| `set`/`setString` | Override specific values |
-| `secrets` | Encrypted values files (requires helm-secrets plugin) |
-| `installed` | Set false to uninstall on sync |
-| `wait` | Wait for resources to be ready |
-| `timeout` | Operation timeout in seconds |
-| `kubeContext` | Kubernetes context to use |
-| `labels` | Key-value pairs for filtering |
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `name` | string | | Release name |
+| `namespace` | string | | Target namespace |
+| `chart` | string | | Chart reference (repo/chart or local path) |
+| `version` | string | | Semver constraint |
+| `values` | list | | Values files or inline values |
+| `set`/`setString` | list | | Override specific values |
+| `secrets` | list | | Encrypted values files (requires helm-secrets plugin) |
+| `installed` | bool | | Set false to uninstall on sync |
+| `condition` | string | | Values lookup key for filtering releases |
+| `wait` | bool | false | Wait for resources to be ready |
+| `waitForJobs` | bool | false | Wait until all Jobs have completed |
+| `timeout` | int | 300 | Operation timeout in seconds |
+| `kubeContext` | string | | Kubernetes context to use |
+| `labels` | map | | Key-value pairs for filtering |
+| `createNamespace` | bool | true | Automatically create release namespace |
+| `missingFileHandler` | string | | "Error" or "Warn" for missing files |
+| `missingFileHandlerConfig` | map | | Additional missing file handler config |
+| `valuesTemplate` | list | | Like `values` but template expressions rendered before passing to Helm |
+| `setTemplate` | list | | Like `set` but template expressions rendered before passing to Helm |
+| `apiVersions` | list | | Per-release API versions |
+| `kubeVersion` | string | | Per-release kube version |
+| `valuesPathPrefix` | string | | Prefix for values file paths |
+| `verifyTemplate` | string | | Templated verify flag |
+| `waitTemplate` | string | | Templated wait flag |
+| `installedTemplate` | string | | Templated installed flag |
+| `adopt` | list | | Resources to adopt (passes `--adopt` to Helm) |
+| `forceGoGetter` | bool | false | Force go-getter URL parsing for chart field |
+| `forceNamespace` | string | | Force namespace on all K8s resources |
+| `skipRefresh` | bool | false | Per-release skip for `helm dependency up` |
+| `disableAutoDetectedKubeVersionForDiff` | bool | false | Disable auto-detected kubeVersion for diff |
+| `takeOwnership` | bool | false | Take ownership of existing resources |

 ### Helm Defaults
 ```yaml
@ -63,6 +129,28 @@ helmDefaults:
  force: false
  atomic: true
  cleanupOnFail: false
+  verify: false
+  keyring: path/to/keyring.gpg
+  skipSchemaValidation: false
+  waitForJobs: true
+  recreatePods: false
+  historyMax: 10
+  devel: false
+  skipDeps: false
+  reuseValues: false
+  enableDNS: false
+  skipCRDs: false
+  skipRefresh: false
+  forceConflicts: false
+  takeOwnership: false
+  trackMode: ""
+  disableAutoDetectedKubeVersionForDiff: false
+  args:
+    - "--set k=v"
+  diffArgs:
+    - "--suppress-secrets"
+  syncArgs:
+    - "--labels=app.kubernetes.io/managed-by=helmfile"
 ```

 ## CLI Commands
@ -79,6 +167,15 @@ helmfile lint                    # Lint charts
 helmfile test                    # Run helm tests
 helmfile list                    # List releases
 helmfile deps                    # Lock dependencies
+helmfile repos                   # Add chart repositories
+helmfile fetch                   # Fetch charts from state file
+helmfile status                  # Retrieve status of releases
+helmfile build                   # Build all resources from state file
+helmfile write-values            # Write values files (like template but for values)
+helmfile unittest                # Unit test charts using helm-unittest plugin
+helmfile show-dag                # Show release dependency graph (GROUP, RELEASE, DEPENDENCIES)
+helmfile cache                   # Cache management
+helmfile create                  # Create a helmfile deployment project scaffold
 ```

 ### Common Flags
@ -91,29 +188,90 @@ helmfile deps                    # Lock dependencies
 | `--kube-context` | Kubernetes context |
 | `--interactive` | Confirm before changes |
 | `--skip-deps` | Skip dependency updates |
+| `--allow-no-matching-release` | Don't error if selector has no matches |
+| `-c, --chart` | Set chart (available in template as {{ .Chart }}) |
+| `--color` | Output with color |
+| `--debug` | Enable verbose output |
+| `--state-values-set` | Override state values from CLI |
+| `--state-values-file` | Override state values from file |
+| `--track-mode` | Resource tracking mode (helm, helm-legacy, kubedog) |
+| `--track-timeout` | Tracking timeout in seconds |
+| `--track-logs` | Enable real-time log streaming |
+
+### Fetch Command (Air-gapped Environments)
+```bash
+helmfile fetch --output-dir ./charts --write-output
+```
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--output-dir` | temp dir | Directory to store charts |
+| `--output-dir-template` | default template | Go template for output dir (`.OutputDir`, `.ChartName`, `.Release.*`, `.Environment.*`) |
+| `--write-output` | false | Write helmfile.yaml with updated chart paths to stdout |
+| `--concurrency` | 0 | Max concurrent helm processes |
+
+### Show DAG
+```bash
+helmfile show-dag
+```
+Prints a table with GROUP, RELEASE, and DEPENDENCIES. Releases in the same GROUP are deployed concurrently. GROUP 2 starts only after GROUP 1 completes.
+
+### Unit Tests
+```bash
+helmfile unittest                  # Requires helm-unittest plugin
+```
+```yaml
+releases:
+  - name: my-app
+    chart: ./charts/my-app
+    values:
+      - values.yaml
+    unitTests:
+      - tests      # Relative to chart dir, /*_test.yaml appended
+```

 ## Templating

 ### Built-in Objects
 - `.Environment.Name` - Current environment name
 - `.Environment.KubeContext` - Environment's kube context
- `.Values` / `.StateValues` - Environment values
+- `.Values` / `.StateValues` - Environment values (`.StateValues` is an alias)
 - `.Release.Name` - Release name
 - `.Release.Namespace` - Release namespace
 - `.Release.Labels` - Release labels
 - `.Namespace` - Target namespace
+- `.Chart` - Chart set via `--chart` flag
+- `.HelmfileCommand` - The helmfile command being run
+
+### Helmfile .Values vs Helm .Values
+Helmfile uses the same `.Values` name as Helm. To distinguish, use `.StateValues` for Helmfile's values:
+```yaml
+app:
+  project: {{.Environment.Name}}-{{.StateValues.project}}
+
+{{`
+extraEnvVars:
+- name: APP_PROJECT
+  value: {{.Values.app.project}}
+`}}
+```

 ### Template Functions
 | Function | Description |
 |----------|-------------|
 | `env "VAR"` | Get optional env var (returns empty if unset) |
 | `requiredEnv "VAR"` | Get required env var (fails if unset) |
-| `exec "cmd" (list "args")` | Execute command |
+| `exec "cmd" (list "args")` | Execute command, return stdout |
+| `envExec (dict "k" "v") "cmd" (list "args")` | Execute command with custom env vars |
 | `readFile "path"` | Read file contents |
+| `readDir "path"` | List file paths in directory |
+| `readDirEntries "path"` | List all entries including folders |
+| `isFile "path"` | Check if file exists |
+| `isDir "path"` | Check if directory exists |
 | `toYaml` / `fromYaml` | YAML conversion |
 | `get .Values "key" default` | Get nested value with default |
 | `required "msg" value` | Fail if value is empty |
-| `fetchSecretValue "ref"` | Fetch secret from vals backend |
+| `fetchSecretValue "ref"` | Fetch single secret from vals backend |
+| `expandSecretRefs` | Fetch map of secrets from vals refs |
 | `tpl "{{ .Value.key }}" .` | Render template string |

 ### Values Files Templates
@ -125,6 +283,15 @@ db:
  password: {{ requiredEnv "DB_PASSWORD" }}
 ```

+### Template Partials
+Files matching `_*.tpl` in the same directory are auto-loaded as helpers:
+```
+{{- define "myapp.labels" -}}
+app: myapp
+env: {{ .Environment.Name }}
+{{- end -}}
+```
+
 ## Environments

 ### Environment Configuration
@ -133,12 +300,18 @@ environments:
  default:
    values:
      - environments/default/values.yaml
+      - environments/default/values.hcl
+      - myChartVer: 1.0.0-dev
  production:
    values:
      - environments/production/values.yaml
+      - myChartVer: 1.0.0
+      - vault:
+          enabled: false
    secrets:
      - environments/production/secrets.yaml
    kubeContext: prod-cluster
+    missingFileHandler: Error
 ```

 ### Using Environments
@ -155,6 +328,31 @@ releases:
    chart: stable/prometheus
 ```

+## Values Merging and Data Flow
+
+Values are merged in this order (lowest to highest priority):
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    VALUES MERGING ORDER                         │
+├─────────────────────────────────────────────────────────────────┤
+│  1. Base files (from `bases:`)                                  │
+│  2. Root-level `values:` block (Defaults)                       │
+│  3. Environment values (yaml/yaml.gotmpl)                       │
+│  4. Environment values (HCL, including HCL secrets)             │
+│  5. Environment secrets (non-HCL, decrypted)                    │
+│  6. CLI overrides (--state-values-set, --state-values-file)     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Later values override earlier values** at the map level (deep merge). Arrays use smart merging (sparse auto-detection by default).
+
+```bash
+# CLI overrides (highest priority)
+helmfile --state-values-set image.tag=v2.0.0 sync
+helmfile --state-values-file overrides.yaml sync
+```
+
 ## Layering and Inheritance

 ### Bases (Layering)
@ -188,8 +386,81 @@ helmfiles:
      - {{ toYaml .Values | nindent 4 }}
 ```

+## Hooks
+
+### Hook Events
+| Event | Description |
+|-------|-------------|
+| `prepare` | After release loaded from YAML, before execution |
+| `preapply` | Before uninstall/install/upgrade during `apply` (only if changes exist) |
+| `presync` | Before each release is synced (installed or upgraded) |
+| `preuninstall` | Immediately before a release is uninstalled |
+| `postuninstall` | After successful uninstall of a release |
+| `postsync` | After each release is synced, regardless of success |
+| `cleanup` | After each release is processed (counterpart to `prepare`) |
+
+### Hook Configuration
+```yaml
+releases:
+  - name: myapp
+    chart: mychart
+    hooks:
+      - events: ["prepare", "cleanup"]
+        showlogs: true
+        command: "echo"
+        args: ["{{`{{.Environment.Name}}`}}", "{{`{{.Release.Name}}`}}"]
+      - events: ["presync"]
+        showlogs: true
+        command: "kubectl"
+        args: ["apply", "-f", "crds.yaml"]
+      - events: ["postsync"]
+        showlogs: true
+        command: "kubectl"
+        args: ["rollout", "status", "deployment/myapp"]
+```
+
+### kubectlApply Hook
+Alternative to `command`/`args`, directly apply manifests:
+```yaml
+hooks:
+  - events: ["presync"]
+    kubectlApply:
+      - apiVersion: v1
+        kind: ConfigMap
+        metadata:
+          name: my-config
+        data:
+          key: value
+```
+
 ## Advanced Features

+### Resource Tracking with Kubedog
+```yaml
+releases:
+  - name: myapp
+    chart: ./charts/myapp
+    trackMode: kubedog
+    trackTimeout: 300
+    trackLogs: true
+    trackKinds:
+      - Deployment
+      - StatefulSet
+    skipKinds:
+      - ConfigMap
+    trackResources:
+      - kind: Deployment
+        name: myapp-deployment
+        namespace: default
+```
+
+**Track Modes:**
+| Mode | Description |
+|------|-------------|
+| `helm` (default) | Uses Helm's built-in `--wait` |
+| `helm-legacy` | Uses Helm v4's `--wait=legacy` for compatibility |
+| `kubedog` | Advanced tracking with detailed feedback |
+
 ### Kustomize Integration
 Deploy kustomizations as Helm releases:
 ```yaml
@ -208,13 +479,36 @@ releases:
 releases:
  - name: raw1
    chart: incubator/raw
+    values:
+      - resources:
+        - apiVersion: v1
+          kind: ConfigMap
+          metadata:
+            name: raw1
+          data:
+            foo: FOO
    strategicMergePatches:
      - apiVersion: v1
        kind: ConfigMap
        metadata:
          name: raw1
        data:
-          extra: value
+          bar: BAR
+```
+
+### JSON Patches
+```yaml
+releases:
+  - name: myapp
+    chart: mychart
+    jsonPatches:
+      - target:
+          version: v1
+          kind: ConfigMap
+          name: myconfig
+        patch:
+          - op: remove
+            path: /data/old-key
 ```

 ### Transformers
@ -246,13 +540,30 @@ releases:

 ### Remote Secrets (vals)
 ```yaml
+# Single key
 releases:
  - name: app
    values:
      - db:
-          password: ref+awssecrets://my-secret/db-password
+          password: {{ .Values.db.password | fetchSecretValue | quote }}
+
+# Multiple keys
+environments:
+  default:
+    values:
+      - service:
+          password: ref+vault://svc/#pass
+          login: ref+vault://svc/#login
 ```

+```yaml
+# values.yaml.gotmpl
+service:
+{{ .Values.service | expandSecretRefs | toYaml | nindent 2 }}
+```
+
+Supported backends: Vault, AWS SSM, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, and more via [vals](https://github.com/helmfile/vals).
+
 ## Best Practices

 ### Directory Structure
@ -277,6 +588,7 @@ releases:
 2. Use `bases` for shared configuration
 3. Use `environments` for environment-specific values
 4. Use `.gotmpl` files for templated values
+5. Use `_*.tpl` partials for shared template logic

 ### Missing Keys Handling
 ```yaml
@ -327,13 +639,6 @@ releases:
      - replicaCount: {{ .Values.replicas }}
 ```

-### Git-based Charts
-```yaml
-repositories:
-  - name: polaris
-    url: git+https://github.com/reactiveops/polaris@deploy/helm?ref=master
-```
-
 ### OCI Charts
 ```yaml
 repositories:
@ -347,18 +652,6 @@ releases:
    version: 1.0.0
 ```

-### Hooks
-```yaml
-releases:
-  - name: crds
-    chart: ./crds
-    hooks:
-      - events: ["presync"]
-        showlogs: true
-        command: "kubectl"
-        args: ["apply", "-f", "crds.yaml"]
-```
-
 ## Troubleshooting

 ### Debug Template Rendering
@ -378,6 +671,7 @@ helmfile list
 2. **Chart not found**: Run `helmfile deps` or check repository config
 3. **Diff plugin missing**: Install with `helm plugin install https://github.com/databus23/helm-diff`
 4. **Secrets not decrypting**: Install helm-secrets plugin
+5. **Helm v4 compatibility**: Use `trackMode: helm-legacy` for charts with broken `livenessProbe` configs

 ## Environment Variables
 | Variable | Description |
@ -399,3 +693,6 @@ Invoke this skill when:
 - Implementing best practices for Helm chart management
 - Configuring remote secrets with vals
 - Using advanced features like strategic merge patches and transformers
+- Setting up resource tracking with kubedog
+- Managing Helm 4 compatibility
+- Writing hooks for lifecycle management
--- a/skills/helmfile/metadata.json
+++ b/skills/helmfile/metadata.json
@ -1,8 +1,8 @@
 {
-  "version": "1.0.0",
+  "version": "1.1.0",
  "organization": "Helmfile",
-  "date": "February 2026",
-  "abstract": "Comprehensive guide for Helmfile, a declarative spec for deploying Helm charts to Kubernetes. Covers configuration structure, CLI commands, templating, environments, layering, release templates, Kustomize integration, strategic merge patches, transformers, chart dependencies, remote secrets, and best practices. Designed for AI agents working with Helmfile configurations and Kubernetes deployments.",
+  "date": "May 2026",
+  "abstract": "Comprehensive guide for Helmfile v1.1, a declarative spec for deploying Helm charts to Kubernetes. Covers configuration structure, CLI commands, templating, environments, values merging and data flow, layering, release templates, hooks (prepare, presync, postsync, cleanup), Kustomize integration, strategic merge patches, JSON patches, transformers, chart dependencies, remote secrets (vals), resource tracking with kubedog, Helm 4 support, and best practices. Designed for AI agents working with Helmfile configurations and Kubernetes deployments.",
  "references": [
    "https://helmfile.readthedocs.io",
    "https://github.com/helmfile/helmfile",