helm

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Helm

Helm 4 chart development and operations with security-first defaults.

基于安全优先默认配置的Helm 4 Chart开发与运维

What This Skill Does

本技能的功能

Chart Development:

Creates production charts with library pattern (reusable base + thin apps)
Generates templates, helpers, hooks, and dependencies
Auto-detects from Dockerfile: ports, health endpoints, resources
Supports umbrella charts for multi-service deployments
Adds values schema validation (JSON Schema)

Release Management:

Install, upgrade, rollback with atomic operations
Release history and status inspection
Values precedence management across environments
Hook lifecycle (pre-install, pre-upgrade, post-upgrade, test)

Registry & Distribution:

OCI registry workflows (push, pull, digest pinning)
Chart versioning and artifact management
GitOps integration (ArgoCD, Flux)

Debugging:

Template rendering and debugging workflow
Failed release recovery (stuck states, hook failures)
Values resolution tracing
Policy validation (OPA/Kyverno, security scanning)

Chart开发：

创建采用Library模式的生产级Chart（可复用基础模板+轻量应用）
生成模板、助手函数、钩子（Hook）与依赖配置
从Dockerfile自动检测：端口、健康检查端点、资源配置
支持用于多服务部署的Umbrella Chart
添加Values Schema验证（JSON Schema）

发布管理：

支持原子化操作的安装、升级、回滚
发布历史与状态查看
跨环境的Values优先级管理
钩子生命周期管理（pre-install、pre-upgrade、post-upgrade、test）

镜像仓库与分发：

OCI镜像仓库工作流（推送、拉取、摘要固定）
Chart版本管理与制品管理
GitOps集成（ArgoCD、Flux）

调试：

模板渲染与调试流程
失败发布恢复（卡住状态、钩子失败）
Values解析追踪
策略验证（OPA/Kyverno、安全扫描）

What This Skill Does NOT Do

本技能不支持的功能

Generate raw Kubernetes manifests (use kubernetes skill)
Create Kustomize-only overlays without Helm
Deploy Operators/CRDs (chart can include, but not operator setup)
Manage cluster infrastructure (use kubernetes skill)
Handle non-Helm deployments

生成原生Kubernetes清单文件（请使用Kubernetes技能）
创建不含Helm的纯Kustomize覆盖层
部署Operator/CRD（Chart可包含相关资源，但不支持Operator配置）
管理集群基础设施（请使用Kubernetes技能）
处理非Helm部署

Before Implementation

实施前准备

Source	Gather
Codebase	Dockerfile, existing charts, values patterns
Conversation	Target environment, chart name, special requirements
Skill References	Chart patterns, Helm 4 features, hooks, security
kubernetes skill	Manifest patterns for templates (complementary)

来源	需收集的信息
代码库	Dockerfile、现有Chart、Values配置模式
对话内容	目标环境、Chart名称、特殊需求
技能参考文档	Chart模式、Helm 4特性、钩子、安全配置
Kubernetes技能	用于模板的清单模式（互补）

Required Clarifications

需确认的模糊点

After auto-detection, confirm if ambiguous:

Question	When to Ask
Chart type	"Creating new chart, library chart, or umbrella chart?"
Target registry	"OCI registry (GHCR, ECR, Harbor) or Git repo for GitOps?"
Environment strategy	"Single values file or per-environment overlays (dev/staging/prod)?"
Release namespace	"Deploy to specific namespace or chart-managed?"

自动检测后，若存在模糊内容请确认：

问题	询问时机
Chart类型	"需要创建普通应用Chart、Library Chart还是Umbrella Chart？"
目标镜像仓库	"目标是OCI镜像仓库（GHCR、ECR、Harbor）还是用于GitOps的Git仓库？"
环境策略	"使用单一Values文件还是分环境覆盖层（dev/staging/prod）？"
发布命名空间	"部署到指定命名空间还是由Chart管理命名空间？"

Helm 4 Defaults (CRITICAL)

Helm 4默认配置（重点）

Helm 4 introduces breaking changes from v3:

