codecentric Helm Charts 实战指南：Jenkins与Keycloak在K8s的高效部署

1. 项目概述：一个由社区驱动的 Helm Chart 宝库

如果你正在 Kubernetes 上部署应用，并且厌倦了重复编写那些冗长、复杂的 YAML 文件，那么 Helm 和 Chart 仓库绝对是你工具箱里的必备品。今天要聊的这个 codecentric/helm-charts 项目，就是一个由德国知名 IT 咨询公司 codecentric 维护的 Helm Chart 集合。它不是一个官方仓库，但正因如此，它汇集了许多经过实战检验、针对特定流行中间件和应用（比如 Jenkins, Keycloak）的部署方案，其价值在于提供了“开箱即用”的配置，同时保留了高度的可定制性。

2. 核心组件与 Chart 解析

2.1 Helm 基础与 Chart 仓库机制

在深入 codecentric/helm-charts 的具体内容前，有必要先厘清几个核心概念。Helm 是 Kubernetes 的包管理器，你可以把它类比为 Ubuntu 的 apt 或 CentOS 的 yum 。一个 Helm Chart 就是一个预配置的 Kubernetes 资源包，里面包含了部署一个应用所需的所有 YAML 定义文件（如 Deployment, Service, ConfigMap, Ingress 等），并且通过模板化和参数化（ values.yaml ）使得配置可以灵活调整。

而 codecentric/helm-charts 就是一个 Helm Chart 仓库。仓库的本质是一个 HTTP 服务器，它托管着所有 Chart 打包后（.tgz 文件）的索引（index.yaml）。当你执行 helm repo add codecentric https://codecentric.github.io/helm-charts 时，Helm 客户端会获取这个索引文件并缓存到本地。之后，你就可以通过 helm search repo codecentric 来搜索、通过 helm install 来安装仓库里的任何 Chart。这种机制分离了 Chart 的存储和消费，使得分享和版本管理变得非常方便。

2.2 仓库核心 Chart 深度解读

根据关键词，这个仓库至少包含了 Jenkins、Keycloak、MailHog 等核心应用的 Chart。我们来逐一拆解它们的典型价值与配置要点。

Jenkins Chart： 对于在 K8s 中运行 CI/CD 流水线，用 Helm 部署 Jenkins 几乎是标准做法。 codecentric 维护的 Jenkins Chart 通常会解决几个原生部署的痛点：

动态 Agent 配置 ：它通常会集成 Kubernetes Plugin 的配置，让 Jenkins Master 可以按需在 K8s 集群中动态创建和销毁 Pod 作为构建 Agent。这在 values.yaml 中体现为 agent 部分的配置，你需要指定用于运行 Agent Pod 的 ServiceAccount、镜像、资源限制以及标签等。
持久化与高可用 ：Chart 会处理 Jenkins Home 目录的持久化，通常通过 PersistentVolumeClaim (PVC) 实现。对于生产环境，它可能提供 Master 多副本的选项（虽然 Jenkins Master 本身并非完全无状态，需要谨慎配置共享存储）。
插件预安装与管理 ：通过 installPlugins 列表，你可以声明需要安装的插件及其版本，Chart 会在初始化时自动处理。这是避免手动管理插件依赖的关键。

Keycloak Chart： Keycloak 是一个功能强大的开源身份和访问管理解决方案。在生产环境部署它，挑战在于数据库（通常是 PostgreSQL）的高可用、缓存（Infinispan）集群的配置，以及性能调优。

数据库集成 ：Chart 通常会提供内嵌 PostgreSQL 子 Chart（作为依赖）或允许连接外部数据库的选项。对于生产环境，强烈建议使用外部托管的高可用数据库，Chart 的 values.yaml 中会有 postgresql.enabled 和 externalDatabase.* 等参数进行切换。
缓存与集群 ：为了实现 Keycloak 多实例的水平扩展，必须配置一个共享的缓存（Infinispan）集群。Chart 需要能配置 Infinispan 以 Kubernetes DNS 发现或静态节点列表的方式组建集群。这部分配置较为复杂，但好的 Chart 会通过模板简化它。
Ingress 与 TLS ：Chart 会集成 Ingress 配置，支持自动申请 Let‘s Encrypt 证书（通常通过注解关联 cert-manager），这对于暴露安全的身份认证端点至关重要。

