[Proposal] 支持集成外部私有仓库插件编译构建方案

[snakorse]

需求

部分插件，由于并不普适、或与内部服务功能绑定、或商业安全要求，不能贡献到开源社区
这部分私有插件代码，需要保持在私有仓库中，因此，需要设计一种产物构建机制，能够合并官方仓库、私有仓库的插件，一起构建出包

核心目标

• 能够将私有插件灵活注册进ilogtail
• 可以支持一次注册添加多个插件，即可基于repo注册
• 复用ilogtail整体构建流程，生成代码不污染代码仓库

整体思路

• 将pipeline涉及到的插件接口、数据模型，迁移到 ilogtail/pkg这个module下，pkg module 可被custom repo单独import

• custom repo 中，通过 init 函数，主动调用pipeline的注册插件函数，进行注册
  

  

• ilogtail主仓，根据配置文件：

  • 向 plugins/all 目录下生成添加 *.external_plugins.go文件，在其中自动 import 自定义插件
  • 之后可以走正常的构建流程进行构建

• *.external_plugins.go 加入gitignore文件，避免提交到主仓库

详细设计

配置定义

plugins:    // 需要注册的plugins，按适用的系统分类
common:
    - gomod: code.private.org/private/custom_plugins v1.0.0  // 必须，插件module
      import: code.private.org/private/custom_plugins        // 可选，代码中import的package路径
      path: ../custom_plugins                            // 可选，replace 本地路径，用于调试
windows:
linux:

project:
replaces:       // 可选，array，用于解决多个插件module之间依赖冲突时的问题
go_envs:        // 可选，map，插件的repo是私有的时候，可以添加如GOPRIVATE环境等设置
  GOPRIVATE: *.code.org
git_configs:    // 可选，map，私有插件repo可能需要认证，可以通过设置git url insteadof调整
  url.https://user:[email protected]/user/.insteadof: https://github.com/user/

代码生成

1. 配置文件的指定方式
   1. make指令时，设置 EXTERNAL_PLUGINS_CONFIG_FILE 环境变量
   2. 默认会检测根目录的 external_plugins.yml 文件
2. 增加 tools/builder package，其代码中主要完成如下逻辑：
   1. 读取插件配置文件（支持远程地址，通过http get访问）
   2. 生成 *.exteral_config.go 文件到plugins/all目录下
   1. 文件的内容主要为一句 import _ "github.com/name/plugins"
      3. 执行命令行指令 go env -w xxx，应用配置文件中的go_envs设置(如果有)
      4. 执行命令行指令 git config xxx xxx，应用配置文件中的git_configs设置(如果有)
3. Makefile 增加 make add_external_plugins 命令，执行如下操作
   - 其主要操作为：构造参数，执行 scripts/gen_external_plugins.sh，其中会进一步执行 go run tools/builder 启动程序生成代码

# file: gen_external_plugins.sh

CONFIG_FILE=${1:-${EXTERNAL_PLUGINS_CONFIG_FILE:-external_plugins.yml}}
MOD_FILE=${2:-${GO_MOD_FILE:-go.mod}}
ROOT_DIR=${3:-$(cd $(dirname "${BASH_SOURCE[0]}") && cd .. && pwd)}

if [ "$CONFIG_FILE" == "off" ]; then
echo "process disabled, nothing to do"
return
fi

