Wildcard Higress Controller

English | 中文

Kubernetes Controller 用于自动化管理 Higress 泛域名路由和实例配置。

📋 目录

• 功能特性
• 架构设计
• 快速开始
• 使用示例
• 配置说明
• 开发指南
• 贡献指南
• 许可证

✨ 功能特性

Service Controller

• 🔍 监听 Kubernetes Service 的所有生命周期事件
• 🏷️ 通过 higress/type: instance annotation 识别 Higress 实例 Service
• 📊 自动打印 Service 信息和关联 Pod 信息
• 🔄 支持 Service 的创建、更新和删除事件

ConfigMap Controller

• 📝 监听带有 higress.io/config-map-type: domain 标签的 ConfigMap
• 🌐 自动创建对应的 Ingress 资源用于域名路由
• 🔗 自动绑定到对应 namespace 下的 instance Service
• 🗑️ ConfigMap 删除时自动清理关联的 Ingress 资源
• 🔒 使用 Finalizer 机制确保资源正确清理

🏗️ 架构设计

┌─────────────────────────────────────────────────────────────┐
│                    Kubernetes Cluster                        │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │         Wildcard Higress Controller                    │ │
│  │                                                         │ │
│  │  ┌──────────────────┐    ┌──────────────────┐         │ │
│  │  │ Service          │    │ ConfigMap        │         │ │
│  │  │ Controller       │    │ Controller       │         │ │
│  │  └────────┬─────────┘    └────────┬─────────┘         │ │
│  │           │                       │                    │ │
│  └───────────┼───────────────────────┼────────────────────┘ │
│              │                       │                      │
│              ▼                       ▼                      │
│  ┌───────────────────┐   ┌──────────────────┐             │
│  │ Service           │   │ ConfigMap        │             │
│  │ (higress/type:    │   │ (domain config)  │             │
│  │  instance)        │   │                  │             │
│  └───────────────────┘   └──────────────────┘             │
│              │                       │                      │
│              │                       ▼                      │
│              │           ┌──────────────────┐             │
│              └──────────►│ Ingress          │             │
│                          │ (higress-manager)│             │
│                          └──────────────────┘             │
└─────────────────────────────────────────────────────────────┘

🚀 快速开始

前置要求

• Kubernetes 1.19+
• Helm 3.0+ (可选)
• Go 1.21+ (仅开发需要)

方式一: 使用 Helm 部署 (推荐)

# 1. 创建 namespace
kubectl create namespace higress-manager

# 2. 安装 chart
helm install wildcard-higress ./charts/wildcard-higress \
  --namespace higress-manager \
  --set image.repository=wildcard-higress \
  --set image.tag=latest

# 3. 验证部署
kubectl get pods -n higress-manager

方式二: 使用 Kustomize 部署

# 1. 应用配置
kubectl apply -k config/

# 2. 验证部署
kubectl get pods -n higress-manager

方式三: 本地开发运行

# 1. 安装依赖
go mod download

# 2. 运行 controller
go run main.go

卸载

# Helm 卸载
helm uninstall wildcard-higress -n higress-manager

# Kustomize 卸载
kubectl delete -k config/

📖 使用示例

示例 1: 创建 Higress 实例 Service

创建带有 higress/type: instance annotation 的 Service：

apiVersion: v1
kind: Service
metadata:
  name: my-higress-instance
  namespace: my-namespace
  annotations:
    higress/type: instance
spec:
  type: ClusterIP
  selector:
    app: my-app
  ports:
    - name: http
      port: 80
      targetPort: 8080
      protocol: TCP

Controller 会自动检测并打印该 Service 及其 Pod 的信息。

示例 2: 创建域名配置 ConfigMap

创建带有 higress.io/config-map-type: domain 标签的 ConfigMap：

apiVersion: v1
kind: ConfigMap
metadata:
  name: domain-config
  namespace: my-namespace
  labels:
    higress.io/config-map-type: domain
data:
  domain: example.com

Controller 会自动：

1. 查找 my-namespace 下带有 higress/type: instance annotation 的 Service
2. 在 higress-manager namespace 创建对应的 Ingress
3. 设置 Ingress 的 higress.io/destination 指向找到的 Service
4. 设置 Ingress 的 higress.io/exact-match-header-Host 为 example.com

示例 3: 完整部署示例

---
# 1. 创建 namespace
apiVersion: v1
kind: Namespace
metadata:
  name: my-app

---
# 2. 创建 Higress 实例 Service
apiVersion: v1
kind: Service
metadata:
  name: higress-instance
  namespace: my-app
  annotations:
    higress/type: instance
spec:
  type: ClusterIP
  selector:
    app: my-app
  ports:
    - name: http
      port: 80
      targetPort: 8080

---
# 3. 创建域名配置
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-domain
  namespace: my-app
  labels:
    higress.io/config-map-type: domain
data:
  domain: app.example.com

⚙️ 配置说明

命令行参数

参数	默认值	描述
--metrics-addr	:8080	Prometheus 指标端点地址
--health-probe-bind-address	:8081	健康检查端点地址
--leader-elect	false	是否启用 Leader 选举 (多副本部署时建议启用)
--leader-election-id	wildcard-higress-controller-lock	Leader 选举锁的 ID
--higress-manager-namespace	higress-manager	Higress Manager 命名空间

Helm Chart 配置

主要配置项 (values.yaml):

# 副本数
replicaCount: 1

# 镜像配置
image:
  repository: wildcard-higress
  tag: latest
  pullPolicy: IfNotPresent

# 资源限制
resources:
  limits:
    cpu: 500m
    memory: 128Mi
  requests:
    cpu: 10m
    memory: 64Mi

# Leader 选举
leaderElection:
  enabled: false

# Higress Manager 命名空间
higressManagerNamespace: higress-manager

环境变量

变量名	描述	默认值
HIGRESS_MANAGER_NAMESPACE	Higress Manager 命名空间	higress-manager

🛠️ 开发指南

前置要求

• Go 1.21+
• Docker
• kubectl
• Helm 3.0+ (可选)
• kind 或其他 Kubernetes 集群 (用于测试)

本地开发

# 1. 克隆仓库
git clone https://github.com/yourusername/wildcard-higress.git
cd wildcard-higress

# 2. 安装依赖
go mod download

# 3. 本地构建
make build

# 4. 运行测试
make test

# 5. 本地运行 (需要 kubeconfig)
go run main.go

使用 Makefile

项目提供了 Makefile 支持常用操作：

# 显示帮助信息
make help

# 本地构建
make build

# 运行单元测试
make test

# 代码格式化
make fmt

# 代码检查
make vet

# 构建 Docker 镜像
make docker-build IMG=wildcard-higress:latest

# 推送 Docker 镜像
make docker-push IMG=wildcard-higress:latest

# Helm 安装
make helm-install

# Helm 卸载
make helm-uninstall

# Helm 模板渲染
make helm-template

# Helm lint 检查
make helm-lint

# Kustomize 部署
make deploy IMG=wildcard-higress:latest

# Kustomize 卸载
make undeploy

# 清理构建产物
make clean

运行测试

# 运行所有测试
go test ./...

# 运行测试并生成覆盖率报告
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# 运行特定包的测试
go test ./controllers/...

代码规范

• 遵循 Go 官方代码规范
• 使用 gofmt 格式化代码
• 使用 golangci-lint 进行代码检查
• 为新功能添加单元测试
• 更新相关文档

📁 目录结构

wildcard-higress/
├── Makefile                          # Makefile 构建脚本
├── Dockerfile                        # Docker 构建文件
├── LICENSE                           # Apache 2.0 许可证
├── README.md                         # 项目说明文档
├── CONTRIBUTING.md                   # 贡献指南
├── CHANGELOG.md                      # 变更日志
├── .gitignore                        # Git 忽略文件
├── main.go                           # 程序入口
├── go.mod                            # Go 模块定义
├── go.sum                            # Go 依赖锁定
├── controllers/                      # Kubernetes Controllers
│   ├── higressinstance_controller.go # Service Controller
│   ├── configmap_controller.go       # ConfigMap Controller
│   └── *_test.go                     # 单元测试
├── pkg/                              # 公共包
│   └── api/                          # API 定义
├── charts/                           # Helm Charts
│   └── wildcard-higress/
│       ├── Chart.yaml
│       ├── values.yaml
│       └── templates/
├── config/                           # Kustomize 配置
│   ├── kustomization.yaml
│   ├── manager/
│   │   └── manager.yaml
│   └── rbac/
│       ├── role.yaml
│       └── role_binding.yaml
├── scripts/                          # 脚本文件
│   └── test-*.yaml                   # 测试用例
├── docs/                             # 文档
│   ├── PRD.md                        # 产品需求文档
│   └── architecture.md               # 架构设计文档
└── .github/                          # GitHub 配置
    ├── workflows/                    # CI/CD 工作流
    ├── ISSUE_TEMPLATE/               # Issue 模板
    └── PULL_REQUEST_TEMPLATE.md      # PR 模板

🤝 贡献指南

我们欢迎所有形式的贡献！请查看 CONTRIBUTING.md 了解如何参与贡献。

如何贡献

1. Fork 本仓库
2. 创建您的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交您的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启一个 Pull Request

📝 许可证

本项目采用 Apache License 2.0 许可证 - 详见 LICENSE 文件。

🙏 致谢

• Kubernetes - 容器编排平台
• Higress - 云原生 API 网关
• Kubebuilder - Kubernetes API 构建框架

⭐ Star History

如果这个项目对您有帮助，请给我们一个 Star ⭐️