使用 Bitnami Helm Chart 在 Kubernetes 上部署 Kong API 网关：完整安装、配置与运维指南

本文以 Bitnami 官方 Kong Helm Chart（当前仓库版本 15.4.23，应用版本 Kong 3.9.1）为主线，系统讲解在 Kubernetes 集群上部署、配置与运维 Kong API 网关的完整流程，涵盖数据库后端选型（PostgreSQL / Cassandra / DB-less）、Prometheus 监控集成、安全加固默认值、Sidecar 与 Init 容器、自定义初始化脚本、额外资源部署及跨大版本升级迁移等内容。读完本文，你将掌握用一条 helm install 命令拉起生产级 Kong 网关，并能够按需调整镜像、存储、网络、探针、亲和性与监控等全部关键参数。

Kong 与 Bitnami Secure Images

Kong 是开源的微服务 API 网关与平台，专为高可用、容错、分布式系统场景下的微服务请求管理而设计。它构建在 NGINX 等成熟技术之上，提供易用的 RESTful API 来操作和配置系统；Kong 核心之外的功能通过插件机制无限扩展（鉴权、限流、日志、转换、correlation-id 等均可通过插件实现）。

本 Chart 同时打包了 kong-ingress-controller 容器，用于基于 Kong 管理 Kubernetes 的 Ingress 资源，因此安装后即可获得"Kong 网关 + Ingress Controller"一体的能力。

Bitnami Secure Images 是 Bitnami 构建并维护的加固、极低 CVE 数量的容器镜像，基于云优化、安全加固的企业级操作系统 Photon Linux 构建。其核心特性包括：

• 流行开源软件的加固安全镜像，接近零漏洞；
• 通过 VEX 声明、KEV 与 EPSS 评分进行漏洞分诊与优先级排序；
• 面向合规的 FIPS、STIG、air-gap 选项，并附带软件物料清单（SBOM）；
• 通过 in-toto 提供软件供应链来源证明；
• 对 Helm Chart 提供一流支持。

每个镜像都附带安全元数据，可在 Bitnami 公共目录中查看（部分数据仅对商业订阅开放）。如果你需要基于 Debian 的旧一代镜像，可参阅 Bitnami Legacy 镜像仓库。

从源码侧看，本 Chart 的镜像由 Chart.yaml 中的 annotations 声明，默认使用 docker.io/bitnami/kong:3.9.1-debian-12-r10 与 docker.io/bitnami/kong-ingress-controller:3.5.1-debian-12-r3。

前置条件与快速安装（TL;DR）

安装本 Chart 需要满足以下前置条件：

• Kubernetes 1.23+
• Helm 3.8.0+
• 底层基础设施支持 PV Provisioner（用于持久化数据库数据）

一条命令完成安装：

helm install my-release oci://registry-1.docker.io/bitnamicharts/kong

上述命令以默认配置在集群中部署 Kong。默认配置即：database=postgresql（随 Chart 部署 PostgreSQL 子 Chart）、Kong 副本数为 2、ingressController.enabled=true、networkPolicy.enabled=true。查看已安装的 release 可执行 helm list。

安装 Chart 与指定参数的方式

Chart 通过 OCI Registry 分发，安装时需要将 REGISTRY_NAME 与 REPOSITORY_NAME 替换为实际的 Chart 仓库，例如 Bitnami 官方仓库为 registry-1.docker.io/bitnamicharts：

helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/kong

参数可以通过 --set key=value[,key=value] 的方式逐项指定。例如，下面的命令会把 Kong 的 Admin 端口暴露到 Service 中：

helm install my-release \
  --set service.exposeAdmin=true oci://REGISTRY_NAME/REPOSITORY_NAME/kong

也可以使用 YAML 文件批量传入参数：

helm install my-release -f values.yaml oci://REGISTRY_NAME/REPOSITORY_NAME/kong

仓库中的 values.yaml 即默认参数文件，其中每个参数都带 @param 注释，是查询默认值和取值范围的权威参考。

数据库后端选型：PostgreSQL 与 Cassandra