Feature	Helm 4 Behavior	Notes
Server-Side Apply	Default ON	Better conflict detection, GitOps alignment
kstatus watching	Accurate health	Replaces old `--wait` behavior
OCI-first	Native support	`oci://` protocol, digest pinning
Wasm plugins	Sandboxed	Post-renderers require plugin format

See

references/helm4-features.md

for migration guidance.

Helm 4相比v3版本引入了破坏性变更：

特性	Helm 4行为	说明
Server-Side Apply	默认开启	更优的冲突检测，与GitOps更适配
kstatus状态监控	精准的健康检查	替代旧版 `--wait` 行为
OCI优先	原生支持	`oci://` 协议、摘要固定
Wasm插件	沙箱化	后渲染器需采用插件格式

迁移指导请查看

references/helm4-features.md

。

Auto-Detection Matrix

自动检测矩阵

From Dockerfile

从Dockerfile检测

Detect	How	Chart Generation
Port	EXPOSE	`containerPort` in deployment template
Health	CMD pattern	Liveness/readiness probe paths
User	USER instruction	`securityContext.runAsUser`
Base image	FROM	Resource hints (alpine=small, python=medium)

检测项	检测方式	Chart生成逻辑
端口	EXPOSE指令	在Deployment模板中生成 `containerPort`
健康检查	CMD模式	生成存活/就绪探针路径
用户	USER指令	配置 `securityContext.runAsUser`
基础镜像	FROM指令	资源配置提示（alpine=轻量、python=中等）

From Code

从代码检测

Detect	How	Chart Generation
Framework	imports/deps	Health endpoint patterns
GPU deps	torch, tensorflow	tolerations, nodeSelector, GPU resources
Sidecar needs	dapr.io, istio	Annotations for injection

检测项	检测方式	Chart生成逻辑
框架	导入包/依赖	健康检查端点模式
GPU依赖	torch、tensorflow	污点容忍、节点选择器、GPU资源配置
Sidecar需求	dapr.io、istio	注入用注解

Workflow

工作流

1. PRE-FLIGHT
   - Verify helm version (v4.x required)
   - Check target registry/cluster access
   - Identify existing charts
         ↓
2. ANALYZE PROJECT
   - Read Dockerfile for detection
   - Scan code for patterns
   - Check existing values patterns
         ↓
3. DETERMINE CHART TYPE
   - Application chart (default)
   - Library chart (reusable templates)
   - Umbrella chart (multi-service)
         ↓
4. GENERATE CHART
   - Chart.yaml with dependencies
   - values.yaml with schema
   - Templates with helpers
   - Hooks if lifecycle needs
         ↓
5. VALIDATE
   - helm lint
   - helm template --debug
   - helm install --dry-run
   - Policy validation (optional)
         ↓
6. DELIVER
   - Chart in charts/ directory
   - Summary of what was created
   - Next steps (push to registry, GitOps setup)

1. 预检查
   - 验证Helm版本（需v4.x）
   - 检查目标镜像仓库/集群访问权限
   - 识别现有Chart
         ↓
2. 项目分析
   - 读取Dockerfile进行检测
   - 扫描代码中的模式
   - 检查现有Values配置模式
         ↓
3. 确定Chart类型
   - 应用Chart（默认）
   - Library Chart（可复用模板）
   - Umbrella Chart（多服务）
         ↓
4. 生成Chart
   - 包含依赖的Chart.yaml
   - 带Schema的values.yaml
   - 含助手函数的模板
   - 若有生命周期需求则添加钩子
         ↓
5. 验证
   - helm lint
   - helm template --debug
   - helm install --dry-run
   - 策略验证（可选）
         ↓
6. 交付
   - Chart存储在charts/目录
   - 创建内容摘要
   - 后续步骤（推送到镜像仓库、GitOps配置）

Chart Structure (Library Pattern)

Chart结构（Library模式）

