portworx/kong-ingress-controller

Kong Ingress Controller for PDS SM 技术文档

一、镜像概述和主要用途

1.1 镜像概述

Kong Ingress Controller 是基于 Kong Gateway 的 Kubernetes Ingress 控制器，用于管理集群外部到内部服务的 HTTP/HTTPS 流量路由。本镜像专为 PDS SM 环境优化，提供与 PDS SM 生态的深度集成能力，简化在 PDS SM 平台中部署、配置和运维 Kong Ingress Controller 的流程。

1.2 主要用途

• 管理 PDS SM 环境中 Kubernetes 集群的入站流量路由策略；
• 实现基于路径、主机名、HTTP 方法等规则的流量转发；
• 提供 SSL 终止、负载均衡、认证授权等流量治理能力；
• 与 PDS SM 监控、日志、配置中心等生态组件集成，支持可观测性与配置联动。

二、核心功能和特性

2.1 核心功能

• 标准资源支持：兼容 Kubernetes Ingress、IngressClass、Gateway API（v1beta1+）等标准资源，支持流量路由规则的声明式配置；
• 动态配置更新：通过监听 Kubernetes API 事件实现配置实时同步，无需重启控制器；
• 流量治理能力：支持 SSL/TLS 终止、证书自动管理（ACME 集成）、请求限流、重试、超时控制等；
• 插件扩展：集成 Kong Gateway 插件生态，支持认证（JWT、OAuth2）、监控（Prometheus）、日志（File、HTTP）等插件即插即用；
• PDS SM 集成：内置与 PDS SM 服务发现、配置中心的适配逻辑，支持 PDS SM 特有资源（如自定义路由策略、服务标签）的解析。

2.2 关键特性

• 高可用性：支持多实例部署，通过 leader 选举机制避免单点故障；
• 性能优化：基于 Nginx 内核的 Kong Gateway 提供高吞吐量、低延迟的流量转发；
• 可观测性：暴露 Prometheus 指标接口，支持与 PDS SM 监控系统（如 Grafana）对接；
• 轻量级部署：精简镜像体积，优化资源占用，适配 PDS SM 环境的资源约束；
• 版本兼容性：兼容 Kubernetes 1.21+ 及 PDS SM 最新稳定版。

三、使用场景和适用范围

3.1 典型使用场景

• PDS SM 微服务流量路由：在 PDS SM 环境的 Kubernetes 集群中，通过 Ingress 资源定义微服务间的路由规则，实现基于路径（如 /api/v1/user）或主机名（如 user.example.com）的流量转发；
• 多环境流量隔离：结合 PDS SM 环境标签（如 env=prod、env=test），通过 IngressClass 或 Gateway 资源隔离不同环境的流量；
• PDS SM 监控与日志集成：通过内置插件将流量 metrics、访问日志推送到 PDS SM 监控平台（如 Prometheus）和日志系统（如 ELK），实现全链路可观测；
• 安全流量治理：在 PDS SM 生产环境中，通过 SSL 终止、JWT 认证等功能保护内部服务，满足合规性要求。

3.2 适用范围

• 环境要求：运行 Kubernetes 1.21+ 的 PDS SM 平台；
• 架构适配：基于 Kubernetes 的 PDS SM 微服务架构；
• 功能依赖：需使用 Kong Gateway 作为流量转发引擎的 PDS SM 场景；
• 生态集成：需与 PDS SM 服务网格、配置中心、监控系统协同工作的场景。

四、使用方法和配置说明

4.1 前置条件

• PDS SM 环境中已部署 Kubernetes 集群（1.21+）；
• 集群内已安装 Kong Gateway（推荐使用与控制器版本匹配的 Kong 网关，如控制器 v2.12.x 对应 Kong Gateway 3.5.x）；
• 本地环境已配置 kubectl 并拥有集群管理员权限（用于部署控制器资源）；
• 若使用 Helm 安装，需提前安装 Helm 3.8+。

4.2 安装方式

4.2.1 Helm 安装（推荐，Kubernetes 环境）

通过 Helm Chart 部署，支持与 PDS SM 环境参数联动：

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

# 部署 Kong Ingress Controller for PDS SM（指定 PDS SM 集成参数）
helm install kong-ingress-controller kong/kong \
  --namespace kong --create-namespace \
  --set ingressController.enabled=true \
  --set ingressController.image.repository=kong/ingress-controller-pds-sm \  # 假设镜像名为该名称
  --set ingressController.image.tag=v2.12.0-pds-sm.1 \  # 示例版本号
  --set pdsSM.integration.enabled=true \  # 启用 PDS SM 集成
  --set pdsSM.configPath=/etc/pds-sm/config  # PDS SM 配置文件路径

4.2.2 Docker 部署（测试环境）

适用于非 Kubernetes 环境的功能验证（生产环境建议使用 Kubernetes 部署）：

