一、既然是一文玩转，自然要讲些背景

**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在配置格式、行为逻辑上做了很大改进，主打的就是灵活、简单、稳定。

**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字段列表如下：

有一些注意点：

• project字段在CR创建后无法修改，如果需要切换project需要创建新的CR。
• name字段为必填，采集到的日志会发到这里。
• endpoint字段仅在有跨地域的需求时填写，否则会默认在集群所在的地域。
• uid字段仅在有跨账号的需求时填写，其他场景不用关心这个参数。
• 如果指定的project不存在的话，会尝试创建，创建project时如果填写了endpoint、uid，则会创建到对应的地域/账号下

**2.1.2. config字段详解与配置指南**

config字段列表如下：

为了追求使用体验的统一、功能的完善，config的详细信息与插件参数，与SLS CreateLogtailPipelineConfig接口的“请求参数”完全一致，并支持所有功能。

这里需要注意：

• 当前Inputs插件列表只支持配置一个（API层面限制）
• 当前Flushers插件列表只支持配置一个，且只能是flusher_sls（API层面限制）
• configTags是打在采集配置上的标签，不是写到日志里的tag

**2.1.3. logstores字段详解与配置指南**

logstores字段，里面支持配置多个logstore属性。单个logstore的参数列表如下：

这里的Logstore参数，完全支持了SLSCreateLogstore接口中的参数，并且支持修改计费模式。

这里的注意点有：

• 一般场景下创建Logstore，只需要填写name即可，其他参数不必关心，它们的默认值与在控制台创建Logstore是一样的
• 所有的参数仅在创建Logstore时有效，已有的Logstore不会被该参数修改。

**2.1.4.** machineGroups**字段详解与配置指南**

machineGroups字段，里面支持配置多个机器组。下面是单个机器组的参数列表：

机器组配置做了简化处理，只需要填写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，就如文档里的：

1. 为了支持跨地域，我们需要做一些修改，加上上海的地域信息。修改后的配置如下：

{
"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"
},
]
}

1. 可以把这个文件保存到configMap中，挂载到kube-system命名空间下，名为logtail-ds的daemonset里，容器内路径假设为/etc/ilogtail/ilogtail_config.json
2. 然后，在集群中，在kube-system命名空间下，找到名为alibaba-log-configuration的configmap
3. 编辑log-ali-uid的值，添加B账号的uid（多个账号之间使用半角逗号（,）相隔，例如17****397,12****456）
4. 编辑log-config-path的值，改为上面挂载的/etc/ilogtail/ilogtail_config.json
5. 记录下log-machine-group配置项的值

1. 重启kube-system命名空间下名为logtail-ds的daemonset**。**

至此，iLogtail就直接拉取上海地域的采集配置、发送数据到上海，并拥有了B账号的用户标识

**3.2.2. 修改alibaba-log-controller配置**

alibaba-log-controller的改动比较简单

1. 在kube-system命名空间下，找到名为alibaba-log-controller的deployment
2. 添加环境变量ALICLOUD_LOG_ACCOUNT_INFOS={"":{"accessKeyID":"<your_access_key_id>","accessKeySecret":"<your_access_key_secret>"}}，这里的uid是B账号的，ak/sk需要具备SLS相关的权限。

1. 重启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：

1. AliyunLogConfig与AliyunPipelineConfig在同一集群内
   1. 如果不在同一集群，AliyunPipelineConfig会因配置冲突而应用失败
2. AliyunLogConfig与AliyunPipelineConfig指向同一个采集配置：
   1. 目标project相同
      • AliyunLogConfig中为集群默认的project或spec.project
      • AliyunPipelineConfig中为spec.project.name
   • 目标iLogtail采集配置名相同
     • AliyunLogConfig中为spec.logtailConfig.configName
     • AliyunPipelineConfig中为metadata.Name
3. 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就会执行以下操作：

1. 应用AliyunPipelineConfig，将原本的采集配置覆盖。
2. 如果应用成功，删除已有的AliyunLogConfig。

这样，AliyunLogConfig就可以升级到AliyunPipelineConfig了

**四、总结**

AliyunPipelineConfig的介绍就到这里了，不知道你有没有会用了呢？

AliyunPipelineConfig会先在“自建K8s集群部署日志组件”上线，后续会正式登陆ACK等容器产品，欢迎大家使用并反馈意见，我们会虚心采纳和改正。