MailHog Chart： MailHog 是一个用于开发的邮件测试工具，能捕获发出的邮件并提供 Web UI 查看。它的 Chart 相对简单，但体现了 Helm 的另一个价值：快速搭建开发测试环境。Chart 会部署 MailHog 的 Deployment 和 Service，并可能提供一个简单的 Ingress 来访问 Web UI。通过 helm install my-mailhog codecentric/mailhog ，开发团队就能立刻拥有一个共享的模拟邮件服务器，无需每人本地搭建。

codecentric Helm Charts 实战指南：Jenkins与Keycloak在K8s的高效部署

注意：使用第三方 Chart 时，务必仔细审查其 values.yaml 默认值。例如，默认的资源请求/限制（ resources ）可能设置得过低（用于演示）或过高，默认的存储类（ storageClass ）可能不符合你的集群环境，默认的镜像拉取策略（ image.pullPolicy ）可能不是 Always 而导致版本更新问题。安装前先执行 helm show values codecentric/<chart-name> 查看所有可配置项是标准操作流程。

3. 实战：从添加仓库到定制化部署

3.1 环境准备与仓库添加

假设你已有一个正在运行的 Kubernetes 集群，并且 Helm 3 已安装就绪（Helm 2 已停止维护，请务必使用 Helm 3）。首先，我们将 codecentric 仓库添加到本地。

# 添加仓库，并命名为 codecentric
helm repo add codecentric https://codecentric.github.io/helm-charts

# 更新本地仓库索引，以获取最新的 Chart 列表和版本信息
helm repo update

# 搜索仓库内所有可用的 Chart
helm search repo codecentric/

执行 helm repo update 是必要的，它相当于 apt update ，会从远程仓库拉取最新的 index.yaml 文件。否则，你可能搜索不到新发布的 Chart 或版本。

3.2 安装与基础配置示例：以 Keycloak 为例

我们以部署一个用于开发测试环境的 Keycloak 实例为例，演示完整流程。

步骤一：拉取 Chart 并查看默认值 在直接安装前，最好先获取其默认配置，并保存为本地文件，以便在此基础上修改。

# 查看 Keycloak Chart 的所有可配置参数
helm show values codecentric/keycloak > keycloak-values.yaml

打开 keycloak-values.yaml ，你会看到一个非常详细的 YAML 文件，包含了镜像版本、副本数、资源限制、数据库配置、Ingress 设置等所有选项。

步骤二：定制化 values.yaml 对于开发环境，我们可能做如下简化修改（使用文本编辑器编辑 keycloak-values.yaml ）：

# keycloak-values.yaml (部分关键修改)
replicas: 1  # 开发环境单副本即可

keycloak:
  username: admin
  password: admin  # 生产环境务必使用Secret，此处仅为演示！
  # 使用内嵌的PostgreSQL，方便快捷
  persistence:
    deployPostgres: true
    dbVendor: postgres
  # 关闭集群模式，简化部署
  clustering:
    enabled: false

ingress:
  enabled: true
  className: "nginx"  # 假设集群使用nginx-ingress
  hosts:
    - host: keycloak.dev.example.com
      paths:
        - path: /
          pathType: Prefix
  tls: []  # 开发环境可以先不用HTTPS

resources:
  requests:
    memory: "512Mi"
    cpu: "250m"
  limits:
    memory: "1Gi"
    cpu: "500m"

步骤三：执行安装 使用我们自定义的 values 文件进行安装，并指定发布名称（release name）和命名空间。

# 在名为 `dev` 的命名空间中安装，发布名称定为 `my-keycloak`
helm install my-keycloak codecentric/keycloak -n dev -f keycloak-values.yaml

安装成功后，Helm 会输出一组 NOTES，告诉你如何访问应用、获取初始密码等关键信息。务必仔细阅读。

步骤四：验证与升级

# 查看发布状态
helm status my-keycloak -n dev

# 查看由这个 Chart 创建的所有Kubernetes资源
helm get manifest my-keycloak -n dev | kubectl get -n dev -f -

# 如果需要修改配置，更新 values.yaml 后，执行升级
helm upgrade my-keycloak codecentric/keycloak -n dev -f keycloak-values.yaml

3.3 高级定制：依赖管理与全局值