bash
docker run -d \
  --name kong-ingress-controller-pds-sm \
  --network=host \  # 测试环境简化网络配置（生产环境需按需调整）
  -e KUBECONFIG=/etc/kubeconfig \  # 挂载 Kubernetes API 访问配置
  -e INGRESS_CLASS=kong-pds-sm \  # 指定 IngressClass，与 PDS SM 环境关联
  -e KONG_ADMIN_URL=http://kong-gateway:8001 \  # Kong Gateway Admin API 地址
  -e PDS_SM_INTEGRATION_ENABLED=true \  # 启用 PDS SM 集成
  -v /path/to/kubeconfig:/etc/kubeconfig \  # 挂载本地 kubeconfig
  -v /path/to/pds-sm/config:/etc/pds-sm/config \  # 挂载 PDS SM 配置
  kong/ingress-controller-pds-sm:v2.12.0-pds-sm.1

4.2.3 Docker Compose 配置（本地测试）

yaml
version: '3.8'
services:
  kong-ingress-controller:
    image: docker.xuanyuan.run/kong/ingress-controller-pds-sm:v2.12.0-pds-sm.1
    container_name: kong-ingress-controller-pds-sm
    environment:
      - KUBECONFIG=/etc/kubeconfig
      - INGRESS_CLASS=kong-pds-sm
      - KONG_ADMIN_URL=http://kong-gateway:8001
      - PDS_SM_INTEGRATION_ENABLED=true
      - PDS_SM_CONFIG_PATH=/etc/pds-sm/config
    volumes:
      - ./kubeconfig:/etc/kubeconfig:ro
      - ./pds-sm-config:/etc/pds-sm/config:ro
    depends_on:
      - kong-gateway  # 假设 Kong Gateway 与控制器联动部署

  kong-gateway:
    image: docker.xuanyuan.run/kong:3.5.0
    container_name: kong-gateway
    ports:
      - "80:8000"   # 客户端流量端口
      - "443:8443"  # HTTPS 端口
      - "8001:8001" # Admin API 端口（供控制器调用）

4.3 核心配置参数

4.3.1 控制器核心参数

4.3.2 PDS SM 集成参数

4.4 配置示例

4.4.1 Ingress 资源配置（PDS SM 服务路由）

在 PDS SM 环境的 Kubernetes 集群中，通过 Ingress 资源定义路由规则：

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: pds-sm-service-ingress
  namespace: pds-sm-apps  # PDS SM 应用所在命名空间
  annotations:
    konghq.com/plugins: "rate-limiting,prometheus"  # 启用限流和监控插件
spec:
  ingressClassName: kong-pds-sm  # 匹配控制器指定的 IngressClass
  rules:
  - host: api.pds-sm.example.com  # PDS SM 环境的访问域名
    http:
      paths:
      - path: /user
        pathType: Prefix
        backend:
          service:
            name: user-service  # PDS SM 管理的微服务
            port:
              number: 80
      - path: /order
        pathType: Prefix
        backend:
          service:
            name: order-service  # PDS SM 管理的微服务
            port:
              number: 80
  tls:
  - hosts:
    - api.pds-sm.example.com
    secretName: pds-sm-tls-cert  # PDS SM 环境中的 TLS 证书密钥

4.4.2 Docker Compose 完整配置（含 PDS SM 集成）

yaml
version: '3.8'
services:
  ingress-controller:
    image: docker.xuanyuan.run/kong/ingress-controller-pds-sm:v2.12.0-pds-sm.1
    container_name: pds-sm-kong-ingress
    restart: always
    environment:
      - KUBECONFIG=/etc/kubeconfig
      - INGRESS_CLASS=kong-pds-sm
      - KONG_ADMIN_URL=http://kong-gateway:8001
      - PDS_SM_INTEGRATION_ENABLED=true
      - PDS_SM_CONFIG_PATH=/etc/pds-sm/config
    volumes:
      - ./kubeconfig:/etc/kubeconfig:ro
      - ./pds-sm-config:/etc/pds-sm/config:ro  # 挂载 PDS SM 配置（如服务发现地址、认证信息）
    depends_on:
      - kong-gateway

  kong-gateway:
    image: docker.xuanyuan.run/kong:3.5.0
    container_name: pds-sm-kong-gateway
    restart: always
    ports:
      - "80:8000"   # HTTP 流量端口
      - "443:8443"  # HTTPS 流量端口
      - "8001:8001" # Admin API 端口（供控制器调用）
    environment:
      - KONG_PROXY_ACCESS_LOG=/dev/stdout
      - KONG_ADMIN_ACCESS_LOG=/dev/stdout
      - KONG_PROXY_ERROR_LOG=/dev/stderr
      - KONG_ADMIN_ERROR_LOG=/dev/stderr

五、注意事项

• 确保 Kong Ingress Controller 版本与 PDS SM 环境版本兼容（参考镜像标签中的 pds-sm.x 后缀）；
• 生产环境中必须启用 leader-elect 以保证高可用，避免单实例故障；
• PDS SM 集成功能依赖 /etc/pds-sm/config 目录下的配置文件，需通过挂载确保文件存在且格式正确；
• 监控指标推荐通过 PDS SM 监控平台采集，控制器默认暴露指标端口 10254/metrics。