一、既然是一文玩转,自然要讲些背景
**1.1. 什么是 iLogtail 采集配置**
长话短说:
- SLS:阿里云日志服务,一站式提供数据采集、加工、查询与分析、可视化、告警、消费与投递等功能,全面提升您在研发、运维、运营、安全等场景的数字化能力。
- iLogtail:SLS推出的一款可观测数据采集器,拥有轻量级、高性能、自动化配置等特性,可以将它部署于物理机,虚拟机,Kubernetes等多种环境中来采集可观测数据,例如logs、traces和metrics。
- iLogtail采集配置:iLogtail采集数据的流水线是通过采集配置定义的,一个采集配置里包含数据的输入、处理、输出等信息。
在SLS控制台,一个简单的采集配置长这样:

1.2. 为什么我们需要CRD来管理采集配置
通过控制台管理采集配置,终究是不够自动化。
试想:若是每次发布,都需要手动上控制台修改一批采集配置,岂不是太麻烦了?更何况可能改错。
在云原生时代,我们需要更方便的方式,来管理采集配置。这种方式,它最好是可灵活扩展的,不与业务耦合;它最好是可以集中管理和监控的,来简化运维的操作;它最好是方便集成与自动化部署的,来降低部署的难度……
基于以上需求,CRD就这样进入了我们的视线。
在 Kubernetes 环境中,CRD 是一种扩展 K8s API 的方法,允许用户定义和管理自己的资源。使用 CRD,可以将采集配置作为 Kubernetes 对象进行管理,使其与其他 Kubernetes 资源(如 Pod、Service、Deployment)保持一致。
看着真不错,那就整一个CRD吧!
**1.3. 你说得对,但是我们不是已经有一种 CRD 了吗?**
是的,我们有一个CRD——AliyunLogConfig。
**1.3.1.** 聊聊 AliyunLogConfig
让我们先看一个简单的AliyunLogConfig配置示例:
apiVersion: log.alibabacloud.com/v1alpha1
kind: AliyunLogConfig
metadata:
设置资源名,在当前Kubernetes集群内唯一。
name: example-k8s-file
namespace: kube-system
spec:
【可选】目标project
project: k8s-log-xxxx
设置Logstore名称。如果您所指定的Logstore不存在,日志服务会自动创建。
logstore: k8s-file
【可选】Logstore shard数
shardCount: 10
【可选】Logstore存储时间
lifeCycle: 30
【可选】Logstore热存储时间
logstoreHotTTL: 7
设置iLogtail采集配置。
logtailConfig:
设置采集的数据源类型。采集文本日志时,需设置为file。
inputType: file
设置iLogtail采集配置的名称,必须与资源名(metadata.name)相同。
configName: example-k8s-file
inputDetail:
指定通过极简模式采集文本日志。
logType: common_reg_log
设置日志文件所在路径。
logPath: /data/logs/app_1
设置日志文件的名称。支持通配符星号(\*)和半角问号(?),例如log\_\*.log。
filePattern: test.LOG
采集容器的文本日志时,需设置dockerFile为true。
dockerFile: true
设置容器过滤条件。
advanced:
k8s:
K8sNamespaceRegex: ^(default)$
K8sPodRegex: '^(demo-0.*)$'
K8sContainerRegex: ^(demo)$
IncludeK8sLabel:
job-name: "^(demo.*)$"
AliyunLogConfig内置了默认Project,使用时,只需要指定目标Logstore,并编辑采集配置,就可以实现数据接入。后来,随着AliyunLogConfig不断发展,还新增了一些新功能,比如支持定义Logstore的创建参数、支持指定目标project、支持简单的跨地域、跨账号能力等等。
AliyunLogConfig会把CR的处理结果反馈到Status字段中,内有statusCode与statu两个字段。
status:
statusCode: 200
status: OK
总的来说,AliyunLogConfig作为管理采集配置的CRD,可以满足基本的功能需求,且可以支持一些复杂场景。
**1.3.2.** 英雄迟暮,AliyunLogConfig 的局限性
随着SLS不断发展,AliyunLogConfig的局限性也不断凸显出来
- 结构混乱
- SLS资源描述不清晰,CRD管理的SLS资源有:project,logstore,machingroup,config,这些都平铺在spec中
- 字段值含义不清:例如Logstore的属性,有的有logstore前缀(logstoreHotTTL),有的没有前缀(shardCount),而且这些参数名与API不一致(lifeCycle与ttl)
- 功能不完善
- 资源的create,update,delete应该明确统一,project,logstore相关的配置只有首次创建生效,不允许更新,config可以更新
- 多个CR指向一个配置,会出现冲突覆盖,尤其是跨集群场景,很容易出现该问题。
二、全体目光向我看齐,全新 CRD 来了!
我们全新的CRD——AliyunPipelineConfig,来了!
相较于AliyunLogConfig,AliyunPipelineConfig在配置格式、行为逻辑上做了很大改进,主打的就是灵活、简单、稳定。
| 类型 | AliyunPipelineConfig(全新升级) | AliyunLogConfig |
|---|---|---|
| ApiGroup | telemetry.alibabacloud.com/v1alpha1 | log.alibabacloud.com/v1alpha1 |
| CRD资源名 | ClusterAliyunPipelineConfig | AliyunLogConfig |
| 作用域 | 集群 | 默认集群 |
| 采集配置格式 | 基本等价于日志服务API中的 “[LogtailPipelineConfig](https://help.aliyun.com/zh/sls/developer-reference/api-sls-2020-12-30-struct-logtailpipelineconfig)” | 基本等价于日志服务API中的 “[LogtailConfig](https://help.aliyun.com/zh/sls/developer-reference/api-sls-2020-12-30-struct-logtailconfig)” |
| 跨地域能力 | 支持 | 支持 |
| 跨账号能力 | 支持 | 支持 |
| webhook校验参数 | 支持 | 不支持 |
| 配置冲突检测 | 支持 | 不支持 |
| 配置难度 | 较低 | 较高 |
| 配置可观测性 | Status包含错误详情、更新时间、上次应用成功配置、上次应用成功时间等信息 | Status包含错误码与错误信息 |
**2.1. 你是不知道 AliyunPipelineConfig 的配置有多简洁**
AliyunPipelineConfig的整体结构如下:
apiVersion: telemetry.alibabacloud.com/v1alpha1
kind: ClusterAliyunPipelineConfig
metadata:
name: test-config
spec:
project: # 目标project
name: k8s-your-project # project名
uid: 11111 #【选填】账号
endpoint: cn-hangzhou-intranet.log.aliyuncs.com # 【选填】endpoint
logstores: #【选填】需要创建的 logstore 列表,与 CreateLogstore 接口基本一致
- name: your-logstore # logstore名
ttl: 30 #【选填】数据保存时间
shardCount: 10 #【选填】shard 数
... #【选填】其他 Logstore 参数
machineGroups: #【选填】需要与采集配置关联的机器组列表 - name: machine-group-1 # 机器组名
- name: machine-group-2 # 机器组名
config: # 采集配置,格式与 CreateLogtailPipelineConfig 接口基本一致
sample: #【选填】日志样例
global: #【选填】全局配置
inputs: # 输入插件,必须有且只有一个
...
processors: #【选填】处理插件,可以自由组合
...
aggregators: #【选填】聚合插件
...
flushers: # 输出插件,只能有一个flusher_sls
...
enableUpgradeOverride: false #【选填】用于升级 AliyunLogConfig
AliyunPipelineConfig的配置有几个特点:
- 结构清晰
- 按sls资源类型分类,有project、logstore、machineGroup、config
- 必填项少
- 必填项只有project.name、config.inputs和config.flushers,其他字段都可以灵活填写
- 贴合API
- logstore、config的数据结构、参数命名与SLS API一致
下面,我们详细讲讲spec字段里的字段。
**2.1.1. project字段详解与配置指南**
project字段列表如下:
| 参数 | 数据类型 | 是否必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 目标 Project 的名称。 |
| description | string | 否 | 目标 Project 的描述。 |
| endpoint | string | 否 | 目标 Project 的服务入口。仅在有跨地域的需求时填写。 |
| uid | string | 否 | 目标账号的 uid。仅在有跨账号的需求时填写。 |
有一些注意点:
- project字段在CR创建后无法修改,如果需要切换project需要创建新的CR。
- name字段为必填,采集到的日志会发到这里。
- endpoint字段仅在有跨地域的需求时填写,否则会默认在集群所在的地域。
- uid字段仅在有跨账号的需求时填写,其他场景不用关心这个参数。
- 如果指定的project不存在的话,会尝试创建,创建project时如果填写了endpoint、uid,则会创建到对应的地域/账号下
**2.1.2. config字段详解与配置指南**
config字段列表如下:
| 参数 | 数据类型 | 是否必填 | 说明 |
|---|---|---|---|
| sample | string | 否 | 日志样例。 |
| global | object | 否 | 全局配置。 |
| inputs | object列表 | 是 | 输入插件列表。 |
| processors | object列表 | 否 | 处理插件列表。 |
| aggregators | object列表 | 否 | 聚合插件列表。 |
| flushers | object列表 | 是 | 输出插件列表。 |
| configTags | map | 否 | 用于标记iLogtail采集配置的自定义标签。 |
为了追求使用体验的统一、功能的完善,config的详细信息与插件参数,与SLS CreateLogtailPipelineConfig接口的“请求参数”完全一致,并支持所有功能。
这里需要注意:
- 当前Inputs插件列表只支持配置一个(API层面限制)
- 当前Flushers插件列表只支持配置一个,且只能是flusher_sls(API层面限制)
- configTags是打在采集配置上的标签,不是写到日志里的tag
**2.1.3. logstores字段详解与配置指南**
logstores字段,里面支持配置多个logstore属性。单个logstore的参数列表如下:
| 参数 | 数据类型 | 是否必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 需要创建的 Logstore 的名称。 |
| queryMode | string | 否 | 目标 Logstore 的类型。默认值为standard,可选值: query:查询型Logstore。 standard:标准型Logstore。 |
| ttl | int | 否 | 目标 Logstore 的数据存储的时间(以天为单位)。默认值为30,取值范围为1~3650,如果配置为3650,表示永久保存。 |
| hotTtl | int | 否 | 目标 Logstore 的热数据存储的时间(以天为单位)。默认值为0,需要小于 ttl 且大于等于 7。 |
| shardCount | int | 否 | 目标 Logstore 的 shard 数量。默认值为2,取值范围为1~100。 |
| maxSplitShard | int | 否 | 目标 Logstore 的最大自动分裂 shard 数量。默认值为64,取值范围为1~256。 |
| autoSplit | bool | 否 | 目标 Logstore 是否开启自动拆分 shard 功能。默认值为true。 |
| telemetryType | string | 否 | 目标 Logstore 的可观测数据类型。默认值为None,可选值: None:日志类型。 Metrics:Metrics 类型。 |
| appendMeta | bool | 否 | 目标 Logstore 是否开通记录外网IP功能。默认值为true。 |
| enableTracking | bool | 否 | 目标 Logstore 是否启用 Web Tracking。默认值为false。 |
| encryptConf | object | 否 | 目标 Logstore 的加密配置信息。 |
| meteringMode | string | 否 | 目标 Logstore 的计费模式。默认值为空,可选值: ChargeByFunction:按功能计费 ChargeByDataIngest:按写入量计费。 |
这里的Logstore参数,完全支持了SLSCreateLogstore接口中的参数,并且支持修改计费模式。
这里的注意点有:
- 一般场景下创建Logstore,只需要填写name即可,其他参数不必关心,它们的默认值与在控制台创建Logstore是一样的
- 所有的参数仅在创建Logstore时有效,已有的Logstore不会被该参数修改。
**2.1.4.** machineGroups**字段详解与配置指南**
machineGroups字段,里面支持配置多个机器组。下面是单个机器组的参数列表:
| 参数 | 数据类型 | 是否必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 需要与iLogtail采集配置关联的机器组名。 |
机器组配置做了简化处理,只需要填写name,就会创建一个标识型机器组,机器组的名字与自定义标识一致。
需要注意:
- machineGroups字段默认不需要填写,使用默认的日志组件自动创建的机器组就可以了。
- 已有的机器组的属性不会被覆盖,即原本有一个ip机器组叫a,这里配置a的话,不会把a机器组改为标识型的。
- 采集配置的机器组会与这里配置的机器组严格一致,如果需要添加机器组,需要编辑这个参数。
**2.2.** 你只需要填参数就可以,但AliyunPipelineConfig要考虑的事情就很多了
相信大家都有遇到过,面对一个不熟悉的配置,乱填一通参数,提交上去,发现又没有成功,又没有报错,整个流程卡死在那了。
AliyunPipelineConfig不会让你受这样的委屈!你只管填写参数,其他的事情,AliyunPipelineConfig全兜了!
**2.2.1. 假如,我是说假如,你填错了参数格式**
AliyunPipelineConfig具有详细的CRD格式规范,同时搭配了webhook进行校验,让格式问题无所遁形!
- CRD的格式校验由k8s进行,保证整体结构不出差错

- webhook会校验更细节的固定参数的值,例如:
- metadata.name需要作为采集配置名使用,需要符合采集配置名的要求
- spec.project.name需要符合project名规范
- spec.config.inputs必须要有插件
- ……
全方位为你保驾护航。
**2.2.2. 假如,我是说假如,你遇到了报错**
虽然有参数值的校验,但参数内容也还是可能填错的,就比如我们的Logstore,创建的时候参数那么多,难免填错一个;或者,机器组配额超限了,写了一些机器组怎么都创建不出来;或者,填写的uid错了,没有获取到跨账号的权限……
这些情况,可以由我们AliyunPipelineConfig的Status字段,全部展示出来!下面是一段采集配置,在配置时指定错了project,使用了其他用户的project,那么这里就会有报错:
apiVersion: telemetry.alibabacloud.com/v1alpha1
kind: ClusterAliyunPipelineConfig
metadata:
finalizers:
- finalizer.pipeline.alibabacloud.com
name: example-k8s-file
预期的配置
spec:
config:
flushers:
- Endpoint: cn-hangzhou.log.aliyuncs.com
Logstore: k8s-file
Region: cn-hangzhou
TelemetryType: logs
Type: flusher_sls
inputs: - EnableContainerDiscovery: true
FilePaths: - /data/logs/app_1/**/test.LOG
Type: input_file
logstores: - encryptConf: {}
name: k8s-file
project:
name: k8s-log-clusterid
CR的应用状态
status:
CR 是否应用成功
success: false
CR 当前的状态信息,应用失败会展示报错详情
message: |-
{
"httpCode": 401,
"errorCode": "Unauthorized",
"errorMessage": "The project does not belong to you.",
"requestID": "xxxxxx"
}
当前 status 的更新时间
lastUpdateTime: '2024-06-19T09:21:34.215702958Z'
上次成功应用的配置信息,该配置信息为填充默认值后实际生效的配置。本次没有应用成功,所以这里为空
lastAppliedConfig:
config:
flushers: null
global: null
inputs: null
project:
name: ""
通过这些报错信息,就可以很方便地定位到问题。
另外,AliyunPipelineConfig会进行失败重试,如果是临时发生的报错(例如某个project的logstore额度不够,很快调整好了),后续都会重试到正常为止(重试间隔指数增长)。
**2.2.3. 假如,我是说假如,你多个配置冲突了**
在AliyunLogConfig时代,我们可能会遇到这样的问题:一不小心好几个CR指向了同一个project/config,导致整个采集配置被几个CR相互覆盖,日志采集被影响。

AliyunPipelineConfig会帮你解决这个问题!在创建采集配置时,AliyunPipelineConfig会给采集配置打上标签,记录CR所在的集群、类型、命名空间:

对于有标签的采集配置,只有创建者可以对它进行修改,其他CR的请求会被拒绝。当然,被拒绝的CR也会把拒绝信息写到Status中,告诉你它与xx集群xx命名空间xx类型的名为xx的CR出现了冲突,这样可以快速定位,解决问题。

**三、眼睛:懂了。手:我~~不~~会!**
你可能会说了:你balabala说了这么一大堆,我好像看懂了但还是不会配置啊!
别急,下面来几个例子,实操练手。
**3.1. 经典场景,采集并解析nginx-ingress日志**
这是ACK ingress组件配置日志采集的文档,可以看到里面配置了一个比较复杂的AliyunLogConfig CR,并配上了很长的说明:

我们现在用AliyunPipelineConfig来实现它:
- 下面的需要替换成你实际的project
- 下面的需要替换成你的实际endpoint,例如cn-hangzhou.log.aliyuncs.com
- 下面的需要替换成你的实际region,例如cn-hangzhou
apiVersion: telemetry.alibabacloud.com/v1alpha1
kind: ClusterAliyunPipelineConfig
metadata:
name: k8s-nginx-ingress
spec:
指定目标 project
project:
name:
logstores:
创建 Logstore,用于存储Ingress日志
- name: nginx-ingress
产品Code,请勿更改。
productCode: k8s-nginx-ingress
添加采集配置
config:
定义输入插件
inputs:
使用service\_docker\_stdout插件采集容器内文本日志
- Type: service_docker_stdout
Stdout: true
Stderr: true
过滤目标容器,这里是容器label。
IncludeLabel:
io.kubernetes.container.name: nginx-ingress-controller
定义解析插件
processors:
- Type: processor_regex
KeepSource: false
Keys: - client_ip
- x_forward_for
- remote_user
- time
- method
- url
- version
- status
- body_bytes_sent
- http_referer
- http_user_agent
- request_length
- request_time
- proxy_upstream_name
- upstream_addr
- upstream_response_length
- upstream_response_time
- upstream_status
- req_id
- host
- proxy_alternative_upstream_name
NoKeyError: true
NoMatchError: true
提取字段使用的正则表达式。符合该格式的日志,会将每个捕获组中内容映射到对应的字段上。
Regex: ^(\S+)\s-\s[([^]]+)]\s-\s(\S+)\s[(\S+)\s\S+\s"(\w+)\s(\S+)\s([^"]+)"\s(\d+)\s(\d+)\s"([^"]*)"\s"([^"]*)"\s(\S+)\s(\S+)+\s[([^]]*)]\s(\S+?(?:,\s\S+?)*)\s(\S+?(?:,\s\S+?)*)\s(\S+?(?:,\s\S+?)*)\s(\S+?(?:,\s\S+?)*)\s(\S+)\s*(\S*)\s*[*([^]]*)]*.*
SourceKey: content
定义输出插件
flushers:
使用flusher\_sls插件输出到指定Logstore。
- Type: flusher_sls
Logstore: nginx-ingress
Endpoint:
Region:
TelemetryType: logs
这样,一个ingress解析配置就好了,结构非常清晰。
**3.2. 想要跨地域、跨账号**
首先,我们需要明确一点,就是数据采集依赖:
- 数据源
- 采集器
- 采集配置
要做到跨地域和跨账号,不仅需要修改采集配置的生成端(alibaba-log-controller)的配置,也需要修改采集器侧(iLogtail)的配置。
下面我们举一个例子,来介绍我们的跨地域和跨账号能力。
我们假设数据源在A账号杭州地域,要投递到B账号的上海地域
**3.2.1. 修改采集侧配置**
首先,需要修改iLogtail的启动参数。
logtail的启动参数可以参考文档,这里我们只关心ilogtail_config.json文件里面的两个参数:config_server_address和data_server_list。
- config_server_address指定了配置拉取的地址,logtail通过这个地址拉取对应地域的采集配置
- data_server_list指定了数据发送的地址,logtail可以把数据发送到这些region
初始的启动参数文件只包含一个region,就如文档里的:

- 为了支持跨地域,我们需要做一些修改,加上上海的地域信息。修改后的配置如下:
{
"config_server_address" : "http://logtail.cn-hangzhou.log.aliyuncs.com",
"config_server_address_list": [
"http://logtail.cn-shanghai.log.aliyuncs.com"
"http://logtail.cn-hangzhou.log.aliyuncs.com"
],
"data_server_list" :
[
{
"cluster" : "cn-shanghai",
"endpoint" : "cn-shanghai.log.aliyuncs.com"
},
{
"cluster" : "cn-hangzhou",
"endpoint" : "cn-hangzhou.log.aliyuncs.com"
},
]
}
- 可以把这个文件保存到configMap中,挂载到kube-system命名空间下,名为logtail-ds的daemonset里,容器内路径假设为/etc/ilogtail/ilogtail_config.json
- 然后,在集群中,在kube-system命名空间下,找到名为alibaba-log-configuration的configmap
- 编辑log-ali-uid的值,添加B账号的uid(多个账号之间使用半角逗号(,)相隔,例如17****397,12****456)
- 编辑log-config-path的值,改为上面挂载的/etc/ilogtail/ilogtail_config.json
- 记录下log-machine-group配置项的值

- 重启kube-system命名空间下名为logtail-ds的daemonset**。**
至此,iLogtail就直接拉取上海地域的采集配置、发送数据到上海,并拥有了B账号的用户标识
**3.2.2. 修改alibaba-log-controller配置**
alibaba-log-controller的改动比较简单
- 在kube-system命名空间下,找到名为alibaba-log-controller的deployment
- 添加环境变量ALICLOUD_LOG_ACCOUNT_INFOS={"":{"accessKeyID":"<your_access_key_id>","accessKeySecret":"<your_access_key_secret>"}},这里的uid是B账号的,ak/sk需要具备SLS相关的权限。

- 重启alibaba-log-controller
至此,alibaba-log-controller就拥有了在B账号下创建SLS资源(logstore、采集配置等)的权限
**3.2.3. 创建**AliyunPipelineConfig CR
编辑AliyunPipelineConfig的CR是最简单的一步,只需要添加上uid和endpoint即可。不要忘记修改flusher_sls中的endpoint和region
apiVersion: telemetry.alibabacloud.com/v1alpha1
kind: ClusterAliyunPipelineConfig
metadata:
name: k8s-nginx-ingress
spec:
指定目标 project
project:
B账号的project
name:
B账号的uid
uid:
目标endpoint
endpoint: cn-shanghai.log.aliyuncs.com
添加采集配置
config:
定义输入插件
inputs:
这里省略
...
定义输出插件
flushers:
使用flusher\_sls插件输出到指定Logstore。
- Type: flusher_sls
Logstore: nginx-ingress
Endpoint: cn-shanghai.log.aliyuncs.com
Region: cn-shanghai
TelemetryType: logs
这样,采集配置就会创建在B账号的project下,数据也可以采集过来了。
3.3. 你可能会问:我那么多AliyunLogConfig,怎么迁移到AliyunPipelineConfig啊?
还记得我们上面讲解AliyunPipelineConfig参数时,省略了一个吗?就是enableUpgradeOverride!
当满足以下条件时,可以把AliyunLogConfig直接升级到AliyunPipelineConfig:
- AliyunLogConfig与AliyunPipelineConfig在同一集群内
- 如果不在同一集群,AliyunPipelineConfig会因配置冲突而应用失败
- AliyunLogConfig与AliyunPipelineConfig指向同一个采集配置:
- 目标project相同
- AliyunLogConfig中为集群默认的project或spec.project
- AliyunPipelineConfig中为spec.project.name
- 目标iLogtail采集配置名相同
- AliyunLogConfig中为spec.logtailConfig.configName
- AliyunPipelineConfig中为metadata.Name
- 目标project相同
- AliyunPipelineConfig打开了enableUpgradeOverride开关
apiVersion: telemetry.alibabacloud.com/v1alpha1
kind: ClusterAliyunPipelineConfig
metadata:
name: k8s-nginx-ingress
spec:
只需要打开这个开关,就可以覆盖更新指向project:、采集配置名为:k8s-nginx-ingress的AliyunLogConfig
enableUpgradeOverride: true
project:
name:
config:
inputs:
...
flushers:
...
满足以上条件,我们的CRD管理器alibaba-log-controller就会执行以下操作:
- 应用AliyunPipelineConfig,将原本的采集配置覆盖。
- 如果应用成功,删除已有的AliyunLogConfig。
这样,AliyunLogConfig就可以升级到AliyunPipelineConfig了
**四、总结**
AliyunPipelineConfig的介绍就到这里了,不知道你有没有会用了呢?
AliyunPipelineConfig会先在“自建K8s集群部署日志组件”上线,后续会正式登陆ACK等容器产品,欢迎大家使用并反馈意见,我们会虚心采纳和改正。