1. 项目概述为什么我们需要 APISIX 的 Helm Chart如果你和我一样长期在 Kubernetes 这片“云原生大陆”上耕耘那你肯定对 API 网关的重要性深有体会。它就像是你微服务集群的“城门”和“交通枢纽”所有的流量都要从这里经过进行路由、认证、限流、监控等一系列操作。Apache APISIX 正是这个领域里一颗耀眼的明星凭借其高性能、高扩展性和丰富的插件生态成为了许多团队构建现代应用架构的首选。然而把 APISIX 这样一个功能强大的组件优雅、可靠地部署到 K8s 集群里从来都不是一件简单的事。你可能会想“不就是几个 Deployment 和 Service 吗” 但真正动起手来你会发现一堆头疼的问题如何管理复杂的配置文件如何优雅地处理证书如何实现高可用部署版本升级时如何平滑迁移这些琐碎但关键的工作足以消耗掉你大把的精力。这时候Helm 的价值就凸显出来了。它被称作 K8s 的“包管理器”能将一组相关的 K8s 资源打包成一个可配置、可版本化的“Chart”。而apache/apisix-helm-chart这个项目就是官方为我们准备好的、开箱即用的 APISIX 全家桶部署方案。它把 APISIX 数据面、Ingress 控制器可选、以及已被标记为废弃的 Dashboardv3.x 版本的部署、配置、依赖关系全部封装好了。你只需要准备一个values.yaml文件像填问卷一样设置好你的需求然后一句helm install命令一个生产就绪的 APISIX 网关集群就能在几分钟内拔地而起。这个项目适合所有正在或计划在 K8s 中使用 APISIX 的开发者、运维和架构师无论是初次尝鲜还是准备投入生产它都能帮你跳过大量重复的“造轮子”工作把精力聚焦在业务逻辑和网关策略本身。2. 核心组件与架构设计解析在深入配置细节之前我们必须先搞清楚这个 Helm Chart 到底包含了什么以及它们是如何协同工作的。这有助于我们在后续定制时做出更明智的决策。2.1 三大核心组件构成这个 Chart 仓库主要维护着三个独立的子 Chart它们可以独立部署也可以组合使用Apache APISIX (数据面): 这是核心的 API 网关运行时。它接收外部流量并根据你定义的规则路由、上游、插件等进行处理和转发。在 Helm Chart 中它通常被部署为一个StatefulSet为了稳定的网络标识便于插件依赖或Deployment并配有相应的Service如ClusterIP和NodePort/LoadBalancer来暴露服务。Apache APISIX Ingress Controller (控制面 - 推荐): 这是一个 Kubernetes Ingress Controller。它的作用是监听 K8s 集群内的Ingress、ApisixRoute自定义资源等资源的变化并将其自动转化为 APISIX 数据面能够理解的配置。这意味着你可以用声明式的 K8s 原生资源来管理网关路由实现了 GitOps 工作流。这里有一个非常重要的注意事项由于 Ingress Controller 会自动管理一部分 APISIX 资源例如它创建的 Route 和 Upstream 会被标记为managed-by: apisix-ingress-controller如果你同时使用 APISIX Dashboard 去手动修改这些资源会造成配置冲突或被控制器覆盖。官方文档也明确指出两者在管理同一批资源时兼容性不佳。[DEPRECATED] Apache APISIX Dashboard (管理界面): 这是一个提供图形化界面的管理控制台用于配置路由、插件、证书等。但是请注意对于 APISIX v3.x这个 Dashboard 已被标记为废弃DEPRECATED。社区主推的方向是通过helm配合values.yaml进行声明式配置或者通过 Admin API 进行自动化配置。对于新项目不建议再依赖此 Dashboard。2.2 版本兼容性矩阵解读项目提供的兼容性矩阵是部署前必须查阅的“圣经”理解它能避免很多因版本错配导致的诡异问题。Chart 版本APISIX (数据面) 版本APISIX Ingress Controller 版本APISIX Dashboard 版本Chart v2.xv3.xv1.x, v2.xv3.x (已废弃)Chart v1.xv3.xv1.xv3.x (已废弃)Chart v0.xv2.xv1.xv2.x关键解读与选型建议主线选择对于新部署应直接选择 Chart v2.x 系列。它支持 APISIX v3.x 的全新特性并且兼容 Ingress Controller v1.x 和 v2.x给你最大的灵活性。APISIX v3.x 是现在和未来APISIX v3.x 相较于 v2.x 有显著的架构和功能改进。除非有历史包袱否则都应选择 v3.x。Ingress Controller 的版本v2.x 版本的控制器引入了更多优化和新特性。如果你的集群环境较新建议搭配使用 Chart v2.x Ingress Controller v2.x。关于 Dashboard表格中虽然列出了 Dashboard v3.x 与 Chart v2.x/v1.x 兼容但旁边的“DEPRECATED”标签已经表明了官方态度。在生产环境中应避免使用 Dashboard 来修改 Ingress Controller 管理的配置。它可能仅适用于纯 Admin API 管理的、简单的测试环境。升级路径如果你正在使用 Chart v1.x 甚至 v0.x需要特别注意v2.x 版本包含了大量破坏性更新Breaking Changes。官方贴心地保留了apisix/1.x分支供旧版本用户维护。计划升级时必须仔细阅读CHANGELOG.md并在测试环境充分验证。实操心得我曾在一个从 Chart v0.x 升级到 v2.x 的项目中踩过坑。最大的变化之一是values.yaml中配置项结构的重组。例如一些关于 etcd 的配置从顶层直接移到了apisix.etcd子项下。直接升级会导致 APISIX 无法连接配置中心。最稳妥的升级方式是先在测试环境通过helm pull下载新版本的 Chart对比新旧values.yaml的结构差异然后逐步迁移和测试自己的定制配置而不是简单地用旧文件覆盖。3. 实战部署从零开始安装与配置理论说得再多不如动手实践。让我们从一个最基础的、可工作的部署开始逐步增加复杂度。这里假设你已经有一个可用的 Kubernetes 集群并已安装好helm客户端。3.1 基础环境准备与仓库添加首先我们需要将 Apache APISIX 的 Helm 仓库添加到本地。# 添加 APISIX 的官方 Helm 仓库 helm repo add apisix https://charts.apiseven.com helm repo update # 搜索查看可用的 Chart helm search repo apisix执行helm search repo apisix后你通常会看到类似下面的输出确认仓库添加成功NAME CHART VERSION APP VERSION DESCRIPTION apisix/apisix 2.0.0 3.8.0 A Helm chart for Apache APISIX apisix/apisix-dashboard 0.15.0 3.0.0 DEPRECATED - Helm chart for Apache APISIX Dashboard apisix/apisix-ingress-controller 0.15.0 1.8.0 A Helm chart for Apache APISIX Ingress Controller3.2 最小化部署快速启动 APISIX 数据面我们先部署一个最简单的 APISIX 网关不启用 Ingress Controller 和 Dashboard。创建命名空间为 APISIX 创建一个独立的命名空间是个好习惯。kubectl create namespace apisix准备基础values.yaml创建一个名为apisix-minimal.yaml的文件。以下配置启用了默认的 etcd 作为配置存储通过apisix.enabledtrue自动部署并将 APISIX 的网关和管理端口通过NodePort方式暴露出来方便我们快速测试。# apisix-minimal.yaml # 启用 APISIX 核心组件 apisix: enabled: true # 使用 StatefulSet 部署保证 Pod 名称和网络标识稳定 deployment: type: StatefulSet # 配置网关服务类型为 NodePort便于从集群外访问 gateway: type: NodePort # 配置 NodePort 端口范围生产环境建议使用 LoadBalancer 或 Ingress nodePort: 30080 # 自定义网关端口 (HTTP) # 如果启用 HTTPS可配置 TLS 的 NodePort # tls: # nodePort: 30443 # 配置管理 API 服务 adminAPI: enabled: true type: NodePort nodePort: 30081 # 自定义管理端口 # 启用内置的 etcd 集群开发测试推荐生产建议使用外部独立 etcd etcd: enabled: true replicaCount: 3 # 生产环境建议至少3个节点以实现高可用 # 我们不启用 Ingress Controller 和 Dashboard ingress-controller: enabled: false dashboard: enabled: false执行安装helm install apisix apisix/apisix -f apisix-minimal.yaml --namespace apisix安装成功后使用kubectl get pods -n apisix查看应该能看到类似以下的 PodNAME READY STATUS RESTARTS AGE apisix-0 1/1 Running 0 2m apisix-etcd-0 1/1 Running 0 2m apisix-etcd-1 1/1 Running 0 2m apisix-etcd-2 1/1 Running 0 2m验证安装获取 APISIX 节点的 IP或使用任意节点 IP。访问管理 APIcurl http://NODE_IP:30081/apisix/admin/routes。如果返回{count:0, ...}之类的 JSON说明 APISIX 运行正常。此时网关端口30080还没有配置任何路由访问会返回404。3.3 生产级配置详解与定制上面的最小化部署仅用于验证。要用于生产我们需要关注稳定性、性能、安全性和可观测性。下面我们拆解几个关键配置领域。3.3.1 高可用与资源规划生产环境必须考虑高可用。APISIX 本身是无状态的其状态存储在 etcd 中因此高可用主要针对 APISIX 实例和 etcd 集群。# apisix-production.yaml (部分) apisix: enabled: true deployment: type: Deployment # 生产环境也常用 Deployment配合 Pod 反亲和性 replicaCount: 3 # 至少部署2个及以上实例 # Pod 反亲和性避免多个 APISIX 实例调度到同一节点 podAntiAffinity: preferredDuringSchedulingIgnoredDuringExecution: - podAffinityTerm: labelSelector: matchExpressions: - key: app.kubernetes.io/instance operator: In values: - apisix topologyKey: kubernetes.io/hostname weight: 100 # 资源请求与限制防止资源竞争和 OOM resources: requests: memory: 1Gi cpu: 500m limits: memory: 2Gi cpu: 2000m etcd: enabled: true # 对于中小规模生产内置 etcd 可以接受。大规模或对配置存储有更高要求时应使用外部独立 etcd 集群。 replicaCount: 3 # 为 etcd 也配置足够的资源它的性能直接影响 APISIX 配置更新速度 resources: requests: memory: 512Mi cpu: 200m limits: memory: 1Gi cpu: 500m # 配置持久化存储避免数据丢失 persistence: enabled: true storageClass: standard # 替换为你集群中可用的 StorageClass size: 10Gi3.3.2 安全与网络配置管理 API 安全绝对不要将管理 API (adminAPI) 暴露到公网。生产环境应设置为ClusterIP并通过严格的网络策略 (NetworkPolicy) 或 Ingress 规则配合认证限制访问来源。apisix: adminAPI: enabled: true type: ClusterIP # 仅限集群内部访问 # 可以修改默认的密钥增强安全性 admin_key: - name: admin key: your-strong-admin-key-here # 替换为强密钥 role: admin网关 TLS 终止启用 HTTPS 是必须的。你可以通过配置apisix.gateway.tls来加载 Kubernetes 的Secret中的证书。apisix: gateway: type: LoadBalancer # 生产环境常用 LoadBalancer 或与 Ingress Controller 配合 tls: enabled: true # 引用包含 TLS 证书和私钥的 Secret existingSecret: apisix-tls-secret # 证书在 Secret 中的键名 certKey: tls.crt keyKey: tls.key你需要提前创建包含证书的 Secretkubectl create secret tls apisix-tls-secret --certpath/to/cert.pem --keypath/to/key.pem -n apisix。使用外部 etcd为了获得更好的可维护性和独立性生产集群通常使用独立部署的 etcd。这需要修改 APISIX 的连接配置。etcd: enabled: false # 禁用内置 etcd apisix: config: etcd: host: - http://etcd-cluster-client:2379 # 替换为你的外部 etcd 服务地址 prefix: /apisix # APISIX 在 etcd 中使用的键前缀3.3.3 启用 APISIX Ingress Controller要使用 Kubernetes 原生方式管理路由必须启用 Ingress Controller。# apisix-with-ingress.yaml (部分) ingress-controller: enabled: true config: # Ingress Controller 的运行模式推荐使用 apisix 模式监听 ApisixRoute 等 CRD apisix: # 指定它要管理的 APISIX 集群的管理 API 地址 adminAPIVersion: v3 baseURL: http://apisix-admin:9180/apisix/admin # 指向 APISIX 的 admin Service # 管理 API 的密钥必须与 APISIX 配置中的 admin_key 一致 adminKey: your-strong-admin-key-here部署完成后你就可以创建Ingress或ApisixRoute资源来定义路由规则Ingress Controller 会自动将其同步到 APISIX 数据面。注意事项再次强调一旦启用了 Ingress Controller 并开始用Ingress/ApisixRoute管理路由就不要再通过 APISIX 的 Admin API 或 Dashboard 去修改由它管理的资源通常带有managed-by: apisix-ingress-controller标签否则会导致配置状态不一致。4. 高级主题定制、监控与故障排查当基础部署稳定后我们会面临更多定制化需求和运维挑战。4.1 插件管理与自定义配置APISIX 的强大在于插件。Helm Chart 允许你全局启用或禁用插件并传递自定义的插件配置。apisix: config: # 插件列表在此处启用的插件才会被加载 plugins: - limit-req # 请求限流 - key-auth # 密钥认证 - cors # 跨域支持 - prometheus # 暴露 Prometheus 指标 - zipkin # 分布式追踪 # 你可以移除不用的插件以减少内存占用 # - “example-plugin” # 插件全局配置 plugin_attr: prometheus: export_addr: ip: 0.0.0.0 port: 9091 # 修改 Prometheus 指标暴露端口 # 自定义 Nginx 配置片段用于满足特殊需求 customLuaSharedDicts: | my_cache 10m; customNginxConfig: | # 例如调整日志格式或超时时间 log_format main $remote_addr - $remote_user [$time_local] $request $status $body_bytes_sent $http_referer $http_user_agent $http_x_forwarded_for; client_header_timeout 60s;4.2 可观测性集成监控与日志没有监控的系统就是在“裸奔”。Metrics (Prometheus)启用prometheus插件后APISIX 会在/apisix/prometheus/metrics端点暴露指标。你需要配置 ServiceMonitor如果你使用 Prometheus Operator或直接在 Prometheus 的scrape_configs中添加抓取任务目标指向 APISIX 的adminAPI或gatewayService 的相应端口如 9091。日志APISIX 的访问日志和错误日志默认输出到容器的 stdout/stderr。生产环境需要将它们收集起来。最佳实践是配置customNginxConfig将日志以 JSON 格式输出便于 Elasticsearch、Loki 等日志系统解析。apisix: config: customNginxConfig: | log_format access_json {timestamp:$time_iso8601, client:$remote_addr, request:$request, status:$status, upstream_addr:$upstream_addr}; access_log /dev/stdout access_json;同时确保你的容器运行时或集群层面的日志收集器如 Fluentd、Fluent Bit被正确配置将这些日志发送到中心化存储。Tracing (分布式追踪)启用zipkin、skywalking或jaeger插件并在插件配置中填入你追踪服务器的地址可以快速定位跨服务调用的性能瓶颈。4.3 常见问题与排查技巧实录即使部署再顺利运维过程中也难免遇到问题。这里记录几个我亲身踩过的坑和排查思路。4.3.1 问题APISIX Pod 不断重启日志显示连接 etcd 失败。排查思路检查 etcd 集群状态kubectl get pods -n apisix | grep etcd查看所有 etcd Pod 是否都为Running。使用kubectl logs apisix-etcd-0查看 leader 节点的日志检查是否有选举失败或磁盘空间不足的错误。检查网络连通性进入 APISIX Pod (kubectl exec -it apisix-0 -n apisix -- sh)尝试用curl或wget连接 etcd 的服务地址如http://apisix-etcd:2379/health。如果失败可能是网络策略 (NetworkPolicy) 阻止了通信或者 Service 域名解析有问题。检查 APISIX 配置确认values.yaml中apisix.config.etcd.host的地址是否正确。如果使用的是内置 etcd地址通常是http://apisix-etcd:2379。如果使用的是外部 etcd确保地址和端口可访问且防火墙规则已放行。检查认证如果 etcd 启用了客户端证书认证需要在 APISIX 配置中提供相应的证书。内置的 etcd 默认不启用。解决方案大多数情况下这是 etcd 集群自身的问题。确保为 etcd 配置了持久化存储和足够的资源。对于内置 etcd可以尝试删除 PVC 并重新安装注意这会丢失所有配置数据。对于网络问题检查 Calico/Flannel 等 CNI 插件状态以及相关的NetworkPolicy。4.3.2 问题通过 Ingress 创建的路由不生效访问返回 404。排查思路检查 Ingress Controller 日志kubectl logs -l app.kubernetes.io/nameapisix-ingress-controller -n apisix。查看是否有错误信息例如无法连接 APISIX Admin API或者同步资源时出现语法错误。检查 APISIX Admin API 连通性和密钥这是最常见的原因。确保ingress-controller.config.apisix.baseURL和adminKey完全正确。可以手动在集群内起一个临时 Pod用curl和相同的密钥去访问 Admin API看是否能正常列出路由。检查 APISIX 数据面配置登录到任意 APISIX 容器检查/usr/local/apisix/conf/config.yaml确认 etcd 配置和 admin_key 是否与 Ingress Controller 的配置匹配。检查自定义资源定义 (CRD)确保ApisixRoute、ApisixUpstream等 CRD 已正确安装Helm Chart 通常会处理。使用kubectl get crd | grep apisix确认。检查路由是否已同步访问 APISIX Admin API (/apisix/admin/routes)查看 Ingress Controller 创建的路由是否已经存在。如果存在但还不生效检查路由的host、uri是否与你的访问请求匹配以及upstream指向的 Service 是否正常。解决方案建立一个标准的排查清单。首先确认控制面Ingress Controller无报错且能连接数据面APISIX。然后确认数据面配置正确且已收到同步的路由配置。最后验证路由规则本身是否正确。4.3.3 问题性能瓶颈网关延迟增高。排查思路监控指标首先查看 Prometheus 中的关键指标如apisix_bandwidth、apisix_etcd_reachable、apisix_request_latency、apisix_http_status。观察是否有突增的流量、异常的延迟或错误率。资源利用率使用kubectl top pods -n apisix查看 APISIX Pod 的 CPU 和内存使用情况。是否达到 limits 限制如果 CPU 持续高位可能是某个插件如复杂的限流或自定义插件消耗过大。检查 etcd 延迟APISIX 每次配置变更都会访问 etcd。如果 etcd 集群负载高或网络延迟大会影响路由更新速度甚至影响健康检查。监控 etcd 的etcd_disk_wal_fsync_duration_seconds等指标。日志分析检查 APISIX 错误日志中是否有大量connect() failed到上游服务的记录这可能意味着上游服务成为瓶颈导致 APISIX 连接池耗尽或等待超时。解决方案根据瓶颈点采取行动。如果是 APISIX 本身资源不足适当增加replicaCount和资源limits。如果是 etcd 瓶颈考虑将 etcd 迁移到更高性能的节点或使用外部专业 etcd 集群。如果是上游服务问题则需要优化后端服务或在 APISIX 层面配置更合理的重试、超时和熔断策略。5. 版本升级与日常维护策略运维不仅仅是部署更是长期的维护。5.1 Helm 升级流程使用 Helm 进行升级相对平滑但必须遵循流程。备份升级前务必备份当前的values.yaml和任何自定义配置。如果使用了内置 etcd 且数据重要考虑备份 etcd 数据具体命令取决于存储后端。查阅变更日志前往 GitHub 仓库的 Release 页面仔细阅读目标版本与当前版本之间的CHANGELOG.md重点关注Breaking Changes。测试环境验证将修改后的values.yaml在测试集群中先进行helm upgrade --dry-run --debug进行模拟然后实际升级并运行完整的集成测试。生产环境分阶段升级如果副本数多可以考虑使用helm upgrade配合--set参数分批次更新镜像或结合 Kubernetes 的 RollingUpdate 策略。# 标准升级命令 helm upgrade apisix apisix/apisix -f your-values.yaml --namespace apisix回滚计划确保你知道如何快速回滚。helm rollback apisix REVISION_NUMBER是你的救命稻草。使用helm history apisix -n apisix查看发布历史。5.2 配置管理与 GitOps将你的values.yaml文件纳入版本控制系统如 Git是实践 GitOps 的基础。你可以为不同环境dev/staging/prod准备不同的 values 文件。结合 Argo CD 或 Flux 这样的 GitOps 工具可以实现配置变更的自动同步和审计让网关的配置和代码一样拥有清晰的变更历史和回滚能力。我个人在实际维护多个集群的 APISIX 时会将所有自定义配置如插件配置、证书 Secret 名称、资源限制都放在一个 Git 仓库中。任何变更都通过 Pull Request 进行经过同行评审后合并到主分支再由 GitOps 工具自动部署到对应集群。这极大地减少了人为误操作也使得灾难恢复变得有章可循。