kong/gateway-operator-oss

Kong Gateway Operator Docker 镜像文档

一、镜像概述和主要用途

概述

本镜像为 Kong Gateway 的 Kubernetes Operator 官方容器镜像，基于 https://github.com/Kong/gateway-operator 项目构建。该 Operator 旨在通过 Kubernetes 原生的声明式 API（CustomResourceDefinition, CRD）自动化管理 Kong Gateway 的全生命周期，简化在 Kubernetes 集群中部署、配置、升级和维护 Kong Gateway 的流程。

主要用途

• 自动化部署 Kong Gateway 实例（包括数据平面和控制平面）
• 声明式配置 Kong Gateway 资源（如服务、路由、插件、Upstream 等）
• 管理 Kong Gateway 的版本升级、回滚及故障恢复
• 监控 Kong Gateway 实例状态并自动修复异常
• 与 Kubernetes 原生资源（如 Service、Ingress、ConfigMap）无缝集成

二、核心功能和特性

1. 全生命周期管理

• 自动化部署：通过 KongGateway CRD 定义 Gateway 规格，Operator 自动创建 Deployment、Service、ConfigMap 等底层资源。
• 版本控制：支持指定 Kong Gateway 镜像版本，自动处理升级/回滚流程（含灰度发布能力）。
• 状态自愈：实时监控 Gateway 实例健康状态，自动重启故障 Pod 或重新调度资源。

2. 声明式配置管理

• CRD 驱动：通过 KongGateway、KongPlugin、KongRoute 等 CRD 定义 Gateway 配置，替代手动修改配置文件。
• 动态更新：配置变更通过 Kubernetes API 提交后，Operator 自动同步至 Kong Gateway，无需重启实例。
• 配置校验：内置配置合法性校验，避免无效配置导致 Gateway 异常。

3. Kubernetes 原生集成

• 资源联动：自动关联 Kubernetes Service、Ingress 资源，简化路由规则配置。
• RBAC 兼容：遵循 Kubernetes RBAC 权限模型，支持细粒度权限控制。
• Prometheus 监控：暴露 metrics 接口，支持与 Prometheus、Grafana 集成监控 Gateway 性能。

4. 高可用与扩展性

• 多实例部署：支持配置 Gateway 实例副本数，实现负载均衡和故障冗余。
• 自定义资源限制：可配置 CPU/内存资源请求与限制，适配不同集群资源环境。
• 插件管理：通过 KongPlugin CRD 声明式管理 Kong 插件，支持全局/路由级插件配置。

三、使用场景和适用范围

适用场景

• Kubernetes 环境中的 Kong Gateway 部署：需在 Kubernetes 集群中标准化部署 Kong Gateway 的场景。
• 多团队协作管理：通过 CRD 实现配置即代码（Configuration as Code），支持多团队共享 Gateway 资源并通过 GitOps 流程管理配置。
• 大规模 Gateway 集群：需管理成百上千个路由/服务配置，或跨多命名空间部署 Gateway 的场景。
• 频繁配置更新：需动态调整路由规则、插件策略，且要求零停机更新的业务场景。

适用范围

• 已部署 Kubernetes 集群（版本 ≥ 1.24）的环境
• 使用 Kong Gateway 作为 API 网关、服务网格入口或边缘代理的用户
• 熟悉 Kubernetes 声明式 API 和 CRD 概念的运维/开发团队

四、使用方法和配置说明

1. 前提条件

• Kubernetes 集群版本：≥ 1.24（推荐 1.25+）
• 集群已配置 kubectl 工具且具有管理员权限
• 集群可访问 Docker Hub 或私有镜像仓库（用于拉取本镜像及 Kong Gateway 基础镜像）

2. 部署 Operator

2.1 部署方式

Kong Gateway Operator 支持通过 Helm Chart 或 直接应用 Manifest 文件 部署。推荐使用 Helm 简化依赖管理。

方式一：通过 Helm 部署（推荐）

bash
# 添加 Kong Helm 仓库
helm repo add kong https://charts.konghq.com
helm repo update

# 部署 Kong Gateway Operator（默认部署至 kong 命名空间）
helm install gateway-operator kong/gateway-operator --namespace kong --create-namespace

方式二：直接应用 Manifest 文件

bash
# 下载官方部署 manifest
kubectl apply -f https://raw.githubusercontent.com/Kong/gateway-operator/main/deploy/manifests/gateway-operator.yaml

3. 创建 Kong Gateway 实例

部署 Operator 后，通过创建 KongGateway CRD 资源声明式定义 Gateway 实例。

3.1 基础示例（单实例模式）

创建 kong-gateway.yaml：

yaml
apiVersion: gateway.konghq.com/v1beta1
kind: KongGateway
metadata:
  name: my-kong-gateway
  namespace: default
spec:
  # 指定 Kong Gateway 镜像版本（默认使用与 Operator 兼容的最新稳定版）
  image: kong/kong-gateway:3.6
  # 数据平面副本数
  replicas: 2
  # 服务类型（ClusterIP/NodePort/LoadBalancer）
  service:
    type: LoadBalancer
  # 资源限制
  resources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: 1000m
      memory: 1Gi
  # 启用 Admin API（仅集群内访问）
  admin:
    enabled: true
    service:
      type: ClusterIP

应用该配置：

bash
kubectl apply -f kong-gateway.yaml

4. 验证部署

4.1 检查 Operator 状态

bash
kubectl get pods -n kong -l app.kubernetes.io/name=gateway-operator

预期输出（状态为 Running）：

NAME                                   READY   STATUS    RESTARTS   AGE
gateway-operator-7f9b6c7d6c-abc12     1/1     Running   0          5m

4.2 检查 Kong Gateway 实例

bash
kubectl get pods -l app.kubernetes.io/instance=my-kong-gateway

预期输出（所有副本均为 Running）：

NAME                                      READY   STATUS    RESTARTS   AGE
my-kong-gateway-data-plane-7f8d9c6b-2xwz   1/1     Running   0          3m
my-kong-gateway-data-plane-7f8d9c6b-9yqv   1/1     Running   0          3m

4.3 获取 Gateway 服务地址

bash
kubectl get service my-kong-gateway-proxy

通过 EXTERNAL-IP（Load*** 类型）或 NodePort 访问 Gateway。

五、配置参数说明

1. Operator 部署参数

部署 Operator 时可通过 Helm values 或 Manifest 调整以下核心参数：

2. KongGateway CRD 配置参数

通过 KongGateway CRD 定义 Gateway 实例时，常用配置项如下：

3. 环境变量配置

Operator 容器支持通过环境变量调整运行时行为：

六、注意事项

1. Kubernetes 版本兼容性：需确保集群版本 ≥ 1.24，低于此版本可能导致 CRD 解析失败。
2. 权限要求：Operator 需要集群级权限（ClusterRole）以管理 CRD 和跨命名空间资源，部署时需确保 RBAC 配置正确。
3. 网络策略：若集群启用网络策略（NetworkPolicy），需允许 Operator 访问 Kubernetes API Server 及 Kong Gateway 实例的网络通信。
4. 资源规划：根据 Gateway 预期流量调整 spec.resources，避免资源不足导致性能瓶颈或 Pod 被驱逐。
5. 升级策略：升级 Operator 前需参考 https://github.com/Kong/gateway-operator/blob/main/UPGRADING.md%EF%BC%8C%E7%A1%AE%E4%BF%9D%E4%B8%8E%E7%8E%B0%E6%9C%89 CRD 版本兼容。

七、参考链接

• https://github.com/Kong/gateway-operator
• Kong Gateway 官方文档
• Kong Gateway Operator Helm Chart