企业官网建设流程全解析

• 云原生
• API网关
• 微服务
• 服务网格

Easegress Ingress Controller 是 Easegress 对 Kubernetes 原生 Ingress 机制的实现：它监听集群中的 Ingress、Service、Endpoints 与 Secret 资源，并将其自动翻译为 Easegress 的 HTTP 流量网关与 Pipeline，从而让 Kubernetes 用户用标准的 Ingress 资源即可获得 Easegress 的路由、负载均衡与流量编排能力。本文以仓库内 helm-charts/ingress-controller 中的 Helm Chart 为主线，讲解从创建命名空间、安装/卸载、参数定制，到其底层如何生成 Kubernetes 资源、如何与源码级实现相互印证，最终帮助你在一台 Kubernetes 集群上快速落地一套可用的 Easegress 南北向流量入口。

读完本文，你将掌握：用 Helm 一键安装/卸载 Easegress Ingress Controller；通过--set或values.yaml定制 NodePort、镜像版本、IngressClass 名称、监听命名空间等关键参数；理解 Chart 生成的 Deployment、Service、ConfigMap、RBAC 等资源的含义；并结合源码理解 Ingress 到 Easegress 配置的翻译过程，从而正确创建 Kubernetes Ingress 规则并验证转发结果。

Chart 概览与仓库位置

本 Chart 名为easegress-ingress-controller（Chart.yaml 中name字段），版本1.0.1，属于application类型，定义于 helm-charts/ingress-controller/Chart.yaml。它包含如下 Kubernetes 资源模板：

这套资源与文档 docs/07.Reference/7.03.Ingress-Controller.md 中“手动方式”部署 IngressController 的 YAML 完全对应：文档给出了手写 RBAC、ConfigMap、Deployment、Service 的完整示例，而 Helm Chart 正是把这一过程模板化、参数化，便于在任意命名空间反复安装。

前置条件

• 一个可用的 Kubernetes 集群。参考文档 docs/07.Reference/7.03.Ingress-Controller.md 要求集群为v1.18+；而从源码 pkg/object/ingresscontroller/k8s.go 看，控制器启动时会调用checkKubernetesVersion检查服务端版本，minor < 19时直接 panic 退出（原因是networking.k8s.io/v1从 Kubernetes 1.19 才开始提供），因此实际运行时请确保集群为v1.19 及以上。
• 本机已安装kubectl并能访问集群。
• 本机已安装 Helm（Chart 使用 Helm v2 格式，即apiVersion: v2）。
• 具备创建命名空间、Deployment、Service、ConfigMap、IngressClass 以及 RBAC 资源的权限。

安装步骤

1. 创建目标命名空间

Chart 的安装说明（README）建议先创建独立命名空间，避免与其他组件混在一起：

kubectl create ns ingress-easegress

2. 使用默认参数安装

在仓库根目录下直接安装：

helm install ingress-easegress -n ingress-easegress ./helm-charts/ingress-controller

该命令会以 release 名称ingress-easegress在命名空间ingress-easegress中部署整套资源。由于所有模板资源都以{{ .Release.Name }}命名，因此一个集群中可以安装多个 release 互不冲突。

3. 使用自定义参数安装

Chart 支持用--set覆盖参数：

helm install ingress-easegress -n ingress-easegress ./helm-charts/ingress-controller \ --set service.nodePort=4080 \ --set image.tag=v1.4.0 \ --set ingressClass.name=test-eg \ --set controller.name=test-eg \ --set 'controller.namespaces={ingress-easegress, default}'

各参数的含义与默认值见下文参数表。controller.namespaces使用 Helm 的 set 列表语法{ns1, ns2}，注意整体要用引号包裹。

安装完成后，可参照 docs/07.Reference/7.03.Ingress-Controller.md 中的示例创建后端服务与 Kubernetes Ingress 规则，验证转发是否按预期工作。

Helm 参数详解

README 中的参数表只列出了三个最常用的参数，实际上 values.yaml 中定义了完整的可配置项，下面全部列出：

其中controller.kubeConfig与controller.masterURL在 values.yaml 中以注释形式给出（values.yaml），若你的 Easegress 部署在集群外，可取消注释并填入实际值。

与源码对应的参数语义

IngressController 对象的 Spec 定义在源码 pkg/object/ingresscontroller/ingresscontroller.go：

