服务端管控协议共建，欢迎参与讨论交流

[messixukejia]

Agent管控协议 v1

syntax = "proto3";
package configserver.proto;
option go_package = ".;configserver_proto";

// 定义 Config 的类别

enum ConfigType {
    PIPELINE_CONFIG_TYPE = 0;   // 采集PIPIELINE配置
    AGENT_CONFIG_TYPE = 1;      // Agent运行配置
}

// 定义 Config 更新状态

enum CheckStatus {
    NEW = 0;        // 新增
    DELETED = 1;    // 删除
    MODIFIED = 2;   // 修改
}

// 定义响应码
enum RespCode {
    ACCEPT = 0;                 // 请求成功
    INVALID_PARAMETER = 1;      // 无效的参数
    INTERNAL_SERVER_ERROR = 2;  // 内部服务调用错误
}

// 定义请求时携带的 Config 信息
message ConfigInfo {
    ConfigType type = 1;    // 必选，Config 类型
    string name = 2;        // 必选，Config 名（唯一标识）
    int64 version = 3;      // 必选，Config 版本号
    string context = 4;     // Config 上下文附加信息描述
}

// 定义检查 Config 更新状态的结果
message ConfigCheckResult {
    ConfigType type = 1;                     // 必选，Config 类型
    string name = 2;                            // 必选，Config 名（唯一标识）
    int64 old_version = 3;                   // 必选，Config 当前版本号
    int64 new_version = 4;                 // 必选，Config 最新版本号
    string context = 5;                         // Config 上下文附加信息描述
    CheckStatus check_status = 6;   // 必选，Config 检查状态    
}

// 定义 Config 的完整信息
message ConfigDetail {
    ConfigType type = 1;    // 必选，Config 类型
    string name = 2;           // 必选，Config 名（唯一标识）
    int64 version = 3;         // 必选，Config 版本号
    string context = 4;       // Config 上下文附加信息描述
    string detail = 5;          // 必选，Config 详情
}

// 定义 Agent 的基本属性
message AgentAttributes {
    string version = 1;                  // Agent 版本
    string category = 2;                // Agent 类别（用于区分Agent运行配置）
    string ip = 3;                            // Agent ip
    string hostname = 4;              // Agent 主机名
    string region = 5;                    // Agent 所在区域
    string zone = 6;                       // Agent 所属可用区
    map<string, string> extras = 100;   // Agent 的其他信息
}

// 定义指令
message Command {
    string type = 1;                  // 必选，指令类型
    string name = 2;                // 必选，指令名
    string id = 3;                      // 必选，指令编号
    map<string, string> args = 4;   // 指令参数数组
}

// API: /Agent/HeartBeat/

// Agent 向 ConfigServer 发送心跳、获取配置更新信息并接收指令的请求
message HeartBeatRequest {
    string request_id = 1;                            // 必选，请求编号
    string agent_id = 2;                              // 必选，Agent 的唯一标识
    string agent_type = 3;                         // 必选，Agent 类型（iLogtail等）
    AgentAttributes attributes = 4;           // Agent 的基础信息
    repeat string tags =  5;                        // Agent 拥有的 tag
    string running_status = 6;                   // 必选，Agent 的运行状态
    int64 startup_time = 7;                        // 必选，Agent 的启动时间
    int32 interval = 8;                                  // Agent 的心跳间隔
    repeated ConfigInfo pipeline_configs = 9;   // Agent 当前拥有的采集配置信息
    repeated ConfigInfo agent_configs = 10;      // Agent 当前拥有的运行配置信息
}

// ConfigServer 对 Agent 心跳的响应
message HeartBeatResponse {
    string request_id = 1;                                  // 必选，请求编号
    RespCode code = 2;                                    // 必选，响应码
    string message = 3;                                    // 必选，响应信息

    repeated ConfigCheckResult pipeline_check_results = 4;  // Agent 的采集配置更新信息
    repeated ConfigCheckResult agent_check_results = 5;     // Agent 的运行配置更新信息
    repeated Command custom_commands = 6;                   // Agent 接收到的自定义指令
}

// API: /Agent/FetchPipelineConfig/
// Agent 向 ConfigServer 拉取采集配置的请求
message FetchPipelineConfigRequest {
    string request_id = 1;                  // 必选，请求编号
    string agent_id = 2;                    // 必选，Agent 的唯一标识
    repeated ConfigInfo req_configs = 3;    // Agent 需要获取完整信息的配置
}

// ConfigServer 对 Agent 拉取采集配置的响应
message FetchPipelineConfigResponse {
    string request_id = 1;                     // 必选，请求编号
    RespCode code = 2;                          // 必选，响应码
    string message = 3;                         // 必选，响应信息

    repeated ConfigDetail config_details = 4;   // Agent 请求的配置的完整信息
}

