materialize/k8s-eip-operator

概述

该Docker镜像封装了一个Kubernetes Operator，旨在通过AWS EIP（弹性IP）实现Kubernetes Pod与外部网络的稳定连接管理。通过自动化EIP分配、关联及回收流程，解决Pod因动态调度导致IP变化而引发的外部连接不稳定问题，确保Pod对外提供服务时拥有固定且可靠的网络入口。

核心功能与特性

• EIP自动分配：根据配置策略自动从AWS EIP资源池分配可用弹性IP
• Pod动态关联：监控Pod生命周期事件（创建/删除/调度），自动将EIP关联至目标Pod
• EIP智能回收：当Pod删除或脱离管理范围时，自动释放关联EIP并回收到资源池
• AWS原生集成：通过AWS EC2 API与AWS云服务深度集成，支持EIP标签筛选、区域隔离
• 自定义策略支持：通过Kubernetes CRD（自定义资源定义）配置EIP分配规则、Pod选择逻辑及资源限制
• 故障自愈机制：检测EIP与Pod关联异常（如网络中断、API调用失败）时自动执行修复流程

使用场景

• 对外服务场景：需向公网提供固定IP访问入口的Kubernetes服务（如Web应用、API端点）
• 第三方集成场景：需通过固定IP与外部系统（如支付网关、合作伙伴API）建立可信连接的业务
• 合规审计场景：满足***、政务等行业对网络入口IP固定化的合规要求
• 高可用架构：结合Kubernetes滚动更新、故障转移能力，实现服务IP不变的无缝升级

使用方法与配置说明

部署前提

• Kubernetes集群版本 ≥ 1.21（需支持CRD v1及Operator Lifecycle Manager）
• AWS账户权限：集群节点需具备EC2 EIP管理权限（推荐通过IAM Role绑定，最小权限策略包含ec2:DescribeAddresses、ec2:AssociateAddress、ec2:DisassociateAddress）
• 预创建AWS EIP资源池（可通过标签eip-manager=operator-controlled标识管理范围）
• 网络环境：集群需能访问AWS EC2 API端点（ec2.<region>.amazonaws.com）

部署步骤

1. 安装CRD

bash
kubectl apply -f https://raw.githubusercontent.com/[项目官方仓库]/main/config/crd/bases/networking.operator.io_eipconnectors.yaml

2. 部署Operator

通过kubectl部署：

bash
kubectl apply -f https://raw.githubusercontent.com/[项目官方仓库]/main/config/manager/manager.yaml

通过Helm部署（推荐生产环境）：

bash
helm repo add eip-operator https://[官方Helm仓库]
helm install eip-operator eip-operator/eip-operator \
  --namespace eip-operator-system \
  --create-namespace \
  --set aws.region=us-west-2 \
  --set rbac.create=true

核心配置参数

通过创建EipConnector自定义资源定义连接策略，示例配置：

yaml
apiVersion: networking.operator.io/v1alpha1
kind: EipConnector
metadata:
  name: production-eip-policy
  namespace: default
spec:
  # AWS区域配置
  aws:
    region: ap-southeast-1
    eipSelector:
      matchLabels:
        environment: production  # 筛选带此标签的EIP资源
  # Pod选择规则
  podSelector:
    matchLabels:
      app: payment-service      # 匹配需关联EIP的Pod标签
    matchExpressions:
      - key: tier
        operator: In
        values: ["frontend"]
  # 资源限制
  resourceConstraints:
    maxEipCount: 10             # 最大EIP分配数量
    eipReuseDelay: 300s         # EIP释放后可重用的冷却时间
  # 关联模式
  associationMode:
    type: "ip-table"            # 支持"ip-table"(直接绑定Pod IP)或"service-proxy"(通过Service转发)

环境变量配置

Operator部署时需配置以下核心环境变量（通过Deployment的env字段设置）：

部署验证

1. 检查Operator运行状态：

bash
kubectl get pods -n eip-operator-system

2. 验证CRD资源创建：

bash
kubectl get eipconnectors networking.operator.io -o wide

3. 查看EIP分配日志：

bash
kubectl logs -f deployment/eip-operator-controller-manager -n eip-operator-system -c manager

注意事项

• 权限管理：生产环境禁止使用长期静态AWS凭证，推荐通过IAM Roles for Service Accounts (IRSA) 实现Pod级权限控制
• EIP资源规划：需提前在AWS账户中预留足够EIP配额，避免分配失败
• 网络策略兼容：确保集群网络策略允许Operator与AWS EC2 API、目标Pod之间的通信
• 升级注意事项：升级Operator前需备份CRD资源，避免自定义策略配置丢失