复杂的 Chart 如 Keycloak，可能会依赖其他子 Chart（例如，上面的 deployPostgres: true 实际上启用了其依赖的 PostgreSQL 子 Chart）。在 values.yaml 中，你可以看到类似 postgresql.* 的配置项，这些就是用来覆盖子 Chart 默认值的。

Helm 支持一种“全局值”（ global ）的配置方式。虽然 codecentric 的 Chart 不一定使用，但了解这个概念有益于阅读其他 Chart。在父 Chart 的 values.yaml 中设置 global.xxx ，其所有子 Chart 都可以通过 .Values.global.xxx 引用这个值，常用于统一设置镜像仓库地址、标签等。

4. 生产环境部署考量与避坑指南

4.1 安全加固配置清单

直接将默认 Chart 用于生产环境是危险的。以下是一份必须检查的安全配置清单：

密码与密钥管理 ：绝对禁止在 values.yaml 中明文写入密码、密钥。必须使用 Kubernetes Secrets。
- 正确做法 ：在 values.yaml 中，密码字段应引用 Secret。例如：
```
# values.yaml
keycloak:
  existingSecret: "keycloak-secrets" # 指向已存在的Secret名称
  # username 和 password 键名需与Secret中的data键匹配
  existingSecretKey: "password"
```
- 然后，通过 kubectl create secret generic 或 CI/CD 流程（如 HashiCorp Vault）来管理 Secret 的实际内容。
镜像策略 ：确保使用确定版本的镜像标签，而非 latest 。并设置 image.pullPolicy: Always 或 IfNotPresent （结合镜像拉取策略和私有仓库认证）。
```
image:
  repository: quay.io/keycloak/keycloak
  tag: "22.0.5" # 使用具体版本号
  pullPolicy: IfNotPresent
```
网络策略 ：默认 Chart 可能不会创建 NetworkPolicy。在生产集群中，应根据最小权限原则，为 Pod 配置 NetworkPolicy，限制不必要的入站和出站流量。
Pod 安全上下文 ：检查 Chart 是否配置了合理的 securityContext ，如以非 root 用户运行、禁止特权模式等。如果没有，你需要在 values.yaml 中补充。

4.2 高可用与稳定性设计

副本数与反亲和性 ：对于无状态服务（如 Keycloak 配合外部数据库和缓存），增加 replicas 数量（例如 3）。并配置 Pod 反亲和性（ podAntiAffinity ），确保副本分散在不同的节点上，提高容灾能力。

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 100
      podAffinityTerm:
        labelSelector:
          matchLabels:
            app.kubernetes.io/name: keycloak
        topologyKey: kubernetes.io/hostname

就绪与存活探针 ：确保 Chart 配置了合理的 livenessProbe 和 readinessProbe 。就绪探针（readiness）决定了 Pod 何时可以接收流量，存活探针（liveness）决定了何时重启 Pod。对于启动慢的应用（如 Java），初始延迟（ initialDelaySeconds ）要设置足够长。
资源限制与 HPA ：务必在 resources 中设置 requests 和 limits 。基于 requests 进行调度， limits 防止单个 Pod 耗尽节点资源。对于流量波动大的服务，可以基于 Chart 创建的 HPA（Horizontal Pod Autoscaler）或自行创建，实现自动扩缩容。

4.3 存储与备份策略

持久化卷选择 ：仔细选择 persistence.storageClass 。对于数据库（如内嵌的 PostgreSQL），需要使用高性能、高可靠的存储类（如 SSD）。对于日志或静态文件，可以使用成本更低的存储类。
备份机制 ：Chart 本身通常不提供备份功能。你需要为有状态数据（如数据库）建立独立的备份流程，例如使用 Velero 进行集群级备份，或使用数据库自身的备份工具（如 pg_dump ）定期将数据备份到对象存储。

4.4 监控与日志集成

Metrics 暴露 ：检查应用是否暴露 Prometheus 格式的指标。许多现代 Chart（如 Keycloak）会默认开启或提供选项来暴露 metrics。你需要确保 Service 或 Pod 上有正确的注解（如 prometheus.io/scrape: "true" ），以便 Prometheus 自动抓取。
日志标准化 ：确保应用日志输出到标准输出（stdout）和标准错误（stderr），这样可以被集群的日志收集器（如 Fluentd、Fluent Bit）统一收集，并转发到 Elasticsearch、Loki 等中心化日志系统。