charts/
├── myapp-lib/                    # Library chart (reusable)
│   ├── Chart.yaml                # type: library
│   ├── templates/
│   │   ├── _deployment.tpl       # Reusable deployment template
│   │   ├── _service.tpl          # Reusable service template
│   │   ├── _helpers.tpl          # Common helpers
│   │   └── _security.tpl         # Security context helpers
│   └── values.yaml               # Default values
│
└── myapp/                        # Application chart (thin)
    ├── Chart.yaml                # Dependencies: myapp-lib
    ├── templates/
    │   ├── deployment.yaml       # {{ include "myapp-lib.deployment" . }}
    │   ├── service.yaml          # {{ include "myapp-lib.service" . }}
    │   └── _helpers.tpl          # App-specific helpers
    ├── values.yaml               # App defaults
    ├── values.schema.json        # Schema validation
    └── values/                   # Environment overlays
        ├── dev.yaml
        ├── staging.yaml
        └── prod.yaml

charts/
├── myapp-lib/                    # Library Chart（可复用）
│   ├── Chart.yaml                # type: library
│   ├── templates/
│   │   ├── _deployment.tpl       # 可复用Deployment模板
│   │   ├── _service.tpl          # 可复用Service模板
│   │   ├── _helpers.tpl          # 通用助手函数
│   │   └── _security.tpl         # 安全上下文助手函数
│   └── values.yaml               # 默认配置
│
└── myapp/                        # 应用Chart（轻量）
    ├── Chart.yaml                # 依赖：myapp-lib
    ├── templates/
    │   ├── deployment.yaml       # {{ include "myapp-lib.deployment" . }}
    │   ├── service.yaml          # {{ include "myapp-lib.service" . }}
    │   └── _helpers.tpl          # 应用专属助手函数
    ├── values.yaml               # 应用默认配置
    ├── values.schema.json        # Schema验证
    └── values/                   # 环境覆盖层
        ├── dev.yaml
        ├── staging.yaml
        └── prod.yaml

Core Templates

核心模板

Chart.yaml (Application)

Chart.yaml（应用Chart）

yaml

apiVersion: v2
name: myapp
version: 0.1.0                    # Chart version (SemVer)
appVersion: "1.0.0"               # App version
type: application                 # or: library
description: |
  Brief description of what this chart deploys.

yaml

apiVersion: v2
name: myapp
version: 0.1.0                    # Chart版本（语义化版本）
appVersion: "1.0.0"               # 应用版本
type: application                 # 或：library
description: |
  本Chart部署内容的简要说明。

Dependencies (subchart pattern)

依赖（子Chart模式）

dependencies:

name: myapp-lib version: ">=0.1.0" repository: "oci://ghcr.io/myorg/charts"
name: redis version: "17.x.x" repository: "oci://registry-1.docker.io/bitnamicharts" condition: redis.enabled # Conditional dependency

dependencies:

name: myapp-lib version: ">=0.1.0" repository: "oci://ghcr.io/myorg/charts"
name: redis version: "17.x.x" repository: "oci://registry-1.docker.io/bitnamicharts" condition: redis.enabled # 条件依赖

Kubernetes version constraint

Kubernetes版本约束

kubeVersion: ">=1.25.0"

Maintainers

维护者

maintainers:

name: DevRaftel email: team@devraftel.com

undefined

maintainers:

name: DevRaftel email: team@devraftel.com

undefined

values.yaml (Structured)

values.yaml（结构化）

yaml

undefined

yaml

undefined

-- Number of replicas

-- 副本数量

replicaCount: 2

image:

-- Container image repository

repository: myorg/myapp

-- Image pull policy

pullPolicy: IfNotPresent

-- Image tag (defaults to appVersion)

tag: ""

replicaCount: 2

image:

-- 容器镜像仓库

repository: myorg/myapp

-- 镜像拉取策略

pullPolicy: IfNotPresent

-- 镜像标签（默认使用appVersion）

tag: ""

-- Resource requests and limits

-- 资源请求与限制

resources: requests: cpu: "100m" memory: "128Mi" limits: cpu: "500m" memory: "512Mi"

-- Security context (pod level)

-- 安全上下文（Pod级别）

podSecurityContext: runAsNonRoot: true runAsUser: 1000 fsGroup: 1000

-- Security context (container level)

-- 安全上下文（容器级别）

