一、前提条件
·已创建 Kubernetes 1.10及以上版本集群。
·已安装 kubectl，并且 kubectl 可正常访问集群。
·已配置自建 K8s 采集所需的云 API 权限，详情请参见 使用自建 K8s 上传数据 文档。
·已获取日志主题所在地域（region）。详细 CLS 地域列表请参见 可用地域 文档。
·已获取访问 CLS 侧鉴权所需的 API 密钥 ID（secretid）以及 API 密钥 Key（secretkey），可前往 API 密钥管理 查看。
二、安装 LogListener
注意：依赖：
1. 安装 Helm。
安装详情可参见 安装 Helm。
2. 安装 LogListener。
通过以下命令，将以 DaemonSet 的方式在 Kubernetes 集群中运行采集组件。若不希望在 Master 节点部署采集组件，请在安装命令中显式指定 –on_master false。若不指定 –on_master，采集组件可能部署到 Master 节点。若需将采集组件运行在 Master 节点中，请参见 Master 节点部署 LogListener。
2.1 下载相关脚本。
wget https://mirrors.tencent.com/install/cls/k8s/addon-charts/tencentcloud-cls-k8s.sh
2.2 赋予脚本执行权限。
# 仅支持Linux 环境， 不支持 MacOS！chmod +x tencentcloud-cls-k8s.sh
2.3 安装脚本。
·内网安装
./tencentcloud-cls-k8s.sh install –region ap-xxxxxx –secretid xxx –secretkey xxx –network intra –on_master false
·外网安装
./tencentcloud-cls-k8s.sh install –region ap-xxxxxx –secretid xxx –secretkey xxx –network internet –on_master false
参数说明如下：
| 参数名 | 是否必填 | 类型描述 |
| secretid | 是 | 云 API 密钥 的一部分，SecretId 用于标识 API 调用者身份。请确保云 API 密钥关联的账号具有相应的 自建 K8s 日志采集上传权限。 |
| secretkey | 是 | 云 API 密钥 的一部分，SecretKey 是用于加密签名字符串和服务器端验证签名字符串的密钥。请确保云 API 密钥关联的账号具有相应的 自建 K8s 日志采集上传权限。 |
| region | 是 | 目标 CLS 服务地域，地域详情请参见 可用地域，例如：ap-guangzhou。 |
| network | 否 | 表示 LogListener 通过哪种方式访问服务域名，取值：intra 内网访问（默认），internet 外网访问。内网访问：适用于集群所在服务器为腾讯云服务器，且服务器所在地域与目标访问 CLS 地域一致。外网访问：适用于集群所在服务器为非腾讯云服务器，或服务器所在地域与目标访问 CLS 地域不一致。 |
| docker_root | 否 | 集群 Docker 的根目录，默认是/var/lib/docker，如果集群不是这个默认目录，需要指定具体的 Docker 的根目录。 |
| cluster_id | 否 | K8s 集群安装 LogListener 后将自动在 CLS 创建一个相应的机器组，你可通过配置 cluster_id 来指定该机器组的名称，如果不指定，在安装期间会生成一个默认 ID（最好指定一个 cluster_id，默认生成的 ID 的可读性较差）。注意：指定的 cluster_id 不可以与已有机器组名称相同。 |
| local_region | 否 | K8s 集群所在地域， 默认赋值与 region 参数一致，若 K8s 集群所在地域与 region 不一致， 可自定义修改。 |
| api_network | 否 | 云 API 使用内网还是外网，取值：intra 内网访问，internet 外网访问（默认）。仅在专线接入场景下需关注。 |
| api_region | 否 | 云 API 的地域。仅在专线接入场景下需关注， 默认赋值与 region 参数一致。 |
| namespace | 否 | 指定安装日志采集组件的 namespace。若不指定，默认为 kube-system（一般不需要特别指定）。 |
| label | 否 | 支持自定义日志采集组件所在 Pod 的 Pod Label。例如：假设希望为日志采集组件所在 Pod 配置 service=a, app=b 的 Pod Label，此处参数定义为 –label label.service=a,label.app=b |
| on_master | 否 | 是否允许在 Master 节点部署采集组件。设置为 false 时，采集组件不部署到 Master 节点；设置为 true 或不指定该参数时，不添加排除 Master 节点的调度规则，采集组件可能部署到 Master 节点。若希望采集组件仅部署在非 Master 节点，请显式设置 –on_master false。 |
| enable_metrics | 否 | 安装时是否安装 metric 采集组件，默认为 false，即默认不安装 metric 组件。 |
| immutable_rootfs | 否 | 当节点根文件系统只读或 LogListener 报 read-only file system 错误时，设为 true。此时数据目录会从默认的 /usr/local/loglistener 改为可写的 /var/lib/loglistener。默认为 false。 |
3. 验证安装。
3.1 查看安装 Helm 包。安装成功后，查看 Helm 安装 tencent-cloud-cls-log。
helm list -n kube-system
3.2 查看组件。使用以下命令查看组件是否都启动正常，正常情况下，会启动一个 cls-provisioner 的 Pod，并在每个可调度的节点上各启动一个 tke-log-agent 的采集 Pod。
kubectl get pods -o wide -n kube-system | grep tke-log-agentkubectl get pods -o wide -n kube-system | grep cls-provisioner
3.3 验证采集组件的节点分布。通过上一步输出结果中的 NODE 列查看 tke-log-agent Pod 所在节点。如果安装时设置了 –on_master false，请确认 Master 节点上没有运行 tke-log-agent Pod。你还可以执行以下命令，查看 DaemonSet 的期望副本数和实际可用副本数：
kubectl get daemonset tke-log-agent -n kube-system
三、配置日志采集
完成 LogListener 安装后， 你即可通过以下两种方式中的任意一种为集群中的日志配置采集。
·控制台交互式配置自建 K8s 日志采集，详情请参见 使用控制台配置自建 K8s 集群日志采集。
·通过编写 CRD YAML 文件配置 K8s 日志采集，详情请参见 使用 CRD 配置自建 K8s 集群日志采集。
四、配置 LogListener
若要修改 LogListener 的配置（例如最大内存占用）， 可参见以下步骤修改：
1. 执行以下 kubectl 命令修改 tke-log-agent 环境变量。
kubectl edit ds tke-log-agent -n kube-system
2. 通过新增环境变量定义 LogListener 配置。
参数说明如下：
| 变量名 | 变量描述 |
| MAX_CONNECTION | 最大连接数，默认10。 |
| CHECKPOINT_WINDOW_SIZE | 单个文件的 checkpoint 环长度，默认1024。 |
| MAX_FILE_BREAKPOINTS | 位点文件大小，N*2k，N 默认8k。 |
| MAX_SENDRATE | 最大发送速率，Bytes/s，默认不限制。 |
| MAX_FILE | 最大监控文件数量，默认15000。 |
| MAX_DIR | 最大监控目录数量，默认5000。 |
| MAX_HTTPS_CONNECTION | HTTPS 最大连接数，默认100。 |
| CONCURRENCY_TASKS | LogListener 任务池，默认256 。该配置仅在 LogListener v3.0.0及以上版本支持。说明：LogListener v3.0.0及以上版本为白名单供应，若有需要请 提交工单 申请使用。 |
| PROCESS_TASKS_EVERY_LOOP | 单次循环处理任务数，默认4。 |
| CPU_USAGE_THRES | LogListener 最大 CPU 利用率，默认与 LogListener 容器的 CPU Limit 保持一致。 |
| MAX_MEM | 最大内存占用上限，默认与 LogListener 容器的内存 Limit 保持一致。单位：Bytes。 |
| MAX_SEND_RETRY_TIME | 日志上传请求失败并重试时，最大超时时间（s）， 默认为10800。 |
五、升级 LogListener
1. 升级前需重新拉取最新版本的安装脚本，以获取最新的采集器组件：
wget https://mirrors.tencent.com/install/cls/k8s/addon-charts/tencentcloud-cls-k8s.shchmod +x tencentcloud-cls-k8s.sh
2. 执行以下命令升级
./tencentcloud-cls-k8s.sh upgrade –region ap-xxxxxx –<options>
参数说明：
| 参数 | 参数说明 |
| region | 目标 CLS 服务地域，详见产品支持的 地域列表。 |
| upgrade_metrics | 升级时是否安装 metric 采集组件。不指定该参数时，保持升级前的原有状态（原来已安装则保留，未安装则不安装）；如需显式开启或关闭，可传入 true 或 false。 |
| namespace | 日志采集组件安装的 namespace，默认安装在 kube-system，一般不需要特殊指定。 |
六、查看/更新 LogListener 密钥
自建 Kubernetes 安装部署 LogListener 后，会将用户指定的 secretid 和 secretkey 保存在 Kubernetes 集群的 configmap 中。
你可通过执行以下命令查看密钥：
kubectl get configmap -n kube-system cls-credential
若要修改密钥，直接编辑修改 configmap 中的密钥和过期时间即可，组件会自动更新密钥。
七、卸载 LogListener
使用下面命令可以卸载已经安装的 tencent-cloud-cls-log helm 包， 其中 -n 为 LogListener 所在的命名空间，通常为 kube-system。
helm uninstall tencent-cloud-cls-log -n kube-system
如果想要完全删除 tencent-cloud-cls-log 包，还需执行以下命令删除相关 secret 配置，其中 -n 为 LogListener 所在的命名空间，通常为 kube-system。
kubectl delete secret -n kube-system cls-k8s
八、Master 节点部署 LogListener
安装时显式设置 –on_master false 后，采集组件不会部署到 Master 节点。若需要在 Master 节点运行采集组件，可在安装时设置 –on_master true。对于已经安装且当前排除了 Master 节点的集群，也可参见以下步骤调整 tke-log-agent 的 DaemonSet 声明文件。
1. 执行以下 kubectl 命令修改 tke-log-agent 声明文件。
kubectl edit ds tke-log-agent -n kube-system
2. 删除以下图中的 affinity 配置项，并根据 Master 节点的污点情况处理 tolerations 配置项：若 Master 节点不存在污点，可一并删除 tolerations；若 Master 节点存在污点，请保留 tolerations，并按下方说明配置。
注意：若 Master 节点存在污点，请勿删除 tolerations 配置项，需将配置中的 key 字段值替换为该 Master 节点的污点 key，否则采集组件可能无法调度到该 Master 节点。污点的查找方法请参见下文。
注意：
查找 Master 节点污点的步骤如下：
2.1 找到 Master 节点的名称。Master 节点通常带有 control-plane 或 master 的标签。
kubectl get nodes -l node-role.kubernetes.io/control-plane# 或者旧版本集群kubectl get nodes -l node-role.kubernetes.io/master
2.2 查看该节点的详细信息。将 <node-name> 替换为上一步查到的节点名称。
kubectl describe node <node-name>
2.3 在输出中查找 Taints 部分，此处会列出所有的污点，示例如下：
Taints: node-role.kubernetes.io/control-plane:NoSchedule node.kubernetes.io/not-ready:NoSchedule
九、自定义部署时的进程守护要求
若你使用 CLS 提供的标准安装脚本 tencentcloud-cls-k8s.sh 部署采集组件，进程守护能力已内置，无需额外配置。
若你存在以下任一情况，则必须参照本节完成进程守护配置，否则可能出现日志采集静默中断：
·基于 LogListener 镜像自定义容器启动入口（entrypoint）。
·自行编写 DaemonSet 声明文件部署 LogListener。
·将 LogListener 与业务进程部署在同一个 Pod 中。
注意：当日志上传速率持续低于日志生产速率时，LogListener 的 checkpoint 环形缓冲区会被写满，此时 LogListener 会主动退出以释放资源，并依赖部署环境将其重新拉起，拉起后自动从断点继续上传，日志不会丢失。若部署环境不具备进程自动拉起能力，LogListener 退出后将不再运行，该节点的日志采集会静默中断且无任何报错。
十、要求1：LogListener 必须是容器主进程
容器的重建依赖主进程（PID 1）的退出。若你使用自定义脚本作为容器入口，必须通过 exec 将 LogListener 提升为主进程，使其退出时容器同步退出，从而被 Kubernetes 重建。
错误写法：LogListener 在后台运行，其退出不会导致容器退出，Kubernetes 无法感知，重启策略失效。
#!/bin/bash# 错误示例：LogListener 退出后容器仍在运行，不会被重建/usr/local/loglistener/loglistener &tail -f /dev/null
正确写法：使用 exec 让 LogListener 接管 PID 1。
#!/bin/bash# 此处可执行所需的初始化逻辑# 正确示例：exec 使 LogListener 成为容器主进程exec /usr/local/loglistener/loglistener "$@"
注意：说明：
注意：若入口脚本必须常驻（例如需在同一容器内管理多个子进程），请在脚本中实现子进程状态监听与自动拉起逻辑，或改用支持进程守护的进程管理器（如 supervisord、tini 等），并确保 LogListener 异常退出时会被重新拉起。
十一、要求2：配置容器重启策略
DaemonSet 的 Pod 重启策略需为 Always。该值为 Kubernetes 默认值，请勿显式修改为 OnFailure 或 Never。
spec: template: spec: restartPolicy: Always
十二、要求3：配置存活探针
为 LogListener 容器配置存活探针（livenessProbe），当 LogListener 进程已不存在但容器仍未退出时，由 Kubernetes 重建容器。
livenessProbe: exec: command: – /bin/sh – -c – pgrep -x loglistener > /dev/null initialDelaySeconds: 30 periodSeconds: 30 failureThreshold: 3
十三、验证部署是否满足守护要求
在任意一个采集节点上执行以下命令，手动结束 LogListener 进程，观察其是否被自动拉起。
kubectl exec -it <tke-log-agent-pod> -n kube-system -c loglistener — pkill -9 loglistener
等待1分钟后，执行以下命令查看 Pod 状态。若 RESTARTS 计数增加且 Pod 重新进入 Running 状态，说明进程守护配置生效。
kubectl get pods -n kube-system -o wide | grep tke-log-agent
注意：建议同时配置采集异常告警，以便在采集中断时及时感知。配置方法请参见 LogListener 采集延迟告警配置。
十四、排障 LogListener
可参见 自建 K8s 日志采集排查指南 文档。