Spec struct { HTTPServer *httpserver.Spec `json:"httpServer" jsonschema:"required"` KubeConfig string `json:"kubeConfig,omitempty"` MasterURL string `json:"masterURL,omitempty"` Namespaces []string `json:"namespaces,omitempty"` IngressClass string `json:"ingressClass,omitempty"` }

对照DefaultSpec（ingresscontroller.go）可以看到：

• IngressClass的默认值就是"easegress"（defaultIngressClass常量，见 ingresscontroller.go）；
• HTTP 网关的默认参数为KeepAlive: true、KeepAliveTimeout: "60s"、MaxConnections: 10240，这与 Chart 中controller.yaml生成的httpServer配置完全一致（见 templates/ConfigMap.yaml）。

Chart 生成的资源剖析

下面逐一说明 Chart 实际生成的 Kubernetes 资源及其作用，帮助你判断自定义参数最终落到了哪里。

ConfigMap：两份关键配置

templates/ConfigMap.yaml 生成一个 ConfigMap，其中包含两个 key：

• easegress-server.yaml：Easegress 服务端自身的启动配置，核心字段包括：

  • name：实例名（取 release 名称）；
  • cluster-name: easegress-ingress-controller、cluster-role: primary：以单节点 primary 模式运行；
  • api-addr: 0.0.0.0:2381：Easegress 管理 API 监听地址；
  • data-dir: /opt/easegress/data：数据目录；
  • log-dir: {{ .Values.log.path }}：日志目录，即上文log.path参数；
  • debug: false。

• controller.yaml：定义 Easegress 侧的 IngressController 对象，核心字段包括：

  • kind: IngressController、name（来自controller.name）；
  • namespaces（来自controller.namespaces，为空时不生成该字段）；
  • ingressClass（来自ingressClass.name）；
  • httpServer：共享 HTTP 流量网关的基础配置（port: 8080、https: false、keepAlive: true、keepAliveTimeout: 60s、maxConnections: 10240）。

这份 ConfigMap 与参考文档中手动部署的示例（docs/07.Reference/7.03.Ingress-Controller.md）结构一致。

Deployment：拉起 easegress-server

templates/Deployment.yaml 生成的 Deployment 要点：

• 副本数由replicas控制；
• 容器启动命令通过/bin/sh -c执行：

/opt/easegress/bin/easegress-server \ -f /opt/eg-config/easegress-server.yaml \ --initial-object-config-files /opt/eg-config/controller.yaml \ --initial-cluster $(EG_NAME)=http://localhost:2380

其中EG_NAME取自 Pod 的metadata.name（fieldRef），保证每个 Pod 在集群内拥有唯一节点名；--initial-object-config-files参数让 Easegress 在首次启动时创建controller.yaml中定义的 IngressController 对象——这一点与参考文档 docs/07.Reference/7.03.Ingress-Controller.md 中的手动 Deployment 完全同源。

• 两个配置文件通过 ConfigMap 挂载到/opt/eg-config/下（subPath方式）；
• 数据目录/opt/easegress/data挂载emptyDir卷。由于 IngressController 本身无状态，Pod 重启无需保留历史状态（控制器每次收到资源事件都会全量重新翻译）；
• 资源请求为cpu: 100m / memory: 256Mi，上限为cpu: 1200m / memory: 2Gi。

Service：NodePort 对外暴露

templates/Service.yaml 生成type: NodePort的 Service：

• 端口名web，port: 8080（对应 HTTP 网关监听端口），nodePort取自service.nodePort参数（默认30080）；
• selector 为app: {{ .Release.Name }}，与 Deployment 的 Pod 标签对应。

外部流量经{NODE_IP}:{nodePort}进入后，被转发到 Pod 内 Easegress HTTP 网关的 8080 端口。

IngressClass 与匹配规则

templates/IngressClass.yaml 生成一个名为{{ .Values.ingressClass.name }}的 IngressClass 资源，其spec.controller固定为megaease.com/ingress-controller——这正是源码中的defaultIngressControllerName常量（ingresscontroller.go）。

IngressClass 匹配规则（源码 pkg/object/ingresscontroller/k8s.go 的getIngresses方法）：