本 Chart 支持三种数据库后端：PostgreSQL、Cassandra 或 off（DB-less）。其中 PostgreSQL 与 Cassandra 各自又有两种部署形态：随 Chart 部署子 Chart，或接入已有的外部数据库实例。

默认形态：随 Chart 部署 PostgreSQL 子 Chart

这是默认行为，无需额外参数：

helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/kong

Chart 会一并部署 postgresql 子 Chart（当前 Chart.yaml 中依赖的 postgresql 为 16.x 大版本），并自动创建 kong 用户与 kong 数据库（见 values.yaml 中 postgresql.auth.username、postgresql.auth.database 的默认值均为 kong）。

使用外部 PostgreSQL

关闭内置 PostgreSQL，并指定外部实例的连接信息：

helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/kong \
    --set postgresql.enabled=false \
    --set postgresql.external.host=_HOST_OF_YOUR_POSTGRESQL_INSTALLATION_ \
    --set postgresql.external.password=_PASSWORD_OF_YOUR_POSTGRESQL_INSTALLATION_ \
    --set postgresql.external.user=_USER_OF_YOUR_POSTGRESQL_INSTALLATION_

外部连接参数均位于 postgresql.external 下：host、port（默认 5432）、user（默认 kong）、password、database（默认 kong），也支持通过 postgresql.external.existingSecret 与 existingSecretPasswordKey 引用已有 Secret 存放数据库凭据。

从模板实现看，dep-ds.yaml 会根据 database=postgresql 注入 KONG_PG_HOST、KONG_PG_PORT、KONG_PG_USER 及密码环境变量（默认以 usePasswordFiles=true 方式挂载密码文件，而非直接使用环境变量，降低凭据泄露风险）。

部署 Cassandra 子 Chart

helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/kong \
    --set database=cassandra \
    --set postgresql.enabled=false \
    --set cassandra.enabled=true

Cassandra 子 Chart 默认创建 kong 用户（cassandra.dbUser.user 默认值为 kong），副本数为 1。

使用已有的 Cassandra 集群

helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/kong \
    --set database=cassandra \
    --set postgresql.enabled=false \
    --set cassandra.enabled=false \
    --set cassandra.external.hosts[0]=_CONTACT_POINT_0_OF_YOUR_CASSANDRA_CLUSTER_ \
    --set cassandra.external.hosts[1]=_CONTACT_POINT_1_OF_YOUR_CASSANDRA_CLUSTER_ \
    ...
    --set cassandra.external.user=_USER_OF_YOUR_CASSANDRA_INSTALLATION_ \
    --set cassandra.external.password=_PASSWORD_OF_YOUR_CASSANDRA_INSTALLATION_

cassandra.external 下支持 hosts（接触点列表）、port（默认 9042）、user、password，同样支持通过 existingSecret / existingSecretPasswordKey 复用已有 Secret。

对应地，模板会注入 KONG_CASSANDRA_CONTACT_POINTS、KONG_CASSANDRA_PORT、KONG_CASSANDRA_USER 与密码变量，见 dep-ds.yaml。

DB-less 声明式配置模式

Kong 1.1 起支持无数据库运行（DB-less）：实体仅保存在内存中，实体配置通过第二个配置文件（YAML 或 JSON）以声明式配置方式提供。启用 DB-less 的方式与 Kong 官方 Docker 安装的第四步一致——设置环境变量 KONG_DATABASE=off。

在本 Chart 中启用 DB-less 的步骤：

1. 将 database 设置为除 postgresql、cassandra 之外的任意值，例如 database: "off"；
2. 通过 kong.extraEnvVars 显式设置 KONG_DATABASE 环境变量：

kong.extraEnvVars:
- name: KONG_DATABASE
  value: "off"

DB-less 模式下还需要提供声明式配置。Chart 通过 kong.declarativeConfig 参数直接内联声明式配置（值会被渲染为模板），或通过 kong.declarativeConfigCM 指向一个已有 ConfigMap。当设置 kong.declarativeConfig 时，declarative-config-configmap.yaml 会生成包含 kong.yml 的 ConfigMap，模板同时在容器中注入 KONG_DECLARATIVE_CONFIG 环境变量（指向 /bitnami/kong/declarative-conf/kong.yml）并将该配置挂载到 Kong 容器，见 dep-ds.yaml。