rm -rf $ROOT_DIR/plugins/all/*.external_plugins.go

go run -mod=mod "$ROOT_DIR/tools/builder" -root-dir="$ROOT_DIR" -config="$CONFIG_FILE" -modfile="$MOD_FILE" && \
echo "generating external plugins finished successfully"

4. 在scripts/plugins_build.sh中，也加入对scripts/gen_external_plugins.sh的调用，保证当执行其他make指令，如 make plugin_local、make dist时，也能自动执行external_plugins插件构建

# file: plugin_build.sh

# make external plugins stuffs
"$CURRDIR/gen_external_plugins.sh" "$EXTERNAL_PLUGINS_CONFIG_FILE" "$GO_MOD_FILE"

go build -mod="$MOD" -modfile="$GO_MOD_FILE" -buildmode="$BUILDMODE" -ldflags="$LDFLAGS" -o "$ROOTDIR/$OUT_DIR/${NAME}" "$ROOTDIR"/plugin_main

避免污染主仓

• 主要通过将相关文件添加到 .gitignore，来避免污染主仓

• 对于 go.mod go.mod.sum的变动，有两种方式：

  1. 提交代码时，执行 make clean，清除自动生成的插件代码，同时自动清除go.mod中自动生成的代码
  2. 或者 指定 GO_MOD_FILE 变量，这会生成一个新的gomod file，并基于这个文件做构建，其原理是：
  • 在go build 命令上加上 -modfile $GO_MOD_FILE
  • GO_MOD_FILE 变量默认是 go.mod，保证不指定时可以正常构建
  • .go.mod 、.go.mod.sum 加入 .gitignore

  GO_MOD_FILE=tmp.go.mod make dist
  

私有仓库鉴权

问题

当执行 make dist等命令通过docker构建时，docker内默认并没有配置好的私有仓库的认证信息(ssh key or pwd)

方案一

通过 git config url.xxx.insteadof 指令，在url上添加 user/pwd

https://go.dev/doc/faq#git_https

git config "url.https://user:[email protected]/user/.insteadof" "https://github.com/user/"

操作方式：

• 可以在仓库手动执行命令
• 也可以配置在 external_plugins.yml的git_configs节，自动执行

方案二

借助docker BuildKit，使用 host 上的 ssh agent保存的ssh keys
要求：

• 需要修改 docker build指令，加上 DOCKER_BUILDKIT=1

• 如果git仓库的 [email protected]=https://github.com的配置是在host的global配置，需要添加到仓库本地配置中

  • 方案：
  • 在 scripts/gen_build_scripts.sh 中，导出host的 git configs，最终执行生成脚本时，将可以导入到docker

• host上的 GOPRIVATE 配置，也需要导入到docker中

  • 方案：
  • 在 scripts/gen_build_scripts.sh 中，导出host的GOPRIVATE，最终执行生成脚本时，将可以导入到docker
    优势：
  • 这样可以实现零手动配置，就能正常的进行docker中私有module repo的拉取构建

  向前兼容性

  比较大的代码变动是，将 Aggregator、Flusher等 interface定义，迁移到了 pkg module下，使pkg作为一个可被外部私有仓库单独依赖的module
  这个改动会影响到现有插件的代码，主要是插件中import的package name的变动：ilogtail -> pkg/pipeline

• 针对ilogtail仓库内置的插件，改动是一次性的，问题不大

• 但是否存在其他外部的依赖方式，需要考虑其兼容性的？

  • 考虑到当前v1 v2 模型，分别定义在 ilogtail、pkg package下，有必要借此机会做个统一

如果要兼容如何做？

• 可使用 go type alias 定义

  package ilogtail
  
  import github.com/alibaba/ilogtail/pkg/pipeline
  
  type Flusher = pipeline.Flusher

[liuhaoyang]

ilogtail 主仓库内的 plugins 是否也做成一个独立的 module，加载所有插件的入口从 all 移动到 pluginmanager 里面？

[liuhaoyang]

对于主仓库内的插件是否默认加载的想法

1. 默认全部加载，好处是ilogtail在大多数场景下可以开箱即用
2. 可以通过选项全部不加载，在external_plugins.yml里定义需要加载的插件，可以有效的减少release产物的大小

[yyuuttaaoo]

我觉得只要能通过plugins.yml控制即可，默认可以是全部都在的，降低使用门槛，对于有大小要求的用户，删掉一些项目，就可以方便裁剪。

[liuhaoyang]

整理一下

1. ilogtail 主仓库添加 plugins.yml 文件，加入版本控制，主仓库的插件都加到这个文件里面进行注册，不再维护 all.go
2. 同时支持 external_plugins.yml 来加载外部仓库的插件，这个和之前提案描述的一致
3. 编译脚本支持传递多个 *_plugins.yml ，默认传递 plugins.yml 来生成内置插件的 all.go 和 external_all.go 文件

这样的效果是

1. 默认加载主仓库的所有插件
2. 如果要多加载的插件做裁剪，在 external_plugins.yml 里面编写需要加载的插件，编译参数不传递 plugins.yml 即可

cc @yyuuttaaoo @snakorse