1. 优先读取 Ingress 的spec.ingressClassName字段；
2. 若该字段为空，则回退读取注解kubernetes.io/ingress.class；
3. 只有匹配上ingressClass参数（默认easegress）的 Ingress 才会被该控制器接管。

因此，你创建的 Ingress 必须设置ingressClassName: easegress（或使用ingressClass.name指定的自定义值），否则控制器不会处理它。

RBAC：最小权限授权

templates/ClusterRole.yaml 中的权限规则为：

- apiGroups: [""] # "" indicates the core API group resources: ["services", "endpoints", "secrets"] verbs: ["get", "watch", "list"] - apiGroups: ["networking.k8s.io"] resources: ["ingresses"] verbs: ["get", "watch", "list"]

即只授予get/watch/list只读权限，覆盖 IngressController 需要监听的四种资源（Ingress、Service、Endpoints、Secret），与参考文档 docs/07.Reference/7.03.Ingress-Controller.md 中的手写 RBAC 示例一致。ClusterRoleBinding将 release 同名的 ServiceAccount 与上述 ClusterRole 绑定，Deployment 通过serviceAccountName: {{ .Release.Name }}使用该账号。

底层工作原理：从 Ingress 到 Easegress 配置

理解 Chart 部署出的控制器行为，有助于你正确编写 Ingress 规则。IngressController 的运行逻辑在源码 pkg/object/ingresscontroller/ingresscontroller.go 中清晰可见，主要分三步：

1. 连接 Kubernetes：通过newK8sClient(ic.spec.MasterURL, ic.spec.KubeConfig)构建客户端，失败则每 10 秒重试；
2. 监听资源：调用k8sClient.watch(ic.spec.Namespaces)对 Ingress、Service、Endpoints、Secret 建立 informer 监听。从 k8s.go 可以看到，namespaces为空时等价于监听全部命名空间；监听 Secret 时还会用owner!=helm的标签选择器过滤掉 Helm 管理的 Secret；informer 每 10 分钟 resync 一次，事件通过容量为 1 的eventCh去重投递（因为每次事件都会触发全量重新翻译，丢弃中间事件是安全的）；
3. 翻译并应用：收到事件后调用translate()（ingresscontroller.go），把当前集群中的 Ingress 集合翻译成一组 Pipeline 与一个共享 HTTP Server 配置，再通过TrafficController的ApplyPipelineForSpec/ApplyTrafficGateForSpec应用到 Easegress；翻译失败时每 10 秒自动重试。

翻译细节位于 pkg/object/ingresscontroller/translator.go：

• Pipeline 命名规则：每个 Ingress backend 对应一条 Pipeline，命名为pipeline-{namespace}-{serviceName}-{port}，WebSocket 场景追加-ws后缀（translator.go）；
• HTTP Server 路由：Ingress 的 host + path 被翻译为 Easegress 的Rule/Path，精确路径（pathType: Exact）与前缀路径（Prefix）分别映射为Path与PathPrefix（translator.go）；通配符主机（如*.megaease.com）会转换成HostRegexp；
• TLS：当httpServer.https: true时，控制器从 Ingress 的 TLS 配置中读取 Secret（要求包含tls.crt与tls.key，见 translator.go）并注入 HTTP Server 证书；
• 默认后端：Ingress 的defaultBackend被翻译为名为pipeline-default的 Pipeline，并作为兜底路由（translator.go）；
• 路由排序：规则按“精确 host 在前、通配符 host 次之、空 host 最后”排序，路径按“精确路径在前、更长前缀优先”排序（translator.go）。

通过 Ingress 注解扩展能力

IngressController 还支持通过 Ingress 注解（annotation）定制代理行为，这些注解在源码 translator.go 与 translator.go 中被读取：

创建后端服务与 Kubernetes Ingress 验证转发

Chart 本身只负责部署控制器，真正的路由规则由标准 Kubernetes Ingress 资源定义。这里直接采用参考文档 docs/07.Reference/7.03.Ingress-Controller.md 中的经典示例：部署一个双容器（hello-app 1.0 / 2.0）的 Deployment 与 Service，再用一个 Ingress 按 Host 分发到不同端口：

