AliyunPipelineConfig参数说明_日志服务(SLS)-阿里云帮助中心

当您使用ClusterAliyunPipelineConfig创建日志采集配置时，需要通过一个结构化的YAML文件定义采集规则。本文介绍该YAML文件的整体结构及各字段的含义。

工作原理

创建CR资源：用户通过 kubectl 提交ClusterAliyunPipelineConfig YAML 文件，定义采集规则。
控制器监听变化：loongcollector-operator 持续监听集群中CR资源的变更。
同步配置：当检测到 CR 变化时，operator 将其转换为具体配置，并提交到指定Project。
采集器拉取最新配置：loongcollector-ds定时向日志服务发送心跳获取配置更新，拉取最新的采集配置并热加载。
开始采集与上报：loongcollector-ds 根据最新配置采集日志，并通过配置的接入点发送到 SLS。

基础字段

定义API版本与资源类型，所有配置都必须以此开头：

apiVersion: telemetry.alibabacloud.com/v1alpha1
kind: ClusterAliyunPipelineConfig

结构示例

apiVersion: telemetry.alibabacloud.com/v1alpha1 # 使用默认值，无需修改。
kind: ClusterAliyunPipelineConfig               # 使用默认值，无需修改。
metadata:
  name: test-config                             # 设置资源名，在当前Kubernetes集群内唯一。
spec:
  project:                                      # 设置目标Project名称。
    name: k8s-your-project                      
  config:                                       # 设置Logtail采集配置。
    inputs:                                     # 设置Logtail采集配置里的输入插件
      ...
    flushers:                                   # 设置Logtail采集配置里的输出插件
      ...

核心参数说明

metadata.name

采集配置名称，必填，在Project内唯一，创建后不可修改。

命名规则：

只能包含：小写字母、数字、-和_。
必须以小写字母或数字开头和结尾。
长度限制：2~128字符。

示例：

metadata:
  name: nginx-access-log

spec.projecct

目标Project信息。

说明

project字段在CR创建后不允许更改，如需切换project请创建新的CR。

参数	数据类型	是否必填	说明
name	string	是	目标 Project 的名称，若不存在会自动创建。
description	string	否	Project 的描述（仅在创建时生效）。
endpoint	string	否	Project所在地域的服务入口，默认值为集群所在的地域。该参数仅控制采集配置的创建地域，不控制采集器数据投递目标。如需跨地域采集，请配置config_server_address和data_server_list。
uid	string	否	目标Project所属的阿里云主账号的uid。默认值为当前集群所属的主账号uid。该参数仅控制采集配置创建到哪个账号下。如需跨账号采集日志，请同步配置`alibaba-log-controller` 组件的环境变量： `ALICLOUD_LOG_ACCOUNT_INFOS={"<uid>":{"accessKeyID":"<your_access_key_id>","accessKeySecret":"<your_access_key_secret>"}}`。

spec.config

采集配置主体，定义具体的输入、处理、输出插件。

子字段	类型	是否必填	说明
`sample`	string	否	日志样例，支持多条日志，总长度不超过1500字节。
`global`	object	否	全局配置。
`inputs`	object列表	是	输入插件列表，目前只允许配置 1 个输入插件。
`processors`	object列表	否	处理插件列表：原生插件扩展插件
`flushers`	object列表	是	输出插件列表，目前只允许存在 1 个 `flusher_sls`插件。

spec.logstores

可选配置，用于声明需要创建的Logstore，其作用如下：

仅在创建时生效：所有参数（除 name 外）都只在 Logstore 首次创建时有效。如果 Logstore 已存在，这些配置将被忽略，不会影响已有 Logstore 的属性。
不决定数据发送目标：此列表不控制日志发送到哪个 Logstore。真正的发送目标由 config.flushers 中的输出插件（如 flusher_sls）决定。
可选配置：如果目标 Logstore 已经存在，可以不用在此处定义。
仅支持增删，不支持修改：可以向列表中添加新的 Logstore 或删除某项，但无法通过更新此配置来修改已创建的 Logstore 属性（如 TTL、Shard 数量等）。如需修改，请通过控制台或 API 操作。

参数	数据类型	是否必填	说明
name	string	是	需要创建的Logstore名称。
queryMode	string	否	Logstore类型。默认值为`standard`，可选值： `query`：查询型Logstore。 `standard`：标准型Logstore。
ttl	int	否	数据保留天数（1~3650）默认30，3650表示永久。
hotTtl	int	否	热数据存储时间（以天为单位）。默认0，需要小于ttl且大于等于 7。
shardCount	int	否	Shard数量。默认值为2，取值范围为1~100。
maxSplitShard	int	否	最大自动分裂Shard数量。默认值为64，取值范围为1~256。
autoSplit	bool	否	是否开启自动分裂Shard。默认值为true。
telemetryType	string	否	可观测数据类型。默认值为None，可选值： `None`：日志数据。 `Metrics`：时序数据。
appendMeta	bool	否	是否记录外网IP地址和日志接收时间。默认值为true。 `true`：开启记录外网 IP 和日志接收时间功能，开启后日志服务自动把日志来源设备的公网 IP 地址和日志到达服务端的时间添加到日志的 Tag 字段中。 `false`：不开启记录外网 IP 和日志接收时间功能。
enableTracking	bool	否	是否启用WebTracking功能。默认值为false。
encryptConf	object	否	加密配置数据结构，包含参数`enable`、 `encrypt_type`、 `user_cmk_info`。默认值为空。
meteringMode	string	否	计费模式。更多信息，请参见管理Logstore。默认值为空，可选值： `ChargeByFunction`：按功能计费 `ChargeByDataIngest`：按写入量计费。说明如果Logstore的queryMode为query，只支持按功能计费。如果账号未开通写入量计费，无法配置为ChargeByDataIngest。

spec.machineGroups

指定哪些机器组可以应用此采集配置。

默认行为：安装LoongCollector时，系统会自动创建的名为k8s-group-${clusterId}的机器组。若未显式设置 machineGroups，将默认关联该机器组。
同步机制：loongcollector-operator 会确保采集配置所关联的机器组严格等于 machineGroups 中定义的列表。任何不在该列表中的机器组都会被自动解除关联。
自动创建支持：如果指定的机器组不存在，系统会自动创建同名的标识型机器组，并将其与当前采集配置绑定。

参数	数据类型	是否必填	说明
name	string	否	要关联的机器组名称。

spec.enableUpgradeOverride

可选，是否允许覆盖旧配置。用于解决新旧版采集配置之间的冲突问题，默认为false。

true：loongcollector-operator会对已有的AliyunLogConfig定义的采集配置进行覆盖升级。
false：采集配置存在冲突，AliyunPipelineConfig应用失败。

使用场景：当集群中存在AliyunLogConfig定义的采集配置、且与当前的AliyunPipelineConfig指向同一个采集配置时，就会发生冲突。

同一个采集配置的定义：

Project 相同
- AliyunLogConfig：使用集群默认 Project 或 spec.project
- AliyunPipelineConfig：使用 spec.project.name
采集配置名称相同
- AliyunLogConfig：spec.logtailConfig.configName
- AliyunPipelineConfig：metadata.name

覆盖升级过程：

新配置生效
ClusterAliyunPipelineConfig 被应用，更新采集配置。
旧配置清理
如果更新成功，控制器会自动删除集群中对应的 AliyunLogConfig 资源。
完成迁移
完成从旧方式到新方式的平滑过渡。