配置与安装细节

资源请求与限制（resourcesPreset 与 resources）

所有 Bitnami Chart 都允许为容器设置资源 requests 与 limits（位于 resources 参数中）。生产环境必须设置 requests，并针对自身场景调整。

为简化配置，Chart 提供了 resourcesPreset 参数，可按预设自动填充 resources 段。可选预设为：none、nano、micro、small、medium、large、xlarge、2xlarge（预设的具体值定义在 bitnami/common 子 Chart 的 _resources.tpl 中）。Kong 容器默认 resourcesPreset: "medium"，Ingress Controller 与 Migration Job 默认 "nano"。

需要说明的是：生产环境不建议依赖 resourcesPreset，因为它可能无法完全贴合你的实际负载，推荐显式设置 resources。一旦设置了 kong.resources，resourcesPreset 将被忽略（模板中 if .Values.kong.resources 优先于 preset 分支，见 dep-ds.yaml）。示例：

kong:
  resources:
    requests:
      cpu: 2
      memory: 512Mi
    limits:
      cpu: 3
      memory: 1024Mi

Rolling 与 Immutable 镜像标签

强烈建议生产环境使用不可变（immutable）镜像标签，以确保同一 tag 被更新到不同镜像时，部署不会自动变化。Bitnami 会在主容器发布新版本、发生重大变更或出现严重漏洞时，发布新的 Chart 并更新其中的容器。因此生产环境建议通过 Chart 版本锁定 + 明确指定镜像 tag/digest 的方式，实现可预期的升级。image.digest 参数（如 sha256:aa...）一旦设置将覆盖 tag。

Prometheus 指标集成

设置 metrics.enabled=true 即可启用 Prometheus 集成。这会：

• 在所有 Pod 上启用 Kong 原生 Prometheus 端口（容器端口 metrics.containerPorts.http，默认 9119）；
• 部署一个 metrics Service（metrics-service.yaml），其 Service 端口默认 9119，并带有 Prometheus 自动抓取所需的注解：

metrics:
  enabled: true
  service:
    annotations:
      prometheus.io/scrape: "true"
      prometheus.io/port: "9119"
      prometheus.io/path: "/metrics"

模板侧，启用后容器会增加 http-metrics 端口，并注入 KONG_NGINX_HTTP_INCLUDE（指向 /bitnami/kong/metrics-exporter/exporter.conf），同时挂载对应的 exporter 配置 ConfigMap。

集成前提是你已有一个可用的 Prometheus 或 Prometheus Operator。仓库中同时提供了 Bitnami Prometheus 与 Bitnami Kube Prometheus Chart，可以直接安装使用。

与 Prometheus Operator 集成（ServiceMonitor）

设置 metrics.serviceMonitor.enabled=true 后，Chart 会部署 ServiceMonitor 对象（servicemonitor.yaml），用于与 Prometheus Operator 安装集成。前提是集群中已安装 Prometheus Operator 的 CustomResourceDefinitions，否则安装会报如下错误：

no matches for kind "ServiceMonitor" in version "monitoring.coreos.com/v1"

此时安装 Bitnami Kube Prometheus Chart 即可获得所需 CRD 与 Prometheus Operator。ServiceMonitor 支持配置 interval（默认 30s）、scrapeTimeout、labels、selector、relabelings、metricRelabelings、honorLabels、jobLabel、namespace，并可自动创建 RBAC（metrics.serviceMonitor.rbac.create=true）以便 Prometheus Operator 访问 Kong 所在命名空间。

备份与恢复（Velero）

对 Kubernetes 上的 Helm Chart 部署做备份/恢复，通常使用 Velero 备份源部署的持久卷，并将其挂载到新部署。步骤要点：

1. 使用 Velero 备份源部署中的 PV；
2. 执行新的部署并挂载同一 PV。

使用 Velero 的完整操作步骤可参考 Broadcom 应用目录文档中《使用 Velero 备份/恢复部署》的指南。注意：执行任何迁移/恢复动作前，务必先对数据库做备份。

