教程:如何在本地开发和调试 Higress Pilot_Blog-HigressOfficial Website

教程:如何在本地开发和调试 Higress Pilot

CH3CHO

Release Time 2024-03-16


背景说明

前面 SJC 在这篇博客中介绍了如何在本地开发和调试 Higress Controller。而 Higress 控制面除了 Controller 之外还有一个组件,那就是 Pilot。本文就将介绍如何在本地开发和调试 Higress Pilot。

环境准备

步骤一:克隆代码仓库

Pilot 的代码目前是以 Istio 上游仓库 submodule 加补丁文件的形式存在于 Higress 的主仓库中的,所以直接克隆 Higress 的代码主仓库 https://github.com/alibaba/higress 即可。

步骤二:准备项目代码

Higress Pilot 是在 Istio Pilot 的基础上,基于 Higress 自身的功能需求进行了二次开发而构建而成的,所以我们这里需要下载上游代码仓库并应用现有的补丁。我们只需要执行下面这条命令:

Terminal window
make prebuild

Windows 用户注意了!

如果你是在 Windows 上进行开发,并且执行 make 命令有困难的话,不要怕,我们也有办法。因为整个 prebuild 其实也只做了两件事情。

第一件事情是初始化所有的上游子模块,只需要执行这样一条命令:

Terminal window
git submodule update --init

第二件事情是初始化开发目录。这一步骤执行的就是 tools/hack/prebuild.sh。大家可以直接在 Cygwin 或者 Git Bash 等类 Linux 终端下执行这个脚本文件。

如果在应用补丁的时候出现了和换行符有关的报错,那么可以编辑 prebuild.sh,给两处 patch 命令增加 --binary 参数即可。

img.png

步骤三:安装 Higress

既然只是调试 pilot,那么其他组件还是要复用现有 Higress 集群里的。所以我们需要在本地配置一个 Higress 集群。大家可以参考这篇文档:链接

开发与调试

本地开发

本地开发推荐使用 IDE JetBrains GoLand。我们直接在 GoLand 中打开 external/istio 目录,正常进行开发即可。

img.png

调试运行

环境准备

第一步:提取配置文件

在本地任意一个位置创建一个目录,然后在该目录下执行以下命令,生成配置文件:

Terminal window
kubectl get configmap higress-config -n higress-system -o=jsonpath='{.data.mesh}' > ./mesh
kubectl get configmap higress-config -n higress-system -o=jsonpath='{.data.meshNetworks}' > ./meshNetworks

第二步:转发 controller 端口

执行以下命令,将 controller 的 xDS 服务端口转发至本地:

Terminal window
kubectl port-forward deployment/higress-controller -n higress-system 15051

代码调整

如果要调试与 TLS 证书下发的相关功能,则需要在 pilot/pkg/xds/ads.goinitConnection 函数中添加代码,绕过证书下发过程的认证要求。代码修改方法请参考下方示例。

if features.EnableXDSIdentityCheck && con.Identities != nil {
// TODO: allow locking down, rejecting unauthenticated requests.
id, err := checkConnectionIdentity(con)
if err != nil {
log.Warnf("Unauthorized XDS: %v with identity %v: %v", con.PeerAddr, con.Identities, err)
return status.Newf(codes.PermissionDenied, "authorization failed: %v", err).Err()
}
con.proxy.VerifiedIdentity = id
}
// Start - Auth bypassing for local debug
con.proxy.VerifiedIdentity = &spiffe.Identity{
TrustDomain: "cluster.local",
Namespace: "higress-system",
ServiceAccount: "higress-gateway",
}
// End - Auth bypassing for local debug

运行配置

配置一:环境变量

Terminal window
CUSTOM_CA_CERT_NAME=higress-ca-root-cert;
JWT_POLICY=none;
PILOT_ENABLE_CROSS_CLUSTER_WORKLOAD_ENTRY=false;
PILOT_ENABLE_GATEWAY_API=true;
PILOT_ENABLE_GATEWAY_API_DEPLOYMENT_CONTROLLER=false;
PILOT_ENABLE_GATEWAY_API_STATUS=false;
PILOT_ENABLE_METADATA_EXCHANGE=false;
PILOT_SCOPE_GATEWAY_TO_NAMESPACE=true;
POD_NAME=higress-controller;
POD_NAMESPACE=higress-system;
REVISION=default;
VALIDATION_ENABLED=false

配置二:命令行参数

Terminal window
discovery --monitoringAddr=:15014 --log_output_level=default:info --domain cluster.local --keepaliveMaxServerConnectionAge 30m --meshConfig ${configDir}/mesh --networksConfig ${configDir}/meshNetworks

注意:其中的 ${configDir} 为在环境准备一步创建的配置目录。

启动调试

在完成以上工作之后,我们就可以启动 Pilot 了。它的 main 函数定义在 pilot/cmd/pilot-discovery/main.go 文件中。

img.png

网关对接

如果想要验证 pilot 下发配置到 gateway 的功能,我们需要修改 gateway 的配置,使之连接到处于开发状态的 pilot 实例。

第一步:修改 higress-config ConfigMap

Terminal window
kubectl edit configmap higress-config -n higress-system

修改两个地方:

  1. discoveryAddress 修改为本机IP:15010
    注意:此处的本机 IP 不可以使用 127.0.0.1 等 loopback IP。需要使用本机有线或无线网卡的 IP。
  2. discoveryAddress 下面添加一个新属性:controlPlaneAuthPolicy: NONE

修改后配置示例:

img.png

第二步:重启 Higress Gateway

Terminal window
kubectl rollout restart deployment higress-gateway -n higress-system

重启后我们可以在 pilot 的控制台输出中看到 gateway 连接上来的并获取配置的日志。

img.png

总结

本地调试和测试是开发过程中必不可少的环节。通过本文的介绍,希望大家可以更加方便的对 pilot 进行本地调试和e2e测试,提高开发效率。同时也希望能够有越来越多的开发者加入到 Higress 研发队伍中,为产品的升级迭代贡献一份力量。

欢迎参与阿里开源贡献👏