日志服务 使用环境变量声明式采集日志

一、操作场景

该功能适用于以下场景：

·应用开发者需要自助接入日志采集，无需等待运维操作。

·团队希望将日志采集配置与应用部署声明放在一起，实现 GitOps 管理。

·快速验证或开发环境下需要极简方式接入日志服务。

二、前提条件

已开通 日志服务 CLS。根据集群类型，还需满足以下条件：

三、TKE 集群

·已创建 TKE 标准集群，且 Kubernetes 版本 ≥ 1.18，可参见 创建集群。

·集群已开启日志采集功能，即已安装 3.0.3 及以上镜像版本的 tke-log-agent（DaemonSet）和 3.0.3 及以上镜像版本的 cls-provisioner（Deployment）。如未安装，请在 TKE 控制台 的集群监控告警 > 日志页面开启日志采集。

四、自建 K8s 集群

·已创建自建 Kubernetes 集群，且 Kubernetes 版本 ≥ 1.18。

·集群已安装 LogListener DaemonSet 组件（安装方式请参见 自建 K8s 集群安装 LogListener）。

·集群已部署 3.0.3 及以上镜像版本的 cls-provisioner（Deployment）。

五、使用限制

·仅支持 Deployment、StatefulSet、DaemonSet、Job、CronJob 工作负载类型，不支持裸 Pod（无 ownerReference 的 Pod，例如通过 kubectl run 创建的 Pod）。

·支持 TKE 标准集群和自建 K8s 集群（需部署 cls-provisioner），不支持 EKS Serverless 集群。

·同一 Workload 下所有副本的 env 必须一致，不支持多副本 env 不同的场景。

·通过环境变量创建的采集配置不支持在 CLS 控制台或 TKE 控制台修改。修改内容会在 Pod 重建时被环境变量的原始声明覆盖。如需调整采集规则，请直接修改 Pod env 后重新部署（重新部署会导致 Pod 重启）。

·环境变量适用于标准采集场景，如需使用高级功能（如投递配置、处理插件等），建议删除当前环境变量与已创建的采集配置，改用 TKE 控制台、API 或 LogConfig CRD 进行配置。

六、操作步骤

根据你的日志来源，选择以下任一采集场景进行配置。各场景之间可组合使用，一个 Pod 中可同时声明多组 cls_logs_{key} 环境变量，实现多路采集，可参见 场景五：多路采集（组合配置）。

七、场景一：采集容器标准输出（最简配置）

在 Pod 的工作负载 YAML 中，为目标容器的 env 字段添加以下环境变量即可开启标准输出采集：

env: – name: cls_logs_demo value: stdout

注意：说明：

注意：其中 {key} 是用户自定义的采集规则标识名，用于区分同一 Workload 中的不同采集规则。同一个 Workload 中可以声明多组 cls_logs_{key} 环境变量（即多个不同的 key），每组代表一路独立的采集配置。

注意：{key} 需遵循以下约束：

完整的 Deployment YAML 示例如下（ env 部分为需要添加的环境变量）：

apiVersion: apps/v1kind: Deploymentmetadata: name: my-app namespace: defaultspec: replicas: 2 selector: matchLabels: app: my-app template: metadata: labels: app: my-app spec: containers: – name: my-app image: my-app:latest env: # 添加以下环境变量即可开启 CLS 标准输出采集 – name: cls_logs_demo value: stdout

八、场景二：采集容器内文件

如需采集容器内指定路径的日志文件，设置采集类型为 container_file 并通过 _path 指定文件路径：

env: – name: cls_logs_applog value: container_file – name: cls_logs_applog_path value: /usr/local/app/logs/*.log

九、场景三：采集节点（宿主机）文件

如需采集宿主机上的日志文件，设置采集类型为 host_file：

env: – name: cls_logs_hostlog value: host_file – name: cls_logs_hostlog_path value: /data/logs/*.log

注意：说明：

注意：此处的路径是宿主机上的路径，而非容器内路径。LogListener 以 DaemonSet 形式运行在每个节点上，因此可以直接访问宿主机文件系统。开发者在容器的 env 中声明路径后，会生成对应的 LogConfig CR，由节点上的 LogListener 进程完成采集。

十、场景四：指定已有 Topic（不自动创建资源）

如果你已有 CLS Topic，可通过 _topic_id 环境变量直接指定，cls-provisioner 将复用该 Topic 而不自动创建新资源。

env: – name: cls_logs_demo value: stdout – name: cls_logs_demo_topic_id value: lhxxx-xxxx-xxxx-1234567890

注意：说明：

注意：指定 _topic_id 后，TTL、分区数等自动建相关的参数将被忽略，系统直接使用该 Topic 现有配置。

十一、场景五：多路采集（组合配置）

一个 Pod 中可以同时声明多组 cls_logs_{key} 环境变量，实现多路日志采集。每组使用不同的 {key} 即可，cls-provisioner 会为每组声明分别创建独立的 LogConfig CR 和 Topic。

以下示例同时采集标准输出和容器内文件：

env: # 第一路：采集标准输出 – name: cls_logs_stdout value: stdout # 第二路：采集容器内应用日志文件 – name: cls_logs_applog value: container_file – name: cls_logs_applog_path value: /usr/local/app/logs/*.log – name: cls_logs_applog_log_type value: json_log

十二、场景六：配置日志解析规则（可选）

默认采集模式为单行全文（minimalist_log）。如需其他解析方式，可通过 _log_type 环境变量指定。

十三、JSON 格式

env: – name: cls_logs_demo value: stdout – name: cls_logs_demo_log_type value: json_log – name: cls_logs_demo_json_standard value: "true"

十四、分隔符格式

env: – name: cls_logs_demo value: stdout – name: cls_logs_demo_log_type value: delimiter_log – name: cls_logs_demo_delimiter value: "|" – name: cls_logs_demo_keys value: "time,level,module,message"

十五、多行全文格式

env: – name: cls_logs_demo value: stdout – name: cls_logs_demo_log_type value: multiline_log – name: cls_logs_demo_beginning_regex value: "\\\\d{4}-\\\\d{2}-\\\\d{2}"

十六、完全正则格式

env: – name: cls_logs_demo value: stdout – name: cls_logs_demo_log_type value: fullregex_log – name: cls_logs_demo_log_regex value: "(\\\\d{4}-\\\\d{2}-\\\\d{2} \\\\d{2}:\\\\d{2}:\\\\d{2}) (\\\\w+) (.*)" – name: cls_logs_demo_keys value: "time,level,message"

注意：说明：

注意：在 YAML 双引号字符串中，反斜杠需要双重转义。例如正则 \\d{4} 在 YAML 中应写为 "\\\\d{4}"。如果使用单引号或无引号的 YAML 字符串，则只需单个反斜杠。

十七、验证采集结果

1. 部署或更新工作负载后，等待约30秒完成解析和 LogConfig CR 创建。

2. 登录 容器服务控制台，在左侧导航栏中选择集群。在集群列表中，单击目标集群 ID，进入集群详情页。选择左侧导航栏中的日志，在日志采集页签预期输出中可看到名称格式为 cls-env-{namespace}-{workload}-{key} 的采集配置。

3. 登录 CLS 控制台，在日志检索页面选择对应 Topic，查看是否有日志数据上报。

十八、环境变量完整参数

以下列出所有支持的环境变量参数。所有参数均以 cls_logs_{key}_ 为前缀（{key} 为你自定义的采集规则标识名）。

注意：说明：

注意：关于 {key}：可参见 { key } 说明。

十九、基础配置

20、日志主题配置

日志主题（Topic）和日志集（Logset）的创建分为两种方式。

21、方式一：自动创建（推荐）

不指定 _topic_id 时，系统将自动创建日志集和日志主题，并使用以下命名规则：

·日志集名称：k8s-<cluster-id>（按集群 ID 自动命名）。

·日志主题名称：{namespace}-{key}（按命名空间和 key 自动命名）。

注意：说明：

注意：如果你希望日志主题和日志集的名称与业务有清晰的语义对应关系，建议使用自动创建模式。系统会基于集群 ID、命名空间和采集规则标识（key）自动生成有语义的名称，便于后续管理和检索。

自动创建时，支持通过以下环境变量自定义日志主题属性：

22、方式二：指定已有日志主题

如果你已有日志主题，可以通过 _topic_id 直接指定该 Topic 的 ID，日志将投递到该已有 Topic。此时，上述自动创建相关参数（_period、_partition_count）均不生效。

23、解析规则配置

24、过滤配置

25、采集范围与标签

26、系统固定配置项（不可修改）

以下配置由系统自动设定，不支持通过环境变量修改：

注意：索引配置仅在自动创建 Topic 时生效。