--- apiVersion: apps/v1 kind: Deployment metadata: name: hello-deployment spec: selector: matchLabels: app: products department: sales replicas: 2 template: metadata: labels: app: products department: sales spec: containers: - name: hello-v1 image: "us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0" env: - name: "PORT" value: "50001" - name: hello-v2 image: "us-docker.pkg.dev/google-samples/containers/gke/hello-app:2.0" env: - name: "PORT" value: "50002" --- apiVersion: v1 kind: Service metadata: name: hello-service spec: type: NodePort selector: app: products department: sales ports: - name: port-v1 protocol: TCP port: 60001 targetPort: 50001 - name: port-v2 protocol: TCP port: 60002 targetPort: 50002 --- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: ingress-example spec: ingressClassName: easegress rules: - host: "www.example.com" http: paths: - pathType: Prefix path: / backend: service: name: hello-service port: number: 60001 - host: "*.megaease.com" http: paths: - pathType: Prefix path: / backend: service: name: hello-service port: number: 60002

注意ingressClassName: easegress必须与安装时的ingressClass.name（默认easegress）一致。待所有 Pod 就绪后，通过 NodePort 访问并携带不同的 Host 头：

curl http://{NODE_IP}:30080/ -HHost:www.megaease.com # Hello, world! # Version: 2.0.0 curl http://{NODE_IP}:30080/ -HHost:www.example.com # Hello, world! # Version: 1.0.0

从返回的Version字段可以看到，IngressController 已根据 Kubernetes Ingress 规则将请求正确转发到了对应的应用版本。

多实例与高可用

IngressController 是无状态的：所有运行时状态都由 Kubernetes 集群中的 Ingress 等资源决定，每次事件都会全量重新翻译。因此只需把 Helm 的replicas参数调大即可实现多副本高可用：

helm upgrade ingress-easegress -n ingress-easegress ./helm-charts/ingress-controller \ --set replicas=2

参考文档 docs/07.Reference/7.03.Ingress-Controller.md 中也是通过把 Deployment 的replicas从 1 改为 2 来扩展实例；多实例共享同一个 IngressClass，由 Kubernetes 保证 Ingress 资源的可观测性，任一实例故障时其余实例仍能继续翻译与转发流量。

卸载

需要移除时，执行：

helm uninstall ingress-easegress -n ingress-easegress

该命令会删除该 release 创建的全部资源（Deployment、Service、ConfigMap、IngressClass、ServiceAccount、ClusterRole、ClusterRoleBinding）。若你不再需要该命名空间，可另行清理：

kubectl delete ns ingress-easegress

常见问题与注意事项

1. NodePort 范围：Kubernetes 默认 NodePort 范围为 30000-32767，设置service.nodePort时必须在该范围内，否则 Service 创建会失败（README 中对此有明确提示）。
2. Kubernetes 版本：参考文档标注 v1.18+，但源码 pkg/object/ingresscontroller/k8s.go 在版本低于 1.19 时会直接 panic，请以 v1.19+ 为准。
3. IngressClass 不匹配：控制器只处理ingressClassName（或注解kubernetes.io/ingress.class）与ingressClass.name一致的 Ingress，请核对二者是否一致。
4. 命名空间监听范围：controller.namespaces默认只监听default；若你的业务 Ingress 在其他命名空间，需通过--set 'controller.namespaces={ns1, ns2}'显式指定，留空才表示监听全部命名空间。
5. 生产环境镜像标签：默认image.tag=latest便于快速试用，生产环境建议固定到具体发布版本（如v1.4.0），避免镜像更新带来的不确定性。
6. 集群外部署：若 IngressController 运行在 Kubernetes 集群之外，必须在controller.kubeConfig与controller.masterURL中至少指定一个，否则控制器无法连接集群。

进一步阅读

• 参考文档完整版：docs/07.Reference/7.03.Ingress-Controller.md，包含手写 RBAC、ConfigMap、Deployment、Service 的完整 YAML 与多实例扩展说明；
• Chart 参数默认值：helm-charts/ingress-controller/values.yaml；
• 控制器核心实现：pkg/object/ingresscontroller/ingresscontroller.go、Kubernetes 客户端与 informer 监听 pkg/object/ingresscontroller/k8s.go、Ingress 到 Easegress 配置翻译器 pkg/object/ingresscontroller/translator.go；
• Kubernetes Ingress 概念：Kubernetes 官方文档 中关于 ingress-controller 的说明（IngressController 即该概念的实现）。

• 云原生
• API网关
• 微服务
• 服务网格