5. 常见问题排查与运维技巧

5.1 安装与升级故障排查

问题现象	可能原因	排查命令与解决思路
`helm install` 失败，报错 `Error: rendered manifests contain a resource that already exists`	同命名空间下已存在同名资源，或之前安装未完全清理。	`kubectl get all -n <namespace>` 查看残留资源。使用 `helm uninstall <release-name> -n <namespace>` 彻底卸载，或使用 `--replace` 参数强制替换（需谨慎）。
`helm upgrade` 后 Pod 处于 `CrashLoopBackOff` 状态	新配置（如环境变量、命令）有误，或新镜像无法启动。	`kubectl describe pod <pod-name> -n <namespace>` 查看 Pod 事件。 `kubectl logs <pod-name> -n <namespace> --previous` 查看前一个容器的日志（如果是重启后）。回滚： `helm rollback <release-name> <revision-number> -n <namespace>` 。
`helm list` 不显示已安装的 release	Helm 使用的存储后端（默认是 Secret）可能被意外删除，或使用了错误的 kube-context/命名空间。	`kubectl get secrets -n <namespace> \| grep helm.sh/release` 查看 Helm 的 release Secret。确认当前 kubeconfig 上下文： `kubectl config current-context` 。
执行 `helm repo update` 后，搜索不到最新 Chart	本地缓存问题，或仓库索引文件未正确更新。	删除本地仓库缓存并重新添加： `helm repo remove codecentric && helm repo add codecentric https://codecentric.github.io/helm-charts` 。

5.2 运行时问题与调试

问题：Pod 运行正常，但服务无法通过 Ingress 访问。

排查：
1. 检查 Ingress 资源： kubectl get ingress -n <namespace> ，确认 ADDRESS 字段已分配（如果是云负载均衡器）或 Ingress Controller Pod 运行正常。
2. 检查 Ingress 注解： kubectl describe ingress <ingress-name> -n <namespace> ，确认 Class 注解（如 kubernetes.io/ingress.class: nginx ）与集群中安装的 Ingress Controller 匹配。
3. 检查 Service 和 Endpoints： kubectl get svc,ep -n <namespace> ，确认 Service 的 Selector 与 Pod 标签匹配，且 Endpoints 中有正确的 Pod IP。

问题：应用性能差，响应慢。

排查：
1. 检查 Pod 资源使用率： kubectl top pods -n <namespace> ，看是否达到 CPU/内存限制（limits），导致被 throttled 或 OOMKilled。
2. 检查持久化存储 I/O：如果应用依赖数据库或文件存储，可能是存储性能瓶颈。查看节点监控或存储提供商的控制台。
3. 检查应用级指标：通过暴露的 Prometheus metrics 或应用自身的管理端点，查看请求延迟、错误率、线程池状态等。

5.3 版本管理与回滚策略

Helm 的强大之处在于版本化。每次 install 、 upgrade 或 rollback 都会创建一个新的 release revision。善用此功能可以构建安全的发布流程。

查看发布历史 ： helm history <release-name> -n <namespace>
回滚到特定版本 ： helm rollback <release-name> <revision-number> -n <namespace> 。例如， helm rollback my-keycloak 2 -n dev 会回滚到第 2 个修订版。
差异化比较 ：在升级前，可以使用 helm diff upgrade <release-name> <chart> -f values.yaml -n <namespace> （需要安装 helm diff 插件）来预览本次升级将会对集群资源做出哪些更改，这是一个非常实用的安全审查步骤。

实操心得 ：对于生产环境的变更，我个人的流程是：1) 在测试环境用 helm diff 和 helm upgrade --dry-run 进行预演；2) 使用蓝绿部署或金丝雀发布策略（可通过 Chart 的 values.yaml 配合 Istio/Argo Rollouts 实现），而非直接原地升级；3) 始终保留一个已知稳定的 revision，并设置快速回滚预案。将 Helm 的 values 文件纳入 Git 版本控制，每次变更都有清晰的记录和审计跟踪。

本文地址：https://www.idc504.com/news/9_21302.html

上一篇：Kubernetes GitOps 实现指南（四）

下一篇：中小企业多语种支持利器：translategemma-27b-it企业级翻译落地案例