通过Sidecar方式采集Kubernetes容器文本日志

如果需要每个Pod使用单独的Logtail实例来收集Pod内所有容器的日志，可以使用Sidecar方式在Kubernetes集群上部署Logtail。本文介绍Sidecar方式采集容器文本日志的工作原理、使用限制、前提条件、操作步骤等信息。

工作原理

Sidecar模式

在Sidecar模式中，每个容器组（Pod）运行一个Logtail容器，用于采集当前容器组（Pod）所有容器（Containers）的日志。不同Pod的日志采集相互隔离。
为了采集同一Pod中其他容器的日志文件，需要通过共享存储卷的方式来完成，即将同一份存储卷分别挂载到业务容器和Logtail容器。Sidecar方式采集容器日志的更多信息，请参见Sidecar日志采集介绍和Sidecar模式示例。存储卷的更多信息，请参见存储基础知识。

前提条件

安装Logtail的主机需要在出口方向开放80（HTTP）端口和443（HTTPS）端口。ECS实例的端口由安全组规则控制，添加安全组规则的步骤请参见添加安全组规则。
K8s集群已安装kubectl。

注意事项

目标容器持续新增日志。Logtail只采集增量日志。如果下发Logtail采集配置后，日志文件无更新，则Logtail不会采集该文件中的日志。更多信息，请参见读取日志。
业务容器中待采集文件必须位于存储卷中，且该存储卷必须挂载到Logtail容器。

步骤一：为业务Pod注入Logtail容器

登录Kubernetes集群。
创建一个YAML文件。sidecar.yaml为文件的示例名称，请根据实际情况替换。
```
vim sidecar.yaml
```

在YAML文件中输入如下脚本，并根据实际情况设置其中的参数。

警告

YAML模板中，所有带有${}的占位符都需要替换为您环境中实际的值，其他参数禁止改动、删除。

YAML模板

apiVersion: batch/v1
kind: Job
metadata:
  # 在这里添加 Job 元信息，比如 name 和 namespace
  name: ${job_name}
  namespace: ${namespace}
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
        # 业务容器
        - name: ${main_container_name}
          image: ${main_container_image}
          command: ["/bin/sh", "-c"]
          args:
            - until [[ -f /tasksite/cornerstone ]]; do sleep 1; done;
              # 替换为业务容器的实际启动命令
              ${container_start_cmd};
              retcode=$?;
              touch /tasksite/tombstone;
              exit $retcode
          volumeMounts:
            # 业务容器的日志目录挂载到共享存储卷
            - name: ${shared_volume_name}
              mountPath: ${dir_containing_your_files}
            # 与 Logtail 容器交互的挂载点
            - mountPath: /tasksite
              name: tasksite

        # Logtail sidecar 容器
        - name: logtail
          image: ${logtail_image}
          command: ["/bin/sh", "-c"]
          args:
            - /etc/init.d/ilogtaild start;
              sleep 10; # 等待 Logtail 配置下载完成
              touch /tasksite/cornerstone;
              until [[ -f /tasksite/tombstone ]]; do sleep 1; done;
              sleep 10; # 等待 Logtail 完成日志发送
              /etc/init.d/ilogtaild stop;
          livenessProbe:
            exec:
              command:
                - /etc/init.d/ilogtaild
                - status
            initialDelaySeconds: 30
            periodSeconds: 30
          env:
            # 设置时区。请根据kubernetes集群所在地域，配置时区，格式为"地区/城市"。如果是中国大陆，可以设置时区为Asia/Shanghai。
            # 如果没有正确配置时区，可能导致原始日志与处理日志的时间标签不匹配，进而将日志数据归档到错误的时间点。
            - name: TZ
              value: "${timezone}"
            - name: ALIYUN_LOGTAIL_USER_ID
              value: "${your_aliyun_user_id}"
            - name: ALIYUN_LOGTAIL_USER_DEFINED_ID
              value: "${your_machine_group_user_defined_id}"
            - name: ALIYUN_LOGTAIL_CONFIG
              value: "/etc/ilogtail/conf/${your_region_config}/ilogtail_config.json"
            # 追加 Pod 环境信息作为日志标签
            - name: "ALIYUN_LOG_ENV_TAGS"
              value: "_pod_name_|_pod_ip_|_namespace_|_node_name_|_node_ip_"
            # 获取 Pod 和 Node 的信息
            - name: "_pod_name_"
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: "_pod_ip_"
              valueFrom:
                fieldRef:
                  fieldPath: status.podIP
            - name: "_namespace_"
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
            - name: "_node_name_"
              valueFrom:
                fieldRef:
                  fieldPath: spec.nodeName
            - name: "_node_ip_"
              valueFrom:
                fieldRef:
                  fieldPath: status.hostIP
          volumeMounts:
            # Logtail 容器的日志目录挂载到共享存储卷
            - name: ${shared_volume_name}
              mountPath: ${dir_containing_your_files}
            # 与业务容器交互的挂载点
            - mountPath: /tasksite
              name: tasksite
              # 时区和主机一致
            - name: tz-config
              mountPath: /etc/localtime
              readOnly: true
      volumes:
        # 定义空的共享存储卷用于日志存储
        - name: ${shared_volume_name}
          emptyDir: {}
        # 定义存储卷用于容器间通信
        - name: tasksite
          emptyDir:
            medium: Memory
        - name: tz-config
          hostPath:
            path: /usr/share/zoneinfo/Asia/Shanghai  # 主机上的时区文件

关键参数说明

变量	说明
`${timezone}`	设置容器时区。更多信息，请参见支持时区。
`${your_aliyun_user_id}`	设置为您的阿里云账号（主账号）ID。更多信息，请参见配置用户标识。
`${your_machine_group_user_defined_id}`	自定义设置机器组的自定义标识，用于创建自定义机器组。例如`nginx-log-sidecar`。重要请确保该标识在您的Project所在地域内唯一。
`${your_region_config}`	请根据日志服务Project所在地域和访问的网络类型填写。其中，地域信息请参见开服地域。如果使用公网采集日志，格式为`region-internet`，例如华东 1（杭州）为cn-hangzhou-internet。如果使用阿里云内网采集日志，格式为`region`。例如华东 1（杭州）为cn-hangzhou。
`${logtail_image}`	Logtail镜像地址。例如`registry.cn-hangzhou.aliyuncs.com/log-service/logtail:latest`。
`${shared_volume_name}`	自定义设置卷的名称。重要 `volumeMounts`节点下的`name`参数与`volumes`节点下的`name`参数需设置为一致，即确保Logtail容器和业务容器挂载相同的卷上。
`${dir_containing_your_files}`	设置挂载路径，即容器待采集文本日志所在目录。

示例

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    deployment.kubernetes.io/revision: '1'
  labels:
    app: deployment-file
    cluster_label: CLUSTER-LABEL-A
  name: deployment-file
  namespace: default
spec:
  progressDeadlineSeconds: 600
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: deployment-file
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: deployment-file
        cluster_label: CLUSTER-LABEL-A
    spec:
      containers:
        - name: timestamp-test
          image: 'mirrors-ssl.aliyuncs.com/busybox:latest'
          args:
            - >-
              while true; mkdir -p /root/log; do date '+%Y-%m-%d %H:%M:%S'
              >>/root/log/timestamp.log; echo 1 >>/root/log/timestamp.log; echo
              2 >>/root/log/timestamp.log; echo 3 >>/root/log/timestamp.log;
              echo 4 >>/root/log/timestamp.log; echo 5
              >>/root/log/timestamp.log; echo 6 >>/root/log/timestamp.log;
              echo 7 >>/root/log/timestamp.log; echo 8
              >>/root/log/timestamp.log; echo 9 >>/root/log/timestamp.log;
              sleep 10; done
          command:
            - /bin/sh
            - '-c'
            - '--'
          env:
            - name: cluster_id
              value: CLUSTER-A
          imagePullPolicy: IfNotPresent
          resources: {}
          terminationMessagePath: /dev/termination-log
          terminationMessagePolicy: File
          volumeMounts:
            # 业务容器的日志目录挂载到共享存储卷
            - name: test-logs
              mountPath: /root/log
             # 与 Logtail 容器交互的挂载点
            - mountPath: /tasksite
              name: tasksite
            - name: tz-config
              mountPath: /etc/localtime
              readOnly: true
        # Logtail sidecar 容器
        - name: logtail
          image: registry.cn-hangzhou.aliyuncs.com/log-service/logtail:v1.8.7.0-aliyun
          command: ["/bin/sh", "-c"]
          args:
            - /etc/init.d/ilogtaild start;
              sleep 10;
              touch /tasksite/cornerstone;
              until [[ -f /tasksite/tombstone ]]; do sleep 1; done;
              sleep 10;
              /etc/init.d/ilogtaild stop;
          livenessProbe:
            exec:
              command:
                - /etc/init.d/ilogtaild
                - status
            initialDelaySeconds: 30
            periodSeconds: 30
          resources:
            limits:
              cpu: 500m
              memory: 512Mi
            requests:
              cpu: 10m
              memory: 30Mi
          env:
            # 设置时区。请根据kubernetes集群所在地域，配置时区，格式为"地区/城市"。如果是中国大陆，可以设置时区为Asia/Shanghai。
            # 如果没有正确配置时区，可能导致原始日志与处理日志的时间标签不匹配，进而将日志数据归档到错误的时间点。
            - name: TZ
              value: "Asia/Shanghai"
            # 在这里替换为实际的环境变量值
            - name: ALIYUN_LOGTAIL_USER_ID
              value: "1290918****39680"
            - name: ALIYUN_LOGTAIL_USER_DEFINED_ID
              value: "nginx-log-sidecar"
            - name: ALIYUN_LOGTAIL_CONFIG
              value: "/etc/ilogtail/conf/cn-beijing-internet/ilogtail_config.json"
            # 追加 Pod 环境信息作为日志标签
            - name: "ALIYUN_LOG_ENV_TAGS"
              value: "_pod_name_|_pod_ip_|_namespace_|_node_name_|_node_ip_"
            # 获取 Pod 和 Node 的信息
            - name: "_pod_name_"
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: "_pod_ip_"
              valueFrom:
                fieldRef:
                  fieldPath: status.podIP
            - name: "_namespace_"
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
            - name: "_node_name_"
              valueFrom:
                fieldRef:
                  fieldPath: spec.nodeName
            - name: "_node_ip_"
              valueFrom:
                fieldRef:
                  fieldPath: status.hostIP
          volumeMounts:
            # Logtail 容器的日志目录挂载到共享存储卷
            - name: test-logs
              mountPath: /root/log
      volumes:
        # 定义空的共享存储卷用于日志存储
        - name: test-logs
          emptyDir: {}
          # 定义存储卷用于容器间通信
        - name: tasksite
          emptyDir:
            medium: Memory
        - name: tz-config
          hostPath:
            path: /usr/share/zoneinfo/Asia/Shanghai  # 主机上的时区文件
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      terminationGracePeriodSeconds: 30

执行如下命令使sidecar.yaml文件配置生效。
sidecar.yaml为文件名，请根据实际情况替换。
```
kubectl apply -f sidecar.yaml
```

步骤二：创建用户自定义标识机器组

重要

步骤一中YAML参数ALIYUN_LOGTAIL_USER_DEFINED_ID的值为用户自定义标识。

登录日志服务控制台，在Project列表，单击打开目标Project。
左侧导航栏中，选择资源 > 机器组。在打开的机器组页面中，选择机器组右侧的 > 创建机器组。

在弹出的创建机器组页面，填写以下信息，并单击确定。

参数	说明

参数	说明
名称	机器组名称，命名规则如下所示：只能包括小写字母、数字、短划线（-）和下划线（_）。必须以小写字母或者数字开头和结尾。长度必须在 2~128 字符之间。重要创建后，不支持修改机器组名称，请谨慎填写。
机器组标识	选择用户自定义标识。
机器组Topic	（可选）机器组Topic用于区分不同服务器产生的日志数据。更多信息，请参见日志主题。
用户自定义标识	填入上述步骤中配置的用户自定义标识。

步骤三：创建Logtail采集配置

在目标Project中，单击目标Logstore左侧 > 数据接入 > 。
在快速接入数据对话框中，单击Kubernetes-文件卡片。
选择目标Project和Logstore，单击下一步。选择您在安装Logtail组件时所使用的Project。Logstore为您自定义创建的Logstore。
在机器组配置页面完成如下操作。机器组相关信息，详细请参见机器组。
1. 根据实际场景，单击以下页签：
  - K8s场景 > ACK Daemonset
  - K8s场景 > 自建集群Daemonset
2. 确认目标机器组已在应用机器组列表中，然后单击下一步。机器组选择步骤二创建的机器组。
  - 如果需要新建机器组，请单击创建机器组，按照右侧面板进行创建。更多信息，请参见采集阿里云ACK集群文本日志（DaemonSet方式部署Logtail）。
  - 如果机器组心跳为FAIL，您可单击自动重试。如果还未解决，请参见Logtail机器组无心跳进行排查。

创建Logtail采集配置，单击下一步创建Logtail采集配置，日志服务开始采集日志。

说明

Logtail采集配置生效时间最长需要3分钟，请耐心等待。

全局配置

配置项	说明
配置名称	Logtail配置名称，在其所属Project内必须唯一。创建Logtail配置成功后，无法修改其名称。
日志主题类型	选择日志主题（Topic）的生成方式。更多信息，请参见日志主题。机器组Topic：设置为机器组的Topic属性，用于明确区分不同机器组产生的日志。文件路径提取：设置为文件路径正则，则需要设置自定义正则，用正则表达式从路径里提取一部分内容作为Topic。用于区分不同源产生的日志。自定义：自定义日志主题。
高级参数	其它可选的与配置全局相关的高级功能参数，请参见创建Logtail流水线配置。

输入配置

参数名称	说明
Logtail部署模式	Logtail部署模式，选择Sidecar。
文件路径类型	选择待采集的文件路径是容器内路径或宿主机路径。对于通过hostPath方式挂载数据卷的容器，如果您希望直接采集其在宿主机上映射的日志文件，请选择宿主机路径，其余情况请选择容器内路径。
文件路径	如果目标容器节点是Linux系统，则日志路径必须以正斜线（/）开头，例如`/apsara/nuwa//app.Log`。如果目标容器节点是Windows系统，则日志路径必须以盘符开头，例如`C:\Program Files\Intel\\.Log`。目录名和文件名均支持完整模式和通配符模式，文件名规则请参见Wildcard matching。其中，日志路径通配符只支持星号（）和半角问号（?）。日志文件查找模式为多层目录匹配，即符合条件的指定目录（包含所有层级的目录）下所有符合条件的文件都会被查找到。例如： `/apsara/nuwa/*/.log`表示`/apsara/nuwa`目录（包含该目录的递归子目录）中后缀名为.log的文件。 `/var/logs/app_//.log`表示`/var/logs`目录下所有符合`app_`格式的目录（包含该目录的递归子目录）中后缀名为`.log`的文件。 `/var/log/nginx//access`表示`/var/log/nginx`目录（包含该目录的递归子目录）中以`access`开头的文件。
最大目录监控深度	设置日志目录被监控的最大深度，即文件路径中通配符`**`匹配的最大目录深度。0代表只监控本层目录。警告请按最小需要原则配置目录监控深度，过大的目录深度导致Logtail占用更多的监控资源，造成日志采集延迟。
文件编码	日志文件的编码格式。
首次采集大小	配置首次生效时，匹配文件的起始采集位置距离文件结尾的大小。首次采集大小设定值为1024 KB。首次采集时，如果文件小于1024 KB，则从文件内容起始位置开始采集。首次采集时，如果文件大于1024 KB，则从距离文件末尾1024 KB的位置开始采集。您可以通过此处修改首次采集大小，取值范围为0~10485760，单位为KB。
采集黑名单	打开采集黑名单开关后，可进行黑名单配置，即可在采集时忽略指定的目录或文件。支持完整匹配和通配符匹配目录和文件名。其中，通配符只支持星号（）和半角问号（?）。重要如果您在配置日志路径时使用了通配符，但又需要过滤掉其中部分路径，则需在采集黑名单中填写对应的完整路径来保证黑名单配置生效。例如您配置日志路径为`/home/admin/app/log/.log`，但要过滤`/home/admin/app1`目录下的所有子目录，则需选择目录黑名单，配置目录为`/home/admin/app1/` 。如果配置为`/home/admin/app1`，黑名单不会生效。匹配黑名单过程存在计算开销，建议黑名单条目数控制在10条内。目录路径不能以正斜线（/）结尾，例如将设置路径为`/home/admin/dir1/`，目录黑名单不会生效。支持按照文件路径黑名单、文件黑名单、目录黑名单设置，详细说明如下：文件路径黑名单文件黑名单目录黑名单选择文件路径黑名单，配置路径为`/home/admin/private.log`，则表示在采集时忽略`/home/admin/`目录下所有以private开头，以.log结尾的文件。选择文件路径黑名单，配置路径为`/home/admin/private/_inner.log`，则表示在采集时忽略`/home/admin/`目录下以private开头的目录内，以_inner.log结尾的文件。例如`/home/admin/private/app_inner.log`文件被忽略，`/home/admin/private/app.log`文件被采集。选择文件黑名单，配置文件名为`app_inner.log`，则表示采集时忽略所有名为`app_inner.log`的文件。选择目录黑名单，配置目录为`/home/admin/dir1`，则表示在采集时忽略`/home/admin/dir1`目录下的所有文件。选择目录黑名单，配置目录为`/home/admin/dir`，则表示在采集时忽略`/home/admin/`目录下所有以dir开头的子目录下的文件。选择目录黑名单，配置目录为`/home/admin/*/dir`，则表示在采集时忽略`/home/admin/`目录下二级目录名为dir的子目录下的所有文件。例如`/home/admin/a/dir`目录下的文件被忽略，`/home/admin/a/b/dir`目录下的文件被采集。
允许文件多次采集	默认情况下，一个日志文件只能匹配一个Logtail配置。如果文件中的日志需要被采集多份，需打开允许文件多次采集开关。
高级参数	Logtail配置的部分参数需要手动输入，请参见创建Logtail流水线配置。

处理配置

配置项	说明
日志样例	待采集日志的样例，请务必使用实际场景的日志。日志样例可协助您配置日志处理相关参数，降低配置难度。支持添加多条样例，总长度不超过1500个字符。 `[2023-10-01T10:30:01,000] [INFO] java.lang.Exception: exception happened at TestPrintStackTrace.f(TestPrintStackTrace.java:3) at TestPrintStackTrace.g(TestPrintStackTrace.java:7) at TestPrintStackTrace.main(TestPrintStackTrace.java:16)`
多行模式	多行日志的类型：多行日志是指每条日志分布在连续的多行中，需要从日志内容中区分出每一条日志。自定义：通过行首正则表达式区分每一条日志。多行JSON：每个JSON对象被展开为多行，例如： `{ "name": "John Doe", "age": 30, "address": { "city": "New York", "country": "USA" } }` 切分失败处理方式： `Exception in thread "main" java.lang.NullPointerException at com.example.MyClass.methodA(MyClass.java:12) at com.example.MyClass.methodB(MyClass.java:34) at com.example.MyClass.main(MyClass.java:½0)` 对于以上日志内容，如果日志服务切分失败：丢弃：直接丢弃这段日志。保留单行：将每行日志文本单独保留为一条日志，保留为一共四条日志。
处理模式	处理插件组合，包括原生插件和拓展插件。有关处理插件的更多信息，请参见处理插件概述。重要处理插件的使用限制，请以控制台页面的提示为准。 2.0版本的Logtail：原生处理插件可任意组合。原生处理插件和扩展处理插件可同时使用，但扩展处理插件只能出现在所有的原生处理插件之后。低于2.0版本的Logtail：不支持同时添加原生插件和扩展插件。原生插件仅可用于采集文本日志。使用原生插件时，须符合如下要求：第一个处理插件必须为正则解析插件、分隔符模式解析插件、JSON解析插件、Nginx模式解析插件、Apache模式解析插件或IIS模式解析插件。从第二个处理插件到最后一个处理插件，最多包括1个时间解析处理插件，1个过滤处理插件和多个脱敏处理插件。对于解析失败时保留原始字段和解析成功时保留原始字段参数，只有以下组合有效，其余组合无效。只上传解析成功的日志：解析成功时上传解析后的日志，解析失败时上传原始日志：解析成功时不仅上传解析后的日志，并且追加原始日志字段，解析失败时上传原始日志。例如，原始日志`"content": "{"request_method":"GET", "request_time":"200"}"`解析成功，追加原始字段是在解析后日志的基础上再增加一个字段，字段名为重命名的原始字段（如果不填则默认为原始字段名），字段值为原始日志`{"request_method":"GET", "request_time":"200"}`。

创建索引和预览数据，然后单击下一步。日志服务默认开启全文索引。您也可以根据采集到的日志，手动创建字段索引，或者单击自动生成索引，日志服务将自动生成字段索引。更多信息，请参见创建索引。
如果需要查询日志中的所有字段，建议使用全文索引。如果只需查询部分字段、建议使用字段索引，减少索引流量。如果需要对字段进行分析（SELECT语句），必须创建字段索引。
单击查询日志，系统将跳转至Logstore查询分析页面。