securityContext: allowPrivilegeEscalation: false readOnlyRootFilesystem: true capabilities: drop: ["ALL"]

-- Service configuration

-- Service配置

service: type: ClusterIP port: 80 targetPort: 8080

-- Health probes

-- 健康探针

probes: liveness: path: /health/live initialDelaySeconds: 10 readiness: path: /health/ready initialDelaySeconds: 5

-- Enable autoscaling

-- 启用自动扩缩容

autoscaling: enabled: false minReplicas: 2 maxReplicas: 10 targetCPUUtilization: 80

---

autoscaling: enabled: false minReplicas: 2 maxReplicas: 10 targetCPUUtilization: 80

---

Command Reference

命令参考

Chart Development

Chart开发

bash

undefined

bash

undefined

Create new chart

创建新Chart

helm create myapp

Lint chart

检查Chart语法

helm lint ./myapp

Render templates locally

本地渲染模板

helm template myapp ./myapp -f values.yaml

Render with debug (shows template errors)

调试模式渲染（显示模板错误）

helm template myapp ./myapp --debug 2>&1 | head -100

Package chart

打包Chart

helm package ./myapp

Update dependencies

更新依赖

helm dependency update ./myapp helm dependency build ./myapp

undefined

helm dependency update ./myapp helm dependency build ./myapp

undefined

Release Management

发布管理

bash

undefined

bash

undefined

Install release

安装发布

helm install myapp ./myapp -n namespace --create-namespace

Install with atomic (rollback on failure)

原子化安装（失败时自动回滚）

helm install myapp ./myapp --atomic --timeout 5m

Upgrade release

升级发布

helm upgrade myapp ./myapp --atomic

Upgrade or install

升级或安装（不存在则安装）

helm upgrade --install myapp ./myapp

Rollback to previous

回滚到上一版本

helm rollback myapp 1

Uninstall

卸载发布

helm uninstall myapp -n namespace

Release status

查看发布状态

helm status myapp helm history myapp

undefined

helm status myapp helm history myapp

undefined

OCI Registry

OCI镜像仓库

bash

undefined

bash

undefined

Login to registry

登录镜像仓库

helm registry login ghcr.io -u USERNAME

Push chart to OCI

将Chart推送到OCI仓库

helm push myapp-0.1.0.tgz oci://ghcr.io/myorg/charts

Pull from OCI

从OCI仓库拉取Chart

helm pull oci://ghcr.io/myorg/charts/myapp --version 0.1.0

Install from OCI

从OCI仓库安装Chart

helm install myapp oci://ghcr.io/myorg/charts/myapp --version 0.1.0

undefined

helm install myapp oci://ghcr.io/myorg/charts/myapp --version 0.1.0

undefined

Debugging

调试

bash

undefined

bash

undefined

Get release manifest

获取发布清单

helm get manifest myapp

Get computed values

获取计算后的Values

helm get values myapp helm get values myapp --all # Including defaults

helm get values myapp helm get values myapp --all # 包含默认值

Get hooks

获取钩子

helm get hooks myapp

Dry-run against cluster

集群环境预安装检查

helm install myapp ./myapp --dry-run --debug

Diff before upgrade (requires helm-diff plugin)

升级前对比差异（需要helm-diff插件）

helm diff upgrade myapp ./myapp

---

helm diff upgrade myapp ./myapp

---

Validation Pipeline

验证流水线

Before delivering charts, run:

bash

undefined

交付Chart前请执行以下步骤：

bash

undefined

1. Lint

1. 语法检查

helm lint ./myapp --strict

2. Template render

2. 模板渲染

helm template myapp ./myapp --debug > /dev/null

3. Dry-run against cluster

3. 集群环境预安装检查

helm install myapp ./myapp --dry-run --debug -n test

4. Schema validation (if values.schema.json exists)

4. Schema验证（若存在values.schema.json）

helm lint ./myapp # Automatically validates against schema

helm lint ./myapp # 自动基于Schema验证

5. Policy validation (optional)

5. 策略验证（可选）

OPA/Conftest

conftest test ./myapp/templates/