Sidecar 与 Init 容器

如果需要在 Kong 所在 Pod 内运行额外容器（例如额外的 metrics 或日志导出器），可以通过 sidecars 参数按 Kubernetes 容器规范定义：

sidecars:
  - name: your-image-name
    image: your-image
    imagePullPolicy: Always
    ports:
      - name: portname
        containerPort: 1234

同理，initContainers 参数用于添加额外的初始化容器：

initContainers:
  - name: your-image-name
    image: your-image
    imagePullPolicy: Always
    ports:
      - name: portname
        containerPort: 1234

模板会将 sidecars 与 initContainers 直接渲染进 Deployment/DaemonSet 的 Pod spec（见 dep-ds.yaml）。若 Sidecar 需要对外暴露端口，可配合 service.extraPorts 使用。

追加环境变量

kong.extraEnvVars 用于向 Kong 容器追加环境变量（高级操作如自定义初始化脚本时很有用）：

kong:
  extraEnvVars:
    - name: KONG_LOG_LEVEL
      value: error

也可以用 ConfigMap 或 Secret 承载环境变量，分别通过 kong.extraEnvVarsCM、kong.extraEnvVarsSecret 指定，模板会将它们渲染为容器的 envFrom 引用。

Kong Ingress Controller 与 Kong Migration Job 同样支持这类配置，对应的参数为 ingressController.extraEnvVars / extraEnvVarsCM / extraEnvVarsSecret，以及 migration.extraEnvVars / extraEnvVarsCM / extraEnvVarsSecret。

使用自定义初始化脚本

对于高级操作，Chart 支持自定义初始化脚本，这些脚本会被挂载到 /docker-entrypoint-initdb.d 目录。可使用 ConfigMap（kong.initScriptsCM）或 Secret（kong.initScriptsSecret，用于敏感数据）承载脚本：

initScriptsCM=special-scripts
initScriptsSecret=special-scripts-sensitive

（示例中的 elasticsearch.hosts / elasticsearch.port 仅为示意性占位参数，实际使用时替换为你的配置。）

模板会将对应 ConfigMap/Secret 以 defaultMode: 0755 挂载到 /docker-entrypoint-initdb.d/cm 与 /docker-entrypoint-initdb.d/secret 目录（见 dep-ds.yaml），在容器启动时执行。

部署额外资源（extraDeploy）

有些场景需要随 Chart 一起部署额外对象，例如 KongPlugin、KongConsumer 等。extraDeploy 参数允许以模板形式添加任意对象的完整定义，extra-list.yaml 会逐个渲染这些对象。下面的示例在部署时激活一个 correlation-id 插件：

## Extra objects to deploy (value evaluated as a template)
##
extraDeploy:
  - |
    apiVersion: configuration.konghq.com/v1
    kind: KongPlugin
    metadata:
      name: {{ include "common.names.fullname" . }}-plugin-correlation
      namespace: {{ .Release.Namespace }}
      labels: {{- include "common.labels.standard" ( dict "customLabels" .Values.commonLabels "context" $ ) | nindent 6 }}
    config:
      header_name: my-request-id
    plugin: correlation-id

注意示例中 common.names.fullname、common.labels.standard 等模板函数由 bitnami/common 子 Chart 提供，extraDeploy 中的内容会以当前 release 上下文渲染。Kong 的 CRD 定义（KongPlugin、KongConsumer 等）随 Chart 提供在 crds/custom-resource-definitions.yaml。

设置 Pod 的亲和性

Chart 支持通过 affinity 参数自定义 Pod 亲和性；一旦设置了 affinity，下面的预设参数将被忽略。

作为替代方案，可以使用 bitnami/common Chart 提供的预设配置：

• podAffinityPreset：可选 soft 或 hard；
• podAntiAffinityPreset：默认 soft；
• nodeAffinityPreset：包含 type（soft/hard）、key（节点标签键）、values（节点标签值列表）。

从模板实现看，dep-ds.yaml 中 affinity 为空时，会依次渲染 podAffinity（common.affinities.pods）、podAntiAffinity（common.affinities.pods）与 nodeAffinity（common.affinities.nodes）三段预设。

