kong/gateway-operator

Kong Gateway Operator Docker 镜像文档

一、镜像概述和主要用途

Kong Gateway Operator 是一个 Kubernetes Operator，用于在 Kubernetes 集群中自动化部署、配置、管理和监控 Kong Gateway 实例的生命周期。本 Docker 镜像是该 Operator 的容器化分发形式，旨在简化 Kong Gateway 在 Kubernetes 环境中的运维流程，降低手动操作成本，提升部署一致性和可靠性。

二、核心功能和特性

2.1 核心功能

• 自动化生命周期管理：自动处理 Kong Gateway 实例的部署、升级、回滚和销毁。
• 配置即代码：通过 Kubernetes 自定义资源定义（CRD）管理 Kong Gateway 配置（如路由、插件、上游服务等），支持 GitOps 工作流。
• 高可用性保障：自动检测并恢复故障实例，支持多副本部署和健康检查。
• 原生 Kubernetes 集成：与 Kubernetes Ingress、Service、ConfigMap 等资源无缝集成，支持动态配置更新。
• 状态监控：暴露 Prometheus 指标，支持与监控系统（如 Grafana）集成，实时监控 Gateway 状态和性能。

2.2 关键特性

• 声明式配置：通过 CRD（如 KongGateway、KongPlugin、KongIngress 等）定义期望状态，Operator 自动协调实际状态。
• 版本兼容性：支持 Kong Gateway 多种版本，可通过配置指定目标版本。
• 安全增强：支持 TLS 证书自动注入、RBAC 权限控制，符合 Kubernetes 安全最佳实践。
• 可扩展性：支持自定义插件和扩展，满足特定业务需求。

三、使用场景和适用范围

3.1 适用场景

• Kubernetes 环境中的 Kong Gateway 部署：需在 K8s 集群中标准化部署和管理 Kong Gateway 的场景。
• API 网关自动化运维：减少手动操作，通过声明式配置实现 Gateway 配置的版本化和自动化更新。
• 微服务架构流量管理：作为微服务架构的入口网关，处理路由、认证、限流、监控等流量治理需求。
• 高可用与灾备：需保障 Gateway 服务连续性，自动应对节点故障或配置错误的场景。

3.2 适用范围

• Kubernetes 集群（版本 1.21+）。
• 需使用 Kong Gateway 作为 API 网关的团队或组织。
• 采用 DevOps/GitOps 工作流的技术团队。
• 对网关高可用性、可扩展性和可观测性有要求的企业级应用。

四、使用方法和配置说明

4.1 前提条件

• Kubernetes 集群版本 ≥ 1.21。
• 集群已安装 cert-manager（用于自动生成 Operator 所需的 TLS 证书，版本 ≥ 1.3.0）。
• 具备集群管理员权限（用于部署 CRD 和 RBAC 资源）。

4.2 部署步骤

4.2.1 通过 Helm Chart 部署（推荐）

Kong 官方提供 Helm Chart 简化部署流程：

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

# 安装 Kong Gateway Operator（指定命名空间，如 kong-system）
helm install kong-gateway-operator kong/gateway-operator \
  --namespace kong-system \
  --create-namespace \
  --version 0.14.0  # 替换为最新版本

4.2.2 通过 Kubectl 部署

直接应用官方发布的 YAML 清单：

bash
# 部署 CRD
kubectl apply -f https://raw.githubusercontent.com/Kong/gateway-operator/main/config/crd/bases/gateway-operator.konghq.com_konggateways.yaml
kubectl apply -f https://raw.githubusercontent.com/Kong/gateway-operator/main/config/crd/bases/gateway-operator.konghq.com_kongplugins.yaml
# ... 其他 CRD（完整列表见官方文档）

# 部署 Operator
kubectl apply -f https://raw.githubusercontent.com/Kong/gateway-operator/main/deploy/manifests/operator.yaml

4.3 核心配置说明

4.3.1 自定义资源定义（CRD）

Operator 通过以下 CRD 管理 Kong Gateway 配置：

4.3.2 KongGateway 配置示例

yaml
apiVersion: gateway-operator.konghq.com/v1beta1
kind: KongGateway
metadata:
  name: kong-gateway
  namespace: kong
spec:
  replicas: 3  # 3 副本确保高可用
  image: kong/kong-gateway:3.5  # 指定 Kong Gateway 镜像版本
  resources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: 1000m
      memory: 1Gi
  service:
    type: LoadBalancer  # 暴露为 LoadBalancer 服务
  env:
    - name: KONG_LOG_LEVEL
      value: "info"  # 日志级别
    - name: KONG_PROXY_ACCESS_LOG
      value: "/dev/stdout"  # 访问日志输出到标准输出

4.4 环境变量配置

Operator 自身支持通过环境变量调整行为，常见配置如下：

五、部署示例

5.1 Helm 部署完整流程

bash
# 1. 安装 cert-manager（Operator 依赖）
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.1/cert-manager.yaml

# 2. 等待 cert-manager 就绪
kubectl wait --for=condition=Available deployment --all -n cert-manager --timeout=300s

# 3. 添加 Kong Helm 仓库并更新
helm repo add kong https://charts.konghq.com
helm repo update

# 4. 安装 Kong Gateway Operator
helm install kong-gateway-operator kong/gateway-operator \
  --namespace kong-system \
  --create-namespace \
  --set watchNamespace=kong  # 仅监控 kong 命名空间

# 5. 部署 KongGateway 实例
kubectl apply -f - <<EOF
apiVersion: gateway-operator.konghq.com/v1beta1
kind: KongGateway
metadata:
  name: kong-gateway
  namespace: kong
spec:
  replicas: 2
  image: kong/kong-gateway:3.5
  service:
    type: NodePort
EOF

# 6. 验证部署
kubectl get pods -n kong  # 查看 Kong Gateway 实例 pod
kubectl get svc -n kong   # 查看 Gateway 服务地址

5.2 验证 Operator 功能

部署完成后，可通过创建 KongPlugin 验证配置是否自动生效：

yaml
# 创建一个限流插件
apiVersion: gateway-operator.konghq.com/v1beta1
kind: KongPlugin
metadata:
  name: rate-limit-plugin
  namespace: kong
spec:
  pluginName: rate-limiting
  config:
    minute: 10  # 每分钟允许 10 次请求
    policy: local

将插件关联到 Ingress 路由：

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-ingress
  namespace: kong
  annotations:
    konghq.com/plugins: rate-limit-plugin  # 关联上述限流插件
spec:
  ingressClassName: kong  # 使用 Kong Ingress Class
  rules:
    - http:
        paths:
          - path: /demo
            pathType: Prefix
            backend:
              service:
                name: demo-service
                port:
                  number: 80

六、注意事项

• Operator 与 Kong Gateway 版本需匹配，具体兼容性参考 Kong 官方文档。
• 生产环境建议通过 Helm 部署，便于版本管理和配置更新。
• 高并发场景下需合理配置 KongGateway 的资源限制（CPU/内存），避免性能瓶颈。
• 定期备份 CRD 资源，防止配置丢失。