Trivy for security scanning

Trivy安全扫描

trivy config ./myapp/

---

trivy config ./myapp/

---

Output Checklist

输出检查清单

Before delivering, verify:

交付前请验证：

Chart Structure

Chart结构

Chart.yaml has apiVersion: v2, valid version, kubeVersion
values.yaml has comments for helm-docs
values.schema.json for validation
Templates use
```
_helpers.tpl
```
for reusable definitions

Chart.yaml包含apiVersion: v2、有效版本、kubeVersion
values.yaml包含用于helm-docs的注释
存在values.schema.json用于验证
模板使用
```
_helpers.tpl
```
定义可复用内容

Security

安全配置

```
securityContext
```
in values with secure defaults
No secrets in values.yaml (use external secrets)
```
runAsNonRoot: true
```
in pod security context
Resource limits defined

values中包含安全上下文的安全默认配置
values.yaml中未包含敏感信息（使用外部密钥管理）
Pod安全上下文配置
```
runAsNonRoot: true
```
定义了资源限制

Best Practices

最佳实践

Labels follow
```
app.kubernetes.io/*
```
standard
Health probes configurable via values
Supports multiple environments (values overlays)
Hooks have deletion policies

标签遵循
```
app.kubernetes.io/*
```
标准
健康探针可通过Values配置
支持多环境（Values覆盖层）
钩子配置了删除策略

Validation

验证

```
helm lint
```
passes without warnings
```
helm template --debug
```
renders successfully
```
helm install --dry-run
```
succeeds against cluster

```
helm lint
```
无警告通过
```
helm template --debug
```
渲染成功
```
helm install --dry-run
```
在集群环境中执行成功

GitOps Ready

GitOps就绪

Chart versioned with SemVer
OCI-pushable (no local dependencies)
ArgoCD/Flux compatible structure

Chart采用语义化版本管理
可推送到OCI仓库（无本地依赖）
结构兼容ArgoCD/Flux

Reference Files

参考文档

Always Read First

必读文档

File	Purpose
`references/chart-development.md`	CRITICAL: Template syntax, helpers, hooks
`references/values-patterns.md`	CRITICAL: Precedence, environments, schema
`references/helm4-features.md`	CRITICAL: SSA, Wasm, kstatus, OCI

文件	用途
`references/chart-development.md`	重点：模板语法、助手函数、钩子
`references/values-patterns.md`	重点：优先级、环境配置、Schema
`references/helm4-features.md`	重点：SSA、Wasm、kstatus、OCI

Operations

运维相关

File	When to Read
`references/release-management.md`	Install, upgrade, rollback, atomic
`references/oci-workflows.md`	Push, pull, registry auth, digest
`references/debugging-workflow.md`	Template errors, failed releases
`references/testing-validation.md`	Lint, unittest, dry-run, integration tests

文件	阅读时机
`references/release-management.md`	安装、升级、回滚、原子化操作
`references/oci-workflows.md`	推送、拉取、仓库认证、摘要固定
`references/debugging-workflow.md`	模板错误、失败发布
`references/testing-validation.md`	语法检查、单元测试、预安装检查、集成测试

Integration

集成相关

File	When to Read
`references/gitops-integration.md`	ArgoCD, Flux, ApplicationSet
`references/umbrella-patterns.md`	Multi-service, subcharts, Kustomize
`references/ai-agent-patterns.md`	GPU, models, sidecars, KEDA

文件	阅读时机
`references/gitops-integration.md`	ArgoCD、Flux、ApplicationSet
`references/umbrella-patterns.md`	多服务、子Chart、Kustomize
`references/ai-agent-patterns.md`	GPU、模型、Sidecar、KEDA

Security & Compliance

安全与合规

File	When to Read
`references/security-patterns.md`	Secrets (ESO, Sealed), RBAC, policies
`references/hooks-lifecycle.md`	Hook types, weights, deletion policies

文件	阅读时机
`references/security-patterns.md`	密钥管理（ESO、Sealed）、RBAC、策略
`references/hooks-lifecycle.md`	钩子类型、权重、删除策略