helm-values-management

Helm Values 管理

全面介绍如何跨环境管理 Helm values、理解覆盖优先级，以及高级配置策略。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 ……
设计按环境划分的 values 文件（dev/staging/prod）并确定覆盖优先级	如果重点是 install/upgrade 命令本身，而不是 values 结构，请使用 helm-release-management
分析 --set、--set-string、--values 和 --reuse-values 的行为	如果 values 渲染生成了错误的 YAML，或出现值类型错误，请使用 helm-debugging
添加 values 架构验证或密钥注入模式	如果 values 架构位于你正在编写的 chart 中，请使用 helm-chart-development

何时使用

在以下情况下自动使用此技能：

• 用户需要使用自定义 values 配置 Helm 部署
• 用户提及特定环境的配置（dev/staging/prod）
• 用户询问值覆盖优先级或合并方式
• 用户需要管理密钥或敏感配置
• 用户想了解已部署的 values
• 用户需要验证或检查 values

值覆盖优先级

Values 按从右到左的优先级合并（最后一个生效）：

1. Chart defaults (values.yaml in chart)
   ↓
2. Parent chart values (if subchart)
   ↓
3. Previous release values (--reuse-values)
   ↓
4. Values files in order (-f values1.yaml -f values2.yaml)
   ↓
5. Individual overrides (--set, --set-string, --set-json, --set-file)
   ↑
   HIGHEST PRECEDENCE

优先级示例

# Chart values.yaml
replicaCount: 1
image:
  tag: "1.0.0"

# -f base.yaml
replicaCount: 2

# -f production.yaml
image:
  tag: "2.0.0"

# --set replicaCount=5

# RESULT:
# replicaCount: 5        (from --set, highest precedence)
# image.tag: "2.0.0"     (from production.yaml)

核心值命令

查看默认 Values

# Show chart default values
helm show values <chart>

# Show values from specific chart version
helm show values <chart> --version 1.2.3

# Save defaults to file
helm show values bitnami/nginx > default-values.yaml

查看已部署的 Values

# Get values used in deployed release
helm get values <release> --namespace <namespace>

# Get ALL values (including defaults)
helm get values <release> --namespace <namespace> --all

# Get values in different formats
helm get values <release> -n <namespace> -o json

# Get values from specific revision
helm get values <release> -n <namespace> --revision 2

在安装/升级期间设置 Values

# Using values file
helm install myapp ./chart \
  --namespace prod \
  --values values.yaml

# Using multiple values files (right-most wins)
helm install myapp ./chart \
  --namespace prod \
  -f values/base.yaml \
  -f values/production.yaml

# Using --set for individual values
helm install myapp ./chart \
  --namespace prod \
  --set replicaCount=3 \
  --set image.tag=v2.0.0

# Using --set-string to force string type
helm install myapp ./chart \
  --namespace prod \
  --set-string version="1.0"

# Using --set-json for complex structures
helm install myapp ./chart \
  --namespace prod \
  --set-json 'nodeSelector={"disktype":"ssd","region":"us-west"}'

# Using --set-file to read value from file
helm install myapp ./chart \
  --namespace prod \
  --set-file tlsCert=./certs/tls.crt

值复用策略

# Reuse existing values, merge with new
helm upgrade myapp ./chart \
  --namespace prod \
  --reuse-values \
  --set image.tag=v2.0.0

# Reset to chart defaults, ignore existing values
helm upgrade myapp ./chart \
  --namespace prod \
  --reset-values \
  -f new-values.yaml

多环境值管理

目录结构

project/
├── charts/
│   └── myapp/           # Helm chart
│       ├── Chart.yaml
│       ├── values.yaml  # Chart defaults
│       └── templates/
└── values/              # Environment-specific values
    ├── common.yaml      # Shared across all environments
    ├── dev.yaml         # Development overrides
    ├── staging.yaml     # Staging overrides
    ├── production.yaml  # Production overrides
    └── secrets/         # Sensitive values (gitignored)
        ├── dev.yaml
        ├── staging.yaml
        └── production.yaml

通用 Values（values/common.yaml）

# Shared configuration across all environments
app:
  name: myapp
  labels:
    team: platform
    component: api

service:
  type: ClusterIP
  port: 8080

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt

resources:
  requests:
    cpu: 100m
    memory: 128Mi

部署命令

# Deploy to dev
helm upgrade --install myapp ./charts/myapp \
  --namespace dev \
  --create-namespace \
  -f values/common.yaml \
  -f values/dev.yaml \
  -f values/secrets/dev.yaml

# Deploy to staging
helm upgrade --install myapp ./charts/myapp \
  --namespace staging \
  --create-namespace \
  -f values/common.yaml \
  -f values/staging.yaml \
  -f values/secrets/staging.yaml \
  --atomic --wait

# Deploy to production
helm upgrade --install myapp ./charts/myapp \
  --namespace production \
  --create-namespace \
  -f values/common.yaml \
  -f values/production.yaml \
  -f values/secrets/production.yaml \
  --atomic --wait --timeout 10m

值语法和类型

简单值

# String
name: myapp
tag: "v1.0.0"  # Quote to ensure string

# Number
replicaCount: 3
port: 8080

# Boolean
enabled: true
debug: false

# Null
database: null

嵌套值

# Nested objects
image:
  repository: nginx
  tag: "1.21.0"
  pullPolicy: IfNotPresent

# Access in template: {{ .Values.image.repository }}

列表/数组

# Simple list
tags:
  - api
  - web
  - production

# List of objects
env:
  - name: DATABASE_URL
    value: postgres://db:5432/myapp
  - name: REDIS_URL
    value: redis://cache:6379

通过 CLI 设置值

# Simple value
--set name=myapp

# Nested value (use dot notation)
--set image.tag=v2.0.0
--set ingress.annotations."cert-manager\.io/cluster-issuer"=letsencrypt

# List values (use array index or {})
--set tags={api,web,prod}

# Complex JSON structures
--set-json 'nodeSelector={"disk":"ssd","region":"us-west"}'

# Force string (prevents numeric conversion)
--set-string version="1.0"

# Read value from file
--set-file cert=./tls.crt

值验证与测试

使用 Values 渲染模板

# Render templates with values
helm template myapp ./chart --values values.yaml

# Validate against Kubernetes API
helm install myapp ./chart \
  --values values.yaml \
  --dry-run --validate

检查计算后的 Values

# See what values will be used (before install)
helm template myapp ./chart \
  --values values.yaml \
  --debug 2>&1 | grep -A 100 "COMPUTED VALUES"

# See what values were used (after install)
helm get values myapp --namespace prod --all

测试不同的值组合

# Test with minimal values
helm template myapp ./chart --set image.tag=test

# Test with full production values
helm template myapp ./chart \
  -f values/common.yaml \
  -f values/production.yaml

有关详细的环境值示例、架构验证 JSON、密钥管理选项、模板值处理模式、最佳实践和故障排除，请参阅 REFERENCE.md。

Agent 优化

上下文	命令
查看 Values（JSON）	helm get values <release> -n <ns> -o json
所有 Values（JSON）	helm get values <release> -n <ns> --all -o json
计算后的 Values	helm template myapp ./chart -f values.yaml --debug 2>&1 | grep -A 50 "COMPUTED VALUES"
验证架构	helm install myapp ./chart -f values.yaml --dry-run 2>&1 | head -50

相关技能

• Helm 发布管理 - 在安装/升级期间使用 Values
• Helm 调试 - 排查值错误
• Helm Chart 开发 - 创建值设计良好的 charts

参考资料

• Helm Values 文件
• Helm 架构验证
• Helm Secrets 插件
• External Secrets Operator