Higress自定义CRD开发指引

2023年8月10日 · 阅读需 20 分钟


功能划分

这里我们先大概梳理一下Higress工程各目录的职责划分

目录功能说明
apiHigress所涉及操作的kubernetes api
clientHigress集成kubernetes的client进行资源监听与下发
cmd命令行参数解析等处理代码
docker构建Higress docker image的描述文件
docs文档内容
envoyenvoy源码内容
helm使用helm安装Higress等配置
istioistio源码内容
pkg/ingressIngress 资源转换为 Istio 资源等相关代码
pkg/bootstrap包括启动 gRPC/xDS/HTTP server 等的代码
pluginsHigress 插件 sdk,以及官方内置插件代码
registry实现对接多种注册中心进行服务发现的代码
samples一些常见Pod、Service的yaml示例
test单元测试及e2e测试用例
tools编译、构建、image分发以及本地测试环境搭建等脚本

研发指引

CRD模型定义

进入api目录

higress/api

根据所要新建CRD的api类型,选择相对于的子目录,比如

networking/v1

编写CRD模型

比如我这里想定义一个http_2_rpc的CRD资源

http_2_rpc.proto

  1. // Copyright (c) 2022 Alibaba Group Holding Ltd.
    //
    // Licensed under the Apache License, Version 2.0 (the “License”);
    // you may not use this file except in compliance with the License.
    // You may obtain a copy of the License at
    //
    //
    // Unless required by applicable law or agreed to in writing, software
    // distributed under the License is distributed on an “AS IS” BASIS,
    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    // See the License for the specific language governing permissions and
    // limitations under the License.
  2. syntax = proto3”;
  3. import google/api/field_behavior.proto”;
  4. // $schema: higress.networking.v1.Http2Rpc
    // $title: Http2Rpc
    // $description: Configuration affecting service discovery from multi registries
    // $mode: none
  5. package higress.networking.v1;
  6. option go_package = github.com/alibaba/higress/api/networking/v1”;
  7. // <!— crd generation tags
    // +cue-gen:Http2Rpc:groupName:networking.higress.io
    // +cue-gen:Http2Rpc:version:v1
    // +cue-gen:Http2Rpc:storageVersion
    // +cue-gen:Http2Rpc:annotations:helm.sh/resource-policy=keep
    // +cue-gen:Http2Rpc:subresource:status
    // +cue-gen:Http2Rpc:scope:Namespaced
    // +cue-gen:Http2Rpc:resource:categories=higress-io,plural=http2rpcs
    // +cue-gen:Http2Rpc:preserveUnknownFields:false
    // —>
    //
    // <!— go code generation tags
    // +kubetype-gen
    // +kubetype-gen:groupVersion=networking.higress.io/v1
    // +genclient
    // +k8s:deepcopy-gen=true
    // —>
    message Http2Rpc {
    oneof destination {
    DubboService dubbo = 1;
    GrpcService grpc = 2;
    }
    }
  8. message DubboService {
    string service = 1 [(google.api.field_behavior) = REQUIRED];
    string version = 2 [(google.api.field_behavior) = REQUIRED];
    string group = 3 [(google.api.field_behavior) = OPTIONAL];
    repeated Method methods = 4 [(google.api.field_behavior) = REQUIRED];
    }
  9. message Method {
    string service_method = 1 [(google.api.field_behavior) = REQUIRED];
    string headers_attach = 2 [(google.api.field_behavior) = OPTIONAL];
    string http_path = 3 [(google.api.field_behavior) = REQUIRED];
    repeated string http_methods = 4 [(google.api.field_behavior) = REQUIRED];
    repeated Param params = 5;
    }
  10. message Param {
    string param_source = 1 [(google.api.field_behavior) = REQUIRED];
    string param_key = 2 [(google.api.field_behavior) = REQUIRED];
    string param_type = 3 [(google.api.field_behavior) = REQUIRED];
    }
  11. message GrpcService {
    oneof destination {
    string proto_descriptor_str = 1;
    string proto_descriptor_file_path = 2;
    }
    repeated string services = 3 [(google.api.field_behavior) = REQUIRED];
    }

2、代码生成

这里依赖kubernetes code generators生成相关kubetype、client、informer、lister等代码。 在higress根目录执行以下命令,

GENERATE_API=1 make gen-client

执行上述命令后会生成,如下代码

kubernetes customresuource定义

通过将这个定义注册给kubernetes集群,然后就能创建对应的CRD资源实例。 kubernetes-customresuource-definition.png

CRD对应资源对象Go语言的定义及操作方法

Hingress(IngressConfig)初始化及运行阶段会使用这里的api模型。 higress-api.png

kubernetes client apis

Hingress集成kubernetes client与kube-apiserver交互时会使用这里的模型对象。 kubernetes-client-api.png

kubernetes client apis operate

kubernetes-client-api-operate.png

kubernetes client informer

kubernetes-client-informer.png

kubernetes client informer lister

kubernetes-client-informer-lister.png

3、集成 Controller

这里主要是在ingress_config,添加自定义CRD Resource的引用对象,并且通过informer机制监听CRD实例的变化,然后实现相关业务逻辑,比如生成istio EnvoyFilter等

higress/pkg/ingress/config/ingress_config.go

定义相关属性

  1. //异步线程启动后,可以监听CRD-http2rpc资源变化事件
    http2rpcController http2rpc.Http2RpcController
    //资源变化事件处理时通过Lister获取发送变化的CRD实例对象
    http2rpcLister netlisterv1.Http2RpcLister
    //存储全量的http2rpcs资源对象,以便在其他事件流程中消费
    http2rpcs map[string]*higressv1.Http2Rpc

ingress-config.png

在higress启动阶段初始化上述变量

这里就会引用自动化生成的一些代码,进行Controller的创建及事件绑定。 ingress-config-initial.png

实现CRD变更事件处理逻辑

ingress-config-event.png

扩展阅读

Kubernetes Controller 机制详解(一)

Kubernetes Informer机制