Skip to content

Latest commit

 

History

History
227 lines (183 loc) · 7.52 KB

README_CN.md

File metadata and controls

227 lines (183 loc) · 7.52 KB

xDS 支持

English | 中文

xDS 是一类发现服务 API 的总称，数据面可以利用 xDS API 来完成配置信息的动态发现，包含LDS、RDS、 CDS、EDS 等。

Kitex 通过外部扩展 kitex-contrib/xds 的形式对 xDS API 进行了支持，可通过代码配置开启 xDS 模块，让Kitex 服务以 Proxyless 的模式运行，被服务网格统一纳管。具体的设计方案参见 proposal。

已支持的功能

  • 服务发现
  • 服务路由：当前仅支持 header 与 method 的精确匹配。
    • HTTP route configuration: 通过 VirtualService 进行配置
      • 由于 Istio 对 thrift 协议的支持有限，并且大多数用户都熟悉 VirtualService 的配置，所以我们在该配置建立 HTTP 到 Thrift 的映射，以定义路由策略。
    • ThriftProxy: 通过 EnvoyFilter 进行配置。
  • 超时配置:
    • HTTP route configuration 内包含的配置，同样通过 VirtualService 来配置。

开启方式

开启的步骤分为两个部分：1. xDS 模块的初始化和 2. Kitex Client/Server 的 Option 配置。

xDS 模块

调用 xds.Init() 便可开启对 xDS 模块的初始化，其中包括 xdsResourceManager ，负责 xDS 资源的管理，xdsClient，负责与控制面进行交互。

Bootstrap

xdsClient 负责与控制面（例如 Istio）交互，以获得所需的 xDS 资源。在初始化时，需要读取环境变量用于构建 node 标识。所以，需要在K8S 的容器配置文件 spec.containers.env 部分加入以下几个环境变量。

  • POD_NAMESPACE: 当前 pod 所在的 namespace。
  • POD_NAME: pod 名。
  • INSTANCE_IP: pod 的 ip。

在需要使用 xDS 功能的容器配置中加入以下定义即可：

- name: POD_NAMESPACE
valueFrom:
  fieldRef:
    fieldPath: metadata.namespace
- name: POD_NAME
valueFrom:
  fieldRef:
    fieldPath: metadata.name
- name: INSTANCE_IP
valueFrom:
  fieldRef:
    fieldPath: status.podIP

Kitex 客户端

目前，我们仅在 Kitex 客户端提供 xDS 的支持。 想要使用支持 xds 的 Kitex 客户端，请在构造 Kitex Client 时将 destService 指定为目标服务的 URL，并添加一个选项 WithXDSSuite。

  • 构造一个 xds.ClientSuite，需要包含用于服务路由的RouteMiddleware中间件和用于服务发现的 Resolver。将该 ClientSuite 传入WithXDSSuite option 中.
// import "github.com/cloudwego/kitex/pkg/xds"

client.WithXDSSuite(xds.ClientSuite{
	RouterMiddleware: xdssuite.NewXDSRouterMiddleware(),
	Resolver:         xdssuite.NewXDSResolver(),
}),
  • 目标服务的 URL 格式应遵循 Kubernetes 中的格式：
<service-name>.<namespace>.svc.cluster.local:<service-port>

基于 tag 匹配的路由匹配

我们可以通过 Istio 中的 VirtualService 来定义流量路由配置。

下面的例子表示 header 内包含 {"stage":"canary"} 的 tag 时，则将请求路由到 kitex-server 的 v1 子集群。

apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: kitex-server
spec:
  hosts:
    - kitex-server
  http:
  - name: "route-based-on-tags"
    match:
      - headers:
          stage:
            exact: "canary"
    route:
    - destination:
        host: kitex-server
        subset: v1
      weight: 100
    timeout: 0.5s

为了匹配 VirtualService 中定义的规则，我们需要指定流量的标签，这些标签将用于匹配规则。

比如：将 key 和 value 设置为“stage”和“canary”，以匹配 VirtualService 中定义的上述规则。

  • 我们可以先定义一个元信息提取方法，并通过 xdssuite.WithRouterMetaExtractor 传入到 RouterMiddleware 中。
    • 注意：若未配置 RouteMetaExtractor，默认会使用 metainfo.GetAllValues 来获取。
var (
	routeKey   = "stage"
	routeValue = "canary"
)

func routeByStage(ctx context.Context) map[string]string {
	if v, ok := metainfo.GetValue(ctx, routeKey); ok {
		return map[string]string{
			routeKey: v,
		}
	}
	return nil
}

// add the option
client.WithXDSSuite(xds2.ClientSuite{
	RouterMiddleware: xdssuite.NewXDSRouterMiddleware(
		// use this option to specify the meta extractor
		xdssuite.WithRouterMetaExtractor(routeByStage),
	),
	Resolver: xdssuite.NewXDSResolver(),
}),
  • 在调用时设置流量的元信息（需与元信息提取方法对应）。这里，我们使用metainfo.WithValue 来指定流量的标签。在路由匹配时，会提取元信息进行匹配。
ctx := metainfo.WithValue(context.Background(), routeKey, routeValue)

基于 method 的路由匹配

同上，利用 Istio 中的 VirtualService 来定义流量路由配置。

下面的例子表示，对于 method 等于 SayHello 的请求，路由到 kitex-server 的 v1 子集群。 需要注意的是，在定义规则时需要包含 package name 和 service name，对应 thrift idl 内的 namespace 和 service。

  • uri: /${PackageName}.${ServiceName}/${MethodName}
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: kitex-server
spec:
  hosts:
    - kitex-server
  http:
  - name: "route-based-on-path"
    match:
      - uri:
          # /${PackageName}.${ServiceName}/${MethodName}
          exact: /proxyless.GreetService/SayHello
    route:
    - destination:
        host: kitex-server
        subset: v2
      weight: 100
    timeout: 0.5s

示例

完整的客户端用法如下:

import (
	"github.com/cloudwego/kitex/client"
	xds2 "github.com/cloudwego/kitex/pkg/xds"
	"github.com/kitex-contrib/xds"
	"github.com/kitex-contrib/xds/xdssuite"
	"github.com/cloudwego/kitex-proxyless-test/service/codec/thrift/kitex_gen/proxyless/greetservice"
)

func main() {
	// initialize xds module
	err := xds.Init()
	if err != nil {
		return
	}
	
	// initialize the client
	cli, err := greetservice.NewClient(
		destService,
		client.WithXDSSuite(xds2.ClientSuite{
			RouterMiddleware: xdssuite.NewXDSRouterMiddleware(),
			Resolver:         xdssuite.NewXDSResolver(),
		}),
	)
	
	req := &proxyless.HelloRequest{Message: "Hello!"}
	resp, err := c.cli.SayHello1(
		ctx, 
		req, 
	) 
}

更详细的例子可以参考该仓库：kitex-proxyless-example.

当前版本的不足

mTLS

目前不支持 mTLS。 请通过配置 PeerAuthentication 以禁用 mTLS。

apiVersion: "security.istio.io/v1beta1"
kind: "PeerAuthentication"
metadata:
  name: "default"
  namespace: {your_namespace}
spec:
  mtls:
    mode: DISABLE

有限的服务治理功能

当前版本仅支持客户端通过 xDS 进行服务发现、流量路由和超时配置。

xDS 所支持的其他服务治理功能，包括负载平衡、速率限制和重试等，将在未来补齐。

兼容性

此项目仅在 Istio1.13.3 下进行测试。

maintained by: ppzqh

依赖

Kitex >= v0.4.0