// API: /Agent/FetchAgentConfig/
// Agent 向 ConfigServer 拉取运行配置的请求
message FetchAgentConfigRequest {
    string request_id = 1;                  // 必选，请求编号
    string agent_id = 2;                    // 必选，Agent 的唯一标识
    AgentAttributes attributes = 3;         // 必选，Agent 的基础信息
    repeated ConfigInfo req_configs = 4;    // Agent 需要获取更新内容的配置信息
}

// ConfigServer 对 Agent 拉取运行配置的响应
message FetchAgentConfigResponse {
    string request_id = 1;                                    // 必选，请求编号
    RespCode code = 2;                                      // 必选，响应码
    string message = 3;                                       // 必选，响应信息
    repeated ConfigDetail config_details = 4;   // Agent 请求的配置的完整信息
}

[codingdancer]

有几个问题请问下：
1.这个是类似于配置中心么？
2.这个东西计划大概啥时候能出？

[Takuka0311]

1、ConfigServer是一个管控服务，包括管控工具和管控协议。ConfigServer的主要功能是对大量采集Agent进行统一的配置管理和运行状态监控。
2、ConfigServer目前正在开发中，近期会上线初版。若对管控有什么需要的功能或有什么建议，欢迎在这里提出来一起讨论。可以关注iogtail社区的开源双周会（昨天刚开展了一次活动），了解该功能及其他功能的最新进展

[yyuuttaaoo]

提议翻新ilogtail的管控协议至v2版本

背景

v1版本的管控协议提出后广受社区关注，在社区参考实现的ConfigServer基础上也多次有PR希望进行进一步改进。然而v1版本的管控协议存在一些问题。

1. 仅有协议字段定义，部分字段存在定义但未使用且无说明，缺少行为定义。导致各方对协议字段的理解不完全一致，对agent和server的行为预期也不完全一致。
2. 协议中心跳信息较为冗余，大规模使用对网络流量浪费不小，缺乏压缩手段。
3. 缺少端上配置的反馈机制，无法了解配置加载状态。
4. Agent与Server见的协商机制不太通用，仅有心跳间隔，且agent和server均没有实现。
5. server的AgentGroupTag和agent侧的tags类型不一致，使用上令人困惑。

v2协议

关于v2版本协议的讨论参见 #1491 ，结论见 #1491 (comment) ，此处不再重复，具体spec和proto定义见PR #1516 。

与V1版本相比

1. 所有proto中定义的字段均有说明，并约定了agent和server的预期行为。
2. 删除了不必要的字段和高度重复的结构，简化proto定义。
3. 具备心跳信息压缩能力，作为可选实现可减少网络开销。
4. 增加端上配置的反馈机制。
5. 增加capabilities和flags用户agent与server协商行为。
6. 统一tags为AgentGroupTag
7. 同时支持单次通信获取配置和通过多次网络请求分开拉取配置。
8. 部分字段类型改为bytes，允许非utf8编码文本或二进制串。

兼容性

由于v1版本中定义未使用的字段较多，加上tag的不一致问题导致

1. tag类型变化不可能保持兼容性
2. 沿用v1中的字段编号势必未使用的字段继续造成困扰

因此这里提出v2版本，放弃协议上与v1版本的兼容，但仍然保持agent仍可以被v1协议的ConfigServer管理一段时间。

后续兼容策略：

1. proto v2与v1在不同命名空间，故可以在1个binary中共存。
2. 当v2版本client和server都完成后，默认切换到v2，使用v1需打开兼容开关。
3. config server v1版本特性depreciated，在一年后彻底删除。

[nelsontang]

// 定义请求时携带的 Config 信息
message ConfigInfo {
ConfigType type = 1; // 必选，Config 类型
string name = 2; // 必选，Config 名（唯一标识）
int64 version = 3; // 必选，Config 版本号
string context = 4; // Config 上下文附加信息描述
}

建议增加 string md5 = 5;
agent启动时上报，内存为空，version字段都为0，可以从本地加载文件md5带上来，避免全量配置重新下发，减少configserver压力

[yyuuttaaoo]

启动的时候会把version带上来。version这个字段可以填写config的hash，这样也具备了md5的作用。这里没有用md5把算法也给定死了，只规定了-1和0的特殊含义，签名算法服务端可以任意选择。

[nelsontang]

message HeartBeatResponse {
string request_id = 1; // 必选，请求编号
RespCode code = 2; // 必选，响应码
string message = 3; // 必选，响应信息

repeated ConfigCheckResult pipeline_check_results = 4;  // Agent 的采集配置更新信息
repeated ConfigCheckResult agent_check_results = 5;     // Agent 的运行配置更新信息
repeated Command custom_commands = 6;                   // Agent 接收到的自定义指令

}

这里Agent 接收到的自定义指令 感觉也可以去掉，命令下发是通过input_command插件，可以作为pipeline配置下发

[yyuuttaaoo]

有点区别的是，这里的command是指一次性的任务，比如补录历史数据，而input_command仍然是常驻任务，定制执行。所以这里的command带有expire_time，超时后，不再关注其状态。