参数总览

以下按组汇总本 Chart 的核心参数、含义与默认值。完整列表与默认值以仓库中的 values.yaml 为准。

全局参数

名称	描述	默认值
global.imageRegistry	全局 Docker 镜像仓库	""
global.imagePullSecrets	全局镜像拉取 Secret 数组	[]
global.defaultStorageClass	全局默认 StorageClass	""
global.security.allowInsecureImages	允许跳过镜像校验	false
global.compatibility.openshift.adaptSecurityContext	为兼容 Openshift restricted-v2 SCC 自适应 securityContext（可选 auto/force/disabled）	auto

通用参数

名称	描述	默认值
kubeVersion	强制目标 Kubernetes 版本	""
apiVersions	覆盖 .Capabilities 报告的 API 版本	[]
nameOverride	部分覆盖 fullname 模板	""
fullnameOverride	完全覆盖 fullname 模板	""
commonAnnotations / commonLabels	应用到所有 Kong 资源（不含子 Chart）的注解/标签，按模板求值	{}
clusterDomain	集群域名	cluster.local
extraDeploy	随 release 部署的额外对象数组（按模板求值）	[]
usePasswordFiles	用文件挂载凭据而非环境变量	true
diagnosticMode.enabled / .command / .args	诊断模式（禁用全部探针并覆盖启动命令）	false / ["sleep"] / ["infinity"]

Kong 通用参数

名称	描述	默认值
image.registry / image.repository	Kong 镜像仓库/名称	REGISTRY_NAME / REPOSITORY_NAME/kong
image.digest	镜像 digest（设置后覆盖 tag）	""
image.pullPolicy	镜像拉取策略	IfNotPresent
image.pullSecrets	docker-registry Secret 数组	[]
image.debug	启用镜像调试模式	false
database	数据库后端，可选 postgresql、cassandra、off	postgresql

Kong Deployment / DaemonSet 参数

名称	描述	默认值
useDaemonset	使用 DaemonSet 代替 Deployment（replicaCount 失效）	false
replicaCount	Kong 副本数	2
containerSecurityContext.enabled	容器级 Security Context	true
containerSecurityContext.runAsUser / runAsGroup	容器运行 UID/GID	1001 / 1001
containerSecurityContext.runAsNonRoot	以非 root 运行	true
containerSecurityContext.readOnlyRootFilesystem	只读根文件系统	true
containerSecurityContext.capabilities.drop	丢弃的能力列表	["ALL"]
containerSecurityContext.seccompProfile.type	seccomp 配置	RuntimeDefault
podSecurityContext.fsGroup	Pod fsGroup	1001
updateStrategy.type	更新策略	RollingUpdate
automountServiceAccountToken	是否挂载 ServiceAccount Token	true
topologySpreadConstraints	Pod 拓扑分布约束（按模板求值）	[]
priorityClassName / schedulerName	优先级类 / 自定义调度器	""
terminationGracePeriodSeconds	优雅终止时间	""
podAnnotations / podLabels	Pod 额外注解/标签	{}
podAntiAffinityPreset	Pod 反亲和预设	soft
nodeAffinityPreset.type / .key / .values	节点亲和预设	"" / "" / []
affinity	自定义亲和性（设置后忽略预设）	{}
nodeSelector / tolerations	节点选择 / 容忍	{} / []
extraVolumes / extraVolumeMounts	额外卷与挂载（按模板求值）	[]
initContainers / sidecars	额外初始化容器 / 边车容器	[]
autoscaling.enabled / .minReplicas / .maxReplicas	水平自动扩缩容（HPA）	false / 2 / 5
pdb.create / .maxUnavailable	PodDisruptionBudget	true / 50%

Kong 容器参数

名称	描述	默认值
kong.command / kong.args	覆盖默认容器命令/参数	[]
kong.initScriptsCM / kong.initScriptsSecret	初始化脚本 ConfigMap / Secret	""
kong.declarativeConfig / kong.declarativeConfigCM	DB-less 声明式配置（内联/ConfigMap，按模板求值）	""
kong.extraEnvVars / extraEnvVarsCM / extraEnvVarsSecret	额外环境变量（数组/ConfigMap/Secret）	[] / "" / ""
kong.containerPorts.proxyHttp / proxyHttps / adminHttp / adminHttps	容器代理/管理端口	8000 / 8443 / 8001 / 8444
kong.resourcesPreset	资源预设	medium
kong.resources	显式资源 requests/limits（生产推荐）	{}
kong.livenessProbe.*	存活探针（默认启用，initialDelay 120s，period 10s，timeout 5s，failureThreshold 6）	见 values.yaml
kong.readinessProbe.*	就绪探针（默认启用，initialDelay 30s）	见 values.yaml
kong.startupProbe.*	启动探针（默认关闭）	见 values.yaml
kong.customLivenessProbe / customReadinessProbe / customStartupProbe	自定义探针覆盖	{}
kong.lifecycleHooks	容器生命周期钩子	{}

探针的默认实现见 dep-ds.yaml：liveness 使用 pgrep -f 'kong start'，readiness 执行 /health/kong-container-health.sh，未配置自定义 lifecycleHooks 时默认添加 preStop 执行 kong quit。

流量暴露参数

名称	描述	默认值
service.type	Service 类型	ClusterIP
service.exposeAdmin	是否把 Kong Admin 端口加入 Service	false
service.disableHttpPort	禁用 proxy/admin 的 HTTP 端口	false
service.ports.proxyHttp / proxyHttps / adminHttp / adminHttps	Service 端口	80 / 443 / 8001 / 8444
service.nodePorts.*	NodePort（30000-32767）	""
service.sessionAffinity	会话亲和（None 或 ClientIP）	None
service.clusterIP	指定 ClusterIP	""
service.externalTrafficPolicy	外部流量策略（Local 可保留源 IP）	""
service.loadBalancerIP / loadBalancerSourceRanges	LoadBalancer 相关	"" / []
service.annotations	Service 注解	{}
service.extraPorts	额外暴露端口（通常配合 sidecar）	[]
networkPolicy.enabled	创建 NetworkPolicy	true
networkPolicy.kubeAPIServerPorts	可达 kube-apiserver 的端口列表	[443, 6443, 8443]
ingress.enabled	启用 Ingress 资源	false
ingress.ingressClassName	IngressClass（K8s 1.18+）	""
ingress.hostname / ingress.path	默认主机与路径	kong.local / /
ingress.tls / ingress.selfSigned	TLS 开关 / 自动自签证书	false / false
ingress.annotations	Ingress 注解（可放 cert-manager 注解）	{}
ingress.extraHosts / extraPaths / extraTls / secrets / extraRules	额外主机/路径/TLS/证书/规则	[]

Service 模板见 service.yaml：默认同时暴露 80（http-proxy）与 443（https-proxy）端口，disableHttpPort=true 时移除 HTTP 端口，exposeAdmin=true 时才加入 admin 端口。

Kong Ingress Controller 容器参数

名称	描述	默认值
ingressController.enabled	启用/停用 Kong Ingress Controller	true
ingressController.image.*	镜像仓库/名称/digest/pullPolicy/pullSecrets	REPOSITORY_NAME/kong-ingress-controller 等
ingressController.proxyReadyTimeout	等待 Kong 容器就绪的最长时间（秒）	300
ingressController.ingressClass	注册的 IngressClass 名称	kong
ingressController.containerPorts.health	健康检查端口	10254
ingressController.resourcesPreset	资源预设	nano
ingressController.resources	显式资源（生产推荐）	{}
ingressController.*Probe	三种探针配置	与 Kong 容器类似，见 values.yaml
ingressController.serviceAccount.create	创建 ServiceAccount	true
ingressController.rbac.create	创建 Ingress Controller 所需 RBAC	true
ingressController.rbac.rules	自定义 RBAC 规则	[]

Ingress Controller 容器通过 CONTROLLER_KONG_ADMIN_URL（指向 http://127.0.0.1:8001）、CONTROLLER_PUBLISH_SERVICE、CONTROLLER_INGRESS_CLASS、CONTROLLER_ELECTION_ID、POD_NAME、POD_NAMESPACE 等环境变量与 Kong 及集群交互（见 dep-ds.yaml）。其默认启动命令为 /health/ingress-container-start.sh，就绪探针为对 /healthz 的 HTTP GET。

Kong Migration Job 参数

名称	描述	默认值
migration.command / migration.args	覆盖迁移 Job 命令/参数	[]
migration.extraEnvVars / extraEnvVarsCM / extraEnvVarsSecret	迁移 Job 额外环境变量	[] / "" / ""
migration.resourcesPreset / migration.resources	资源预设 / 显式资源	nano / {}
migration.automountServiceAccountToken	挂载 ServiceAccount Token	true
migration.hostAliases	主机别名	[]
migration.annotations	Job 注解（默认 post-install, pre-upgrade 钩子）	见 values.yaml
migration.podLabels / podAnnotations	Pod 标签/注解	{}

迁移 Job 模板见 migrate-job.yaml：仅在 database 为 postgresql 或 cassandra 时创建，通过 KONG_MIGRATE=yes 与 KONG_EXIT_AFTER_MIGRATE=yes 环境变量执行数据库迁移后退出，并以 Helm 钩子（post-install, pre-upgrade、before-hook-creation, hook-succeeded 删除策略）串入安装与升级流程。

PostgreSQL 参数

名称	描述	默认值
postgresql.enabled	启用/停用 PostgreSQL 子 Chart	true
postgresql.auth.postgresPassword	postgres 管理员密码	""
postgresql.auth.username	创建的自定义用户	kong
postgresql.auth.password	自定义用户密码	""
postgresql.auth.database	创建的自定义数据库	kong
postgresql.auth.existingSecret	复用已有 Secret	""
postgresql.architecture	架构（standalone 或 replication）	standalone
postgresql.primary.resourcesPreset / primary.resources	主库资源	nano / {}
postgresql.external.host / .port / .user / .password / .database	外部实例连接参数	"" / 5432 / kong / "" / kong
postgresql.external.existingSecret / existingSecretPasswordKey	外部实例凭据 Secret	""

Cassandra 参数

名称	描述	默认值
cassandra.enabled	启用/停用 Cassandra 子 Chart	false
cassandra.dbUser.user / .password / .existingSecret	Cassandra 管理用户	kong / "" / ""
cassandra.replicaCount	Cassandra 副本数	1
cassandra.external.hosts / .port / .user / .password	外部 Cassandra 连接	[] / 9042 / "" / ""
cassandra.external.existingSecret / existingSecretPasswordKey	外部实例凭据 Secret	""
cassandra.resourcesPreset / cassandra.resources	资源预设 / 显式资源	large / {}

注意：Cassandra 开发环境最低建议 4GB 内存与 2 核 CPU，生产环境最低 8GB 内存与 4 核 CPU。

Metrics 参数

名称	描述	默认值
metrics.enabled	启用 Prometheus 指标导出	false
metrics.containerPorts.http	指标容器端口	9119
metrics.service.sessionAffinity / .clusterIP / .annotations / .ports.http	指标 Service 配置	None / "" / prometheus 注解 / 9119
metrics.serviceMonitor.enabled	创建 ServiceMonitor（配合 Prometheus Operator）	false
metrics.serviceMonitor.namespace / .interval / .scrapeTimeout	命名空间 / 抓取间隔 / 超时	"" / 30s / ""
metrics.serviceMonitor.labels / .selector / .relabelings / .metricRelabelings / .honorLabels / .jobLabel	发现与处理规则	见 values.yaml
metrics.serviceMonitor.serviceAccount / .rbac.create	Operator 服务账号 / RBAC	"" / true

升级与迁移注意事项

Chart 的完整变更记录见 CHANGELOG.md，以下为若干关键大版本的升级要点：

升级到 15.1.0：引入镜像校验（安全目的）。如需关闭，设置 global.security.allowInsecureImages=true。升级时必须显式指定已有密码，避免 Secret 被随机生成的无效密码覆盖：

helm upgrade my-release oci://REGISTRY_NAME/REPOSITORY_NAME/kong \
    --set database=postgresql \
    --set postgresql.enabled=true \
    --set postgresql.postgresqlPassword=[POSTGRESQL_PASSWORD]

升级到 15.0.0 / 14.0.0：PostgreSQL 子 Chart 从 14.x 升级到 17.x。15.0.0 起不再在本 Chart values 中覆盖 PostgreSQL 版本，而是自动使用 postgresql 子 Chart 定义的版本（当前 Chart.yaml 中为 16.x.x 依赖大版本）。

升级到 13.0.0：Cassandra 子 Chart 升级到 12.0.0 大版本。

升级到 12.0.0：修改了多项安全默认值，包括 runAsGroup 从 0 改为 1001、readOnlyRootFilesystem 设为 true、resourcesPreset 由 none 改为测试套件可运行的最小规格、adaptSecurityContext 由 disabled 改为 auto。这可能影响已有的自定义或初始化脚本，如受影响请改回旧默认值。

升级到 3.0.0（Helm v3 迁移）：Chart 从 apiVersion: v1（Helm 2/3 均可安装）升级为 apiVersion: v2（仅 Helm 3）。若此前用 Helm v2 安装，迁移到 Helm v3 时需复用原 PostgreSQL PVC。关键步骤（示例 release 名为 kong，请先备份数据库）：

# 1. 导出 Secret 与 PVC 名称
export POSTGRESQL_PASSWORD=$(kubectl get secret --namespace default kong-postgresql -o jsonpath="{.data.password}" | base64 -d)
export POSTGRESQL_PVC=$(kubectl get pvc -l app.kubernetes.io/instance=kong,app.kubernetes.io/name=postgresql,role=master -o jsonpath="{.items[0].metadata.name}")

# 2. 删除 PostgreSQL StatefulSet（注意 --cascade=false）
kubectl delete statefulsets.apps kong-postgresql --cascade=false

# 3. 升级 Chart release 并复用 PVC
helm upgrade kong oci://REGISTRY_NAME/REPOSITORY_NAME/kong \
    --set postgresql.postgresqlPassword=$POSTGRESQL_PASSWORD \
    --set postgresql.persistence.existingClaim=$POSTGRESQL_PVC

# 4. 强制新 StatefulSet 创建新 Pod
kubectl delete pod kong-postgresql-0

随后可在容器日志中看到 Deploying PostgreSQL with persisted data... 之类输出，表示已用持久化数据正常启动。

其他大版本：8.0.0/10.0.0/11.0.0 主要升级 PostgreSQL 子 Chart 大版本；9.0.0/5.0.0/4.0.0/2.0.0 升级 Cassandra 子 Chart 大版本；3.1.0 将 Kong Ingress Controller 升级到 1.x 并同步更新相关 CRD。升级相关 PostgreSQL/Cassandra 子 Chart 大版本时，请先核对子 Chart 的升级说明并妥善迁移数据。

故障排查

Bitnami Helm Chart 常见错误的排查方法，可参考 Bitnami 官方文档中的 Helm Chart 故障排查指南。典型问题包括：ServiceMonitor CRD 缺失导致的安装失败（见上文 Prometheus 章节）、升级时密码未显式指定导致的 Secret 重置、OpenShift restricted-v2 SCC 下的 securityContext 兼容问题（通过 global.compatibility.openshift.adaptSecurityContext 控制）、以及只读根文件系统（readOnlyRootFilesystem=true）下自定义脚本落盘位置需使用挂载卷等问题。

小结

Bitnami Kong Helm Chart 将一个生产级 API 网关的完整交付封装为可复制的 Helm 部署：内置 PostgreSQL/Cassandra 子 Chart、可选 DB-less 声明式模式、Prometheus/ServiceMonitor 监控集成、Kong Ingress Controller 与 CRD、迁移 Job、PodDisruptionBudget、NetworkPolicy、HPA 等开箱即用的能力，同时通过加固的默认 SecurityContext 与可选的镜像校验（allowInsecureImages）体现安全优先的设计。实际使用时，建议以仓库中的 values.yaml 为基准按需覆盖参数，生产环境优先使用显式 resources、不可变镜像 tag，并在升级前备份数据库。