Kubernetes系统日志完全指南：从基础到高级查询

Kubernetes系统日志完全指南：从基础到高级查询

website Kubernetes website and documentation repo: 项目地址: https://gitcode.com/gh_mirrors/webs/website

概述

在Kubernetes集群运维过程中，系统日志是诊断问题的重要依据。本文将全面解析Kubernetes系统日志的各个方面，包括日志格式、级别控制、存储位置以及高级查询技巧，帮助运维人员更好地理解和利用集群日志信息。

日志基础概念

Kubernetes系统组件日志记录了集群中发生的各种事件，对于调试和故障排查至关重要。日志的详细程度可以通过日志级别(verbosity)进行配置，从仅显示组件错误的粗粒度日志，到记录HTTP访问日志、Pod状态变更、控制器动作等详细跟踪信息的细粒度日志。

重要提示：与命令行参数不同，日志输出格式本身不受Kubernetes API稳定性保证，不同版本间的日志条目和格式可能会发生变化。

klog日志库

klog是Kubernetes的核心日志库，负责为系统组件生成日志消息。随着Kubernetes的发展，日志系统也在不断演进和简化。

废弃的klog参数

从Kubernetes 1.23版本开始，以下klog命令行参数已被标记为废弃，并在1.26版本中完全移除：

• --add-dir-header
• --alsologtostderr
• --log-backtrace-at
• --log-dir
• --log-file
• --log-file-max-size
• --logtostderr
• --one-output
• --skip-headers
• --skip-log-headers
• --stderrthreshold

现在，日志输出总是写入stderr，输出重定向由调用Kubernetes组件的工具(如POSIX shell或systemd)处理。

特殊环境处理

在某些特殊环境中(如无发行版容器或Windows系统服务)，无法使用上述重定向方法。此时可以使用kube-log-runner二进制文件作为Kubernetes组件的包装器来重定向输出。

下表展示了kube-log-runner与shell重定向的对应关系：

| 使用场景 | POSIX shell命令 | kube-log-runner等效命令 | |---------|----------------|------------------------| | 合并stderr和stdout输出到stdout | 2>&1 | kube-log-runner | | 重定向到日志文件 | 1>>/tmp/log 2>&1 | kube-log-runner -log-file=/tmp/log | | 同时输出到日志文件和stdout | 2>&1 \| tee -a /tmp/log | kube-log-runner -log-file=/tmp/log -also-stdout | | 仅重定向stdout到日志文件 | >/tmp/log | kube-log-runner -log-file=/tmp/log -redirect-stderr=false |

日志格式详解

传统klog格式

传统klog格式示例：

I1025 00:15:15.525108       1 httplog.go:79] GET /api/v1/namespaces/kube-system/pods/metrics-server-v0.3.1-57c75779f-9p8wg: (1.512ms) 200 [pod_nanny/v0.0.0 (linux/amd64) kubernetes/$Format 10.56.1.19:51756]

日志消息可能包含换行符：

I1025 00:15:15.525108       1 example.go:79] This is a message
which has a line break.

结构化日志(Structured Logging)

结构化日志在Kubernetes 1.23版本进入beta阶段，它引入了统一的日志结构，便于信息的程序化提取和处理。

默认的结构化日志格式保持与传统klog的向后兼容：

<klog header> "<message>" <key1>="<value1>" <key2>="<value2>" ...

示例：

I1025 00:15:15.525108       1 controller_utils.go:116] "Pod status updated" pod="kube-system/kubedns" status="ready"

字符串会被引用，其他值使用%+v格式化，可能根据数据内容跨越多行。

上下文日志(Contextual Logging)

上下文日志构建在结构化日志之上，主要关注开发者如何使用日志调用。从Kubernetes 1.30版本开始，此功能默认启用。

开发者可以使用WithValues或WithName等函数在组件中添加额外信息，这些信息会通过调用者传递给函数。

示例输出：

I0222 15:13:31.645988  197901 example.go:54] "runtime" logger="example.myname" foo="bar" duration="1m0s"

其中logger键和foo="bar"由调用者添加，而duration="1m0s"由被调用函数提供。

JSON日志格式

JSON日志格式在Kubernetes 1.19版本作为alpha功能引入，通过--logging-format=json标志启用。

示例JSON日志(美化后)：

{
   "ts": 1580306777.04728,
   "v": 4,
   "msg": "Pod status updated",
   "pod":{
      "name": "nginx-1",
      "namespace": "default"
   },
   "status": "ready"
}

特殊字段说明：

• ts: Unix时间戳(必需，浮点数)
• v: 详细级别(仅用于info消息，整数)
• err: 错误字符串(可选)
• msg: 消息内容(必需)

目前支持JSON格式的组件包括：

• kube-controller-manager
• kube-apiserver
• kube-scheduler
• kubelet

日志级别管理

-v标志控制日志详细级别。提高该值会增加记录的事件数量，降低该值会减少记录的事件。较高的详细级别设置会记录较不严重的事件：

• 0级：仅记录关键事件
• 1-4级：逐渐增加详细程度
• 5级及以上：调试级别详细信息

日志存储位置

Kubernetes系统组件分为两类：

1. 容器中运行的组件：如调度器(scheduler)和kube-proxy，它们总是将日志写入/var/log目录下的.log文件中。

2. 非容器运行的组件：

   • 在使用systemd的系统上，kubelet和容器运行时将日志写入journald
   • 其他系统上，它们将日志写入/var/log目录下的.log文件

建议对/var/log目录中的系统组件日志进行轮转。在使用kube-up.sh脚本创建的集群中，日志轮转由logrotate工具配置，默认每天轮转一次或当日志大小超过100MB时轮转。

高级日志查询

Kubernetes 1.27引入了节点日志查询功能，允许查看节点上运行服务的日志。要使用此功能，需要确保：

1. 节点启用了NodeLogQuery特性门控
2. kubelet配置中enableSystemLogHandler和enableSystemLogQuery都设置为true

基本查询示例

获取节点node-1.example的kubelet日志：

kubectl get --raw "/api/v1/nodes/node-1.example/proxy/logs/?query=kubelet"

获取节点上的特定日志文件：

kubectl get --raw "/api/v1/nodes/node-1.example/proxy/logs/?query=/var/log/myapp.log"

查询选项

| 选项 | 描述 | |------|------| | boot | 从特定系统启动显示消息 | | pattern | 使用PERL兼容正则表达式过滤日志条目 | | query | 指定要返回日志的服务或文件(必需) | | sinceTime | 显示从指定RFC3339时间戳开始的日志 | | untilTime | 显示到指定RFC3339时间戳为止的日志 | | tailLines | 指定从日志末尾获取的行数(默认获取全部) |

复杂查询示例

获取节点node-1.example的kubelet日志中包含"error"的行：

kubectl get --raw "/api/v1/nodes/node-1.example/proxy/logs/?query=kubelet&pattern=error"

最佳实践

1. 日志轮转：确保配置适当的日志轮转策略，防止日志文件占用过多磁盘空间
2. 日志级别选择：生产环境通常使用较低的详细级别(如2-3)，调试时再提高级别
3. 结构化日志：新开发组件应优先使用结构化日志格式
4. 敏感信息：避免在日志中记录敏感信息，如密码或密钥
5. 长期存储：考虑使用集中式日志系统(如ELK)长期存储和分析日志

通过合理配置和利用Kubernetes的日志系统，运维人员可以更高效地监控集群状态、诊断问题并优化系统性能。

website Kubernetes website and documentation repo: 项目地址: https://gitcode.com/gh_mirrors/webs/website