Grafana Loki 1.x 版本升级指南：配置核对、破坏性变更与安全升级路径

Grafana Loki 1.x 版本升级指南配置核对、破坏性变更与安全升级路径【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki本指南以 Loki 官方文档中的《Upgrade Loki 1.x versions》为骨架系统梳理从 1.4.0、1.5.0 到 1.6.0 各版本升级时必须关注的破坏性变更包括配置项重命名、CLI 参数调整、Docker 镜像运行用户与数据目录变化、schema 周期强制 24h、Promtail 标签变更、以及 ingester ring 的强制升级路径。读完本文你将掌握如何用-print-config-stderr快速 diff 两版本配置、如何逐版本按顺序安全升级微服务与单二进制部署并能对照源码理解这些变更背后的设计动机。升级前的通用原则与配置核对方法Loki 官方在兼容性上投入了大量工作绝大多数升级是低风险、低摩擦的。但软件总有取舍当易用性与可维护性发生冲突时维护团队会优先保证长期可维护性并把这些可能导致升级困难的点显式记录在升级文档中。两个核心建议尽量保持版本最新并做顺序升级跨多个大版本的跳跃会放大意外问题的概率。如果确实要跳过若干版本务必先在开发环境验证再动生产环境。升级前先核对配置差异任何一次升级前都应该用工具对比新旧版本对同一配置文件的解析结果。用 Docker 一键 diff 两个版本的配置解析结果文档给出的方法非常实用利用 Loki 的-print-config-stderr参数把最终生效的完整内部配置结构打印到 stderr再对两个版本的输出做 diff。export OLD_LOKI2.9.4 export NEW_LOKI3.0.0 export CONFIG_FILElocal-config.yaml diff --coloralways --side-by-side (docker run --rm -t -v ${PWD}:/config grafana/loki:${OLD_LOKI} -config.file/etc/loki/${CONFIG_FILE} -print-config-stderr 21 | sed /Starting Loki/q | tr -d \r) (docker run --rm -t -v ${PWD}:/config grafana/loki:${NEW_LOKI} -config.file/etc/loki/${CONFIG_FILE} -print-config-stderr 21 | sed /Starting Loki/q | tr -d \r) | less -R命令要点说明-v ${PWD}:/config把当前目录挂载进容器-config.file/etc/loki/${CONFIG_FILE}指向被挂载的配置文件-print-config-stderr让 Loki 在启动前把最终合并后的内部配置结构体整体打印出来随后用sed /Starting Loki/q截断后续启动日志tr -d \r删除回车符主要针对 WSL2 环境可能混入的 Windows 换行符绝大多数 Linux 环境并不需要输出非常冗长因为它展示的是运行 Loki 所需的整个内部配置结构。你可以自行调整diff的参数例如只显示变化行的diff -u以得到更精简的对比结果。用新版二进制直接校验配置是否合法对于某个具体的新版本下载对应二进制后直接带配置文件运行即可立即暴露非法配置./loki-linux-amd64 -config.filemyconfig.yaml如果存在已删除或改名的字段启动阶段会立刻报错例如./loki-linux-amd64 -config.fileloki-local-config.yaml failed parsing config: loki-local-config.yaml: yaml: unmarshal errors: line 35: field dynamodbconfig not found in type aws.StorageConfig这个报错明确指向aws.StorageConfig类型中已不存在的dynamodbconfig字段对照变更列表即可知道应改为dynamodb。这种启动即报错的行为正是 Loki 配置校验的兜底手段配合上面的 docker diff 方法可以做到升级前对配置变更心中有数。1.6.0端口、微服务滚动顺序与 Promtail 标签变更1.6.0 是 1.x 系列中变更最密集的版本涉及运行身份、微服务滚动策略、Promtail 标签、schema 校验、CLI 参数与 canary 指标六大方面。Ksonnet 端口从 80 改为 3100Docker 镜像移除 NET_BIND_SERVICE 能力背景1.5.0 起 Loki 进程不再以 root 运行这导致无法直接绑定 80 等低端口。当时的解法是在镜像内通过setcap cap_net_bind_serviceep /usr/bin/loki给进程追加能力使其能以非 root 用户绑定 1024 以下端口。这个方案在实践中引发了很多问题因此 1.6.0 通过 PR 2294 移除了该能力现在使用官方 Docker 镜像启动 Loki 时监听端口不能小于 1024Helm 默认端口一直是 3100只要没有改过默认值Helm 用户不受影响Ksonnet 用户必须仔细检查配置PR 2294 将 loki 端口从 80 改成了 3100。微服务模式下的强制滚动顺序先升级所有 ingester1.6.0 为 ingester 新增了 GRPC API用于加速 metric 查询。为保证滚动期间查询不报错文档给出明确指令务必先升级全部 ingester再升级其余组件。原因是升级后的 querier 会调用 ingester 上的新方法。如果一次性全部滚动新 querier 会去查询仍运行旧代码、尚未暴露新 API 的 ingester导致查询失败。该影响只发生在读取查询路径不影响写入且只在滚动升级期间存在。Promtail 抓取配置标签变更instance - podcontainer_name - containerLoki PR 2091由 jsonnet-libs PR 261 触发对 Helm 与 Ksonnet 两套 Promtail 抓取配置做了标签调整使instance标签在单个抓取配置内真正唯一并新增pod与container目标标签便于和 cAdvisor、KSMkube-state-metrics、Kubelet 暴露的指标做 join移除container_name标签——它与container等价且container_name在 Kubernetes 1.16 已被废弃继续使用将无法与上述指标直接 join。TL;DRHelm 与 Ksonnet 的 Promtail 抓取配置中以下标签被改名instance-podcontainer_name-container如果你在 Grafana 面板或告警规则中引用过instance/container_name这两个标签升级后需要同步调整查询表达式。实验性 boltdb-shipper索引周期强制为 24hPR 2166 起boltdb-shipper 索引周期被强制要求正好是24h。如果当前生效的 schema或即将生效的 schema不是 24h 周期Loki 将拒绝启动并报错。可以在 schema_config 中追加一个新的未来生效条目来平滑过渡schema_config: configs: - from: 2020-01-01 ----- 这是你当前的条目日期会不同 store: boltdb-shipper object_store: aws schema: v11 index: prefix: index_ period: 168h - from: [INSERT FUTURE DATE HERE] ----- 新增一条填一个未来日期 store: boltdb-shipper object_store: aws schema: v11 index: prefix: index_ period: 24h --- 这里必须是 24h注意事项新条目的from日期必须是一个未来日期如果当前时区已经过了 UTC 午夜则还要再往后推一天如果你还没用schema: v11这正好是随新 schema 条目一起升级的好时机建议先把period: 24h的新条目加进配置并确认启动正常再等待日期切换。这条校验逻辑在当前仓库源码中依然可循在 pkg/storage/config/schema_config.go 中PeriodConfig.validate()对 TSDB 索引类型强制校验IndexTables.Period必须等于ObjectStorageIndexRequiredPeriod24h否则返回errTSDBNon24HoursIndexPeriodtsdb must always have periodic config for index set to 24h表周期校验则要求周期必须是 24h 的倍数否则报errInvalidTablePeriod。除周期外boltdb-shipper 内部还有一次大重构Loki 不再更新已存在的索引文件而是每 15 分钟创建一个新的索引文件。这一行为变化对用户不可见但非常重要——它保证了对象存储中的对象不可变immutable为后续的 compaction压缩与 deletion删除等操作扫清了障碍。由于该功能当时仍属实验性质文档也提醒出现 bug 是可能的。破坏性 CLI 参数改名以下 CLI 参数在 1.6.0 中为统一命名风格而改名文档判断它们不会被广泛使用- querier.query_timeout querier.query-timeout - distributor.extra-query-delay querier.extra-query-delay - max-chunk-batch-size store.max-chunk-batch-size - ingester.concurrent-flushed ingester.concurrent-flushes注意最后一组concurrent-flushed过去式改为concurrent-flushes现在式。如果你在启动脚本或 systemd unit 中写入了旧参数名需要同步更新。Loki Canary 指标命名规范修正在给 canary 添加新功能时发现原有指标名不符合 Prometheus counter 命名规范counter 应以_total结尾。以下指标在 1.6.0 被重命名loki_canary_total_entries - loki_canary_entries_total loki_canary_out_of_order_entries - loki_canary_out_of_order_entries_total loki_canary_websocket_missing_entries - loki_canary_websocket_missing_entries_total loki_canary_missing_entries - loki_canary_missing_entries_total loki_canary_unexpected_entries - loki_canary_unexpected_entries_total loki_canary_duplicate_entries - loki_canary_duplicate_entries_total loki_canary_ws_reconnects - loki_canary_ws_reconnects_total loki_canary_response_latency - loki_canary_response_latency_seconds从当前仓库源码看这些指标定义位于 pkg/canary/comparator/comparator.go命名空间统一为loki_canary例如entries_total、out_of_order_entries_total、websocket_missing_entries_total、missing_entries_total、unexpected_entries_total、duplicate_entries_total以及 histogram 类型的response_latency_secondsWebSocket 重连次数ws_reconnects_total则定义在 pkg/canary/reader/reader.go。如果你为 canary 配了 Grafana 告警或面板升级后需改用新名称。Ksonnetstorage_backend 不再提供默认值在 production/ksonnet/loki/config.libsonnet 中storage_backend原本默认是bigtable,gcs1.6.0 改为不提供默认值未显式指定就直接报错。因为默认值对使用其他存储后端的用户极具误导性最终会以晦涩的 bigtable 错误形式暴露出来。若想保持与旧默认相同的行为namespace 与 cluster 需已定义在环境 jsonnet 中添加_config:: { namespace: loki-dev, cluster: us-central1, storage_backend: gcs,bigtable, }1.5.0Cortex 升级、Docker 运行身份与路径变更破坏性配置变更Cortex v1.0.0 的配置清理1.5.0 内嵌了 Cortex v1.0.0其中包含大量变更。CLI 参数变化同样会影响 Loki但官方通常推荐优先使用配置文件。Cortex 对配置文件做了大量清理升级前强烈建议先阅读其 annotated diffconfig file breaking changes。在 YAML 配置中以下字段被整体移除claim_on_rollout行为固定为 truenormalise_tokens行为固定为 true。验证配置是否受影响的最快方式下载 1.5.0或更新版本的二进制直接带现有配置运行./loki-linux-amd64 -config.filemyconfig.yaml出现类似下面这类failed parsing config错误即说明字段已失效./loki-linux-amd64 -config.fileloki-local-config.yaml failed parsing config: loki-local-config.yaml: yaml: unmarshal errors: line 35: field dynamodbconfig not found in type aws.StorageConfig对照变更列表即可修复例如- dynamodbconfig: dynamodb:同时多个 AWS 相关配置也一并变更需要同步更新。Docker 镜像进程不再以 root 运行出于安全考虑1.5.0 起 Docker 容器内的 loki 进程不再以 root 运行而是以用户lokiUID10001、GID10001运行。这会从两个维度影响使用者端口如果配置的监听端口大于 1024默认 HTTP 3100、GRPC 9095端口方面一切正常如果配置的监听端口小于 1024Linux 通常要求 root 权限1.5.0 镜像通过setcap cap_net_bind_serviceep /usr/bin/loki让非 root 进程也能绑定低端口但并非所有环境都允许该 capability——部分环境会限制它。一旦受限就只能把 HTTP/GRPC 端口配置到 1024 以上。文件系统数据目录从 /tmp/loki 迁移到 /loki⚠️Docker 镜像内 Loki 查找文件的位置发生了变化针对镜像内置配置文件而言。1.4.0 及更早版本容器内置配置使用的是/tmp/loki/index /tmp/loki/chunks1.5.0 起改为/loki/index /loki/chunks当前仓库中 cmd/loki/loki-docker-config.yaml 也印证了这一点common.path_prefix为/lokichunks 目录为/loki/chunks而面向本地开发场景的 cmd/loki/loki-local-config.yaml 仍使用/tmp/loki作为path_prefix与 chunks 目录。这对使用 docker-compose 或 docker volume 持久化数据的人影响最大需要关注两件事文件归属ownership是否正确以及挂载点是否更新到新路径。一个完整的迁移示例旧命令使用 1.4.0 并挂载loki-data到/tmp/lokidocker stop loki docker rm loki docker run --rm --nameloki-perm -it --mount sourceloki-data,target/mnt ubuntu /bin/bash cd /mnt chown -R 10001:10001 ./* exit docker run -d --nameloki --mount sourceloki-data,target/loki -p 3100:3100 grafana/loki:1.5.0注意新命令中挂载目标改成了target/loki对应镜像内置配置的新数据目录。中间用 ubuntu 镜像改属主的步骤并非必须如果你能直接访问这些文件例如有权限进入/var/lib/docker/volumes或数据挂载在本地文件系统目录也可以直接在宿主机上执行chown -R 10001:10001 数据目录完成权限修正。Duration 配置必须带单位如果你在 1.5.0 遇到如下报错./loki-linux-amd64-1.5.0 -log.leveldebug -config.file/etc/loki/config.yml failed parsing config: /etc/loki/config.yml: not a valid duration string: 0原因是底层变更后不再允许不带单位的 duration。YAML 解析器不会给出具体行号但最可能是下面这两处值即使为 0 也必须写单位chunk_store_config: max_look_back_period: 0s # DURATION VALUES MUST HAVE A UNIT EVEN IF THEY ARE ZERO table_manager: retention_deletes_enabled: false retention_period: 0s # DURATION VALUES MUST HAVE A UNIT EVEN IF THEY ARE ZEROPromtail 配置变更backoff 参数改名Promtail 依赖的 backoff 库发生了配置变更最初未被写进 release notes。若遇到如下错误Unable to parse config: /etc/promtail/promtail.yaml: yaml: unmarshal errors: line 3: field maxbackoff not found in type util.BackoffConfig line 4: field maxretries not found in type util.BackoffConfig line 5: field minbackoff not found in type util.BackoffConfig请将旧参数改为新名称min_period: max_period: max_retries:1.4.0ring 规范化与强制升级路径Loki 1.4.0 内嵌 Cortex v0.7.0-rc.0其中包含若干破坏性配置变更cache_config中defaul_validity改名为default_validity注意拼写default而非defaul不再支持通过命令行参数配置 schema只支持配置文件方式官方文档此前也从未把该方式作为选项提供大概率无人使用。其余配置变更与 Loki 无关可以忽略。必须执行的升级路径ring 的 de-normalized tokens新内嵌的 Cortex 移除了 ring 中 de-normalized tokens 相关代码。理解前提下文所说的shared ring指在以下配置中使用了consul 或 etcd作为存储后端kvstore: # The backend storage to use for the ring. Supported values are # consul, etcd, inmemory store: string按你的情况对照未使用 shared ringinmemory无需任何操作使用 shared ring 且从 v1.3.0 - v1.4.0无需任何操作使用 shared ring 且从低于 v1.3.0 的版本如 v1.2.0- v1.4.0必须执行下述操作。如果你不在 v1.3.0 且使用 shared ring二选一方案一推荐先升级到 v1.3.0再升级到 v1.4.0。方案二单二进制部署时按以下顺序操作给 ingester 命令添加参数-ingester.normalise-tokenstrue用该参数重启所有 ingester继续升级到 v1.4.0待全部组件都运行 v1.4.0 后移除该参数。该参数也可以通过配置文件启用参见lifecycler_config配置项。使用 Helm Loki chart 时extraArgs: ingester.normalise-tokens: true使用 Helm Loki-Stack chart 时loki: extraArgs: ingester.normalise-tokens: true不按路径升级会发生什么如果 v1.4.0 的 ingester 加入一个由 v1.2.0 或更早版本创建的 ring且未带-ingester.normalise-tokenstrue也未通过配置文件启用它会因为看不到其他 ingester 而把 ring 中所有其他 ingester 的条目全部清除。后果是 distributor 无法写入系统整体写入ingestion失败。一旦发生立即回滚部署尽快把 v1.4.0 的 ingester 从 ring 中移除让存量 ingester 重新注册各自的 token同时移除 v1.4.0 的 distributor——它们同样无法理解旧 ring继续存在会导致流量转发失败。升级路线图总结与检查清单把三个版本的关键动作汇总如下方便升级前逐项核对版本关键变更需采取的动作1.4.0ring 移除 de-normalized tokens非 1.3.0 且用 shared ringconsul/etcd先升 1.3.0或先给 ingester 加-ingester.normalise-tokenstrue再升级cache_config.defaul_validity-default_validityschema 不再支持命令行配置1.5.0Docker 进程不再以 root 运行UID/GID 10001端口 1024 依赖cap_net_bind_service受限环境改到 1024数据目录/tmp/loki-/loki更新挂载点并chown属主1.5.0Cortex v1.0.0 配置清理移除claim_on_rollout/normalise_tokensAWS 相关字段改名如dynamodbconfig-dynamodbduration 必须带单位Promtail backoff 参数改为min_period/max_period/max_retries1.6.0镜像移除 NET_BIND_SERVICEKsonnet 端口 80 - 3100端口不能小于 1024Ksonnet 用户改端口为 31001.6.0ingester 新增 GRPC API微服务模式先滚动升级全部 ingester再升级 querier 等其他组件1.6.0Promtail 标签变更instance-podcontainer_name-container同步调整查询与告警1.6.0boltdb-shipper 周期强制 24h追加未来日期的 schema 条目period: 24h未用 v11 可一并升级1.6.0CLI 参数改名querier.query-timeout、querier.extra-query-delay、store.max-chunk-batch-size、ingester.concurrent-flushes1.6.0canary 指标改名所有 counter 加_total后缀response_latency-response_latency_seconds1.6.0ksonnetstorage_backend无默认值环境 jsonnet 中显式指定如storage_backend: gcs,bigtable最后再强调一遍通用原则尽量保持版本最新并顺序升级若要跨版本先在开发环境验证。每次升级前用文中第一节的-print-config-stderrdiff 方法或新版二进制试跑提前发现全部配置问题再按上表逐项处理即可把 1.x 升级的风险降到最低。【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考