使用 k3d 在本地部署 Lokitanka Helm 驱动的开发环境搭建完整指南【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki本文档聚焦于 Loki 仓库中 tools/dev/k3d/README.md 所描述的本地开发环境搭建方案通过 k3d 在单机 Docker 之上拉起轻量 Kubernetes 集群再借助 tankaJsonnet Helm 完成 Prometheus、Grafana 与 Loki 系列组件的部署。读完本文你将掌握如何一键启动单二进制、高可用单二进制、分布式三种 Loki 形态以及如何为 Enterprise Logs 部署完整的 tokengen/provisioner 密钥供给链路并能在本地快速复现、验证 Loki 各部署模式。一、这个开发环境解决什么问题Loki 是像 Prometheus 一样但面向日志的可观测性系统。在开发阶段开发者需要快速验证 Helm Chart 的渲染结果、多租户行为、查询链路与监控仪表盘。k3d 环境的核心价值在于轻量k3d 把 Kubernetes 跑在 Docker 容器里一条命令即可创建 1 个 server 3 个 agent 的集群可复现所有集群搭建、Chart 渲染、组件安装都被封装为 Makefile targetmake loki-distributed一行命令即可得到完整环境贴近生产环境通过官方 production/helm/loki Chart 安装组件验证的就是真实发布物而非简化玩具。从 tools/dev/k3d/Makefile 可以看到这套体系由prepare创建 registry 更新 helm 仓库 vendor charts、helm-cluster拉起 k3d 集群、tk applytanka 渲染并应用基础设施、helm install安装 Loki/Enterprise Logs四段流水线组成。二、前置条件与工具链使用本目录下的 Makefile target 前需要准备以下工具对应 tools/dev/k3d/README.md 的 Pre-requisites 清单工具用途版本要求kubectl与 k3d 集群交互、切换 context、应用 CRD无特殊要求k3d在 Docker 中创建 Kubernetes 集群与镜像仓库v4.4.8文档注明tanka基于 Jsonnet 的 Kubernetes 部署工具执行tk apply无特殊要求jsonnetJsonnet 语言解释器tanka 依赖无特殊要求jq解析 k3d 节点列表 JSON、读取 registry 端口无特殊要求helm安装/升级 Loki 相关 Chart 3.9注意如果 Docker 无法解析本地 k3d registry 的主机名需要在/etc/hosts中添加一行127.0.0.1 k3d-grafana这是因为create-registrytarget见 tools/dev/k3d/Makefile会创建名为grafana的 k3d registry默认端口为46453可通过REGISTRY_PORT变量覆盖集群内组件需要通过grafana.k3d.localhost访问该仓库。关于 Enterprise Logs 的额外要求如果目标环境是enterprise-logs/enterprise-logs-ha-single-binaryprepare-gel会额外执行secretstargettools/dev/k3d/Makefile L101-L119需要1Password CLIop且已op signin从 Grafana Labs Shared vault 拉取loki/grafana.jwt与loki/gel.jwt若没有 vault 权限可以自行准备 enterprise grafana license key 放到secrets/grafana.jwt、enterprise logs license key 放到secrets/gel.jwt——但可能需要修改部署配置使集群名与 license 匹配。三、环境总览一个 Makefile 管到底tools/dev/k3d/Makefile 是整套环境的入口。核心 target 如下Make target作用对应部署形态make lokiOSS Loki 默认形态默认 Chart 配置make loki-ha-single-binaryOSS Loki 高可用单二进制singleBinary.replicas: 3make loki-distributedOSS Loki 分布式各组件独立副本make enterprise-logsEnterprise Logs 默认形态多租户 provisionermake enterprise-logs-ha-single-binaryEnterprise Logs 高可用单二进制单二进制 3 副本make helm-cluster仅拉起空集群 Prometheus/Grafana供后续手动helm installmake down拆除全部环境k3d cluster delete helm-cluster公共变量与行为SLEEP集群操作后的等待秒数默认 5 秒可用make SLEEP10 loki-distributed覆盖DEBUG控制 helm 的--debug开关默认falsemake DEBUGtrue target开启详细输出REGISTRY_PORTregistry 端口默认优先复用已存在的k3d-grafana端口否则用46453。每个部署类 target 的内部流程以loki-distributed为例都是同构的make loki-distributed # 1) preparecreate-registry update-reposadd-repos、tk tool charts vendor、jb update # 2) helm-clusterscripts/create_cluster.sh helm-cluster port # 3) tk apply --ext-code enterprisefalse environments/helm-cluster # 4) sleep 5 # 5) helm install loki production/helm/loki -n loki --values .../values/loki-distributed.yaml四、快速上手启动与拆除环境4.1 启动分布式环境按 tools/dev/k3d/README.md 的说明每个环境都有自己的 make target启动loki-distributed只需make loki-distributed执行过程中scripts/create_cluster.shtools/dev/k3d/scripts/create_cluster.sh会完成k3d cluster create helm-cluster --servers 1 --agents 3 --registry-use k3d-grafana:port --wait读取 serverlb 的 6443 映射端口执行tk env set把 tanka 环境指向该集群kubectl config set-context k3d-helm-cluster切换 kubectl context创建k3d-helm-clusternamespace如果不存在预装 CRD由于 tanka 不会像 helm 那样先应用 helm chart 里的 CRD脚本会预先以 server-side apply 方式安装 Prometheus Operator 的 8 个 CRDmonitoring.coreos.com_*与 Grafana Agent 的 5 个 CRDmonitoring.grafana.com_*否则后续 helm 部署会因缺少 CRD 而失败。随后tk apply --ext-code enterprisefalse environments/helm-cluster通过 main.jsonnet 渲染并部署基础设施Prometheuskube-prometheus-stack、Grafana 9.5.1、以及自动配置好的 prometheus 与 loki 两个数据源。最后 helm 以 values/loki-distributed.yaml 安装分布式 Loki# 该 values 文件的核心要点 backend: replicas: 0 # 由各专用组件承担职责 read: replicas: 0 write: replicas: 0 singleBinary: replicas: 0 compactor: replicas: 1 enabled: true distributor: replicas: 1 indexGateway: replicas: 1 enabled: true ingester: replicas: 3 maxUnavailable: 1 querier: replicas: 3 maxUnavailable: 1 queryFrontend: replicas: 1 queryScheduler: replicas: 2 enabled: true ruler: replicas: 1 enabled: true minio: enabled: true # 使用 MinIO 作为对象存储后端可以看到分布式形态下 ingest 与 query 路径分别由 distributor/ingester 和 querier/query-frontend/query-scheduler 承担且启用了 indexGateway、compactor、ruler形成一套完整的读写分离架构。4.2 其他 OSS 形态高可用单二进制make loki-ha-single-binary对应 values/loki-ha-single-binary.yaml核心是singleBinary.replicas: 3以无状态方式水平扩展单二进制模式默认形态make loki使用 values/loki.yaml。4.3 拆除环境所有环境统一由downtarget 清理tools/dev/k3d/README.md 的 Tearing Down 一节make down其实现就是k3d cluster delete helm-cluster——删除集群即删除了其上所有 namespace、组件与数据本地环境一键归零。五、Helm 模式先集群、后安装helm-cluster环境专门用于把一个只有基础设施的集群拿出来再手动 helm install 想要的配置详见 environments/helm-cluster/README.md。它与其余环境的关键区别在于基础设施Prometheus、Grafana、数据源由 tanka 渲染部署但不安装任何 Loki 组件Loki/Enterprise Logs 完全通过 helm 手动安装因此 minio 由 helm chart 自己拉起适合验证 production/helm/loki Chart 的各种 values 组合。启动方式cd tools/dev/k3d make helm-cluster随后即可手动执行 helm 安装类 target例如make helm-install-loki # helm install loki使用 values/loki.yaml make helm-install-loki-ha-single-binary # release 名为 loki-single-binary make helm-install-loki-distributed # helm install loki使用 values/loki-distributed.yaml对应的升级与卸载 target 也已齐备helm-upgrade-loki*、helm-uninstall-loki*、helm-uninstall-loki-binary。Chart 依赖grafana、promtail、minio、kube-prometheus-stack、loki-distributed 等由 chartfile.yaml 声明update-repos中的tk tool charts vendor会将其 vendor 到本地charts/目录供 tanka 使用。基础设施层做了什么main.jsonnet 通过tanka.helm.new将 kube-prometheus-stack 渲染为 Jsonnet 对象并做了大量细节配置数据源自动注册loki_datasource默认指向http://loki-gateway.loki.svc.cluster.localOSS或http://enterprise-logs-gateway.loki.svc.cluster.localEnterprise启用 basic authOSS 模式下通过X-Scope-OrgID: loki请求头访问单租户Prometheus 数据源指向prometheus-kube-prometheus-prometheus:9090仪表盘挂载Grafana 通过 provisioning ConfigMap 加载loki-dashboards-1/loki-dashboards-2企业版为enterprise-logs-*支持在单二进制模式下通过configMap.withOptional(true)容忍无仪表盘的情况指标打标为 Prometheus、kube-state-metrics、node-exporter 的抓取添加clusterclusterName标签与instance重打标便于区分多集群指标企业版插件Enterprise 模式下注入grafana-enterprise-logs-app插件并用 initContainer 生成插件 provisioning 文件。六、Enterprise Logstokengen → provisioner 密钥供给链路部署 Enterprise Logs 的步骤tools/dev/k3d/README.md 的 Enterprise Logs 一节make helm-cluster make helm-install-enterprise-logs实际更完整的入口是make enterprise-logs它会依次执行 prepare-gel、helm-cluster、apply、helm-install-enterprise-logs。安装阶段会执行一组任务job它们之间存在明确的依赖顺序tokengen job生成 admin-api token将其存入对象存储MinIO并创建一个 Kubernetes secretgel-admin-tokenprovisioner job依赖 tokengen 生成的 secret 与 Admin API 的健康状态。它通过 Admin API 创建租户等 admin 资源每生成一个新 token 就创建一个新的 Kubernetes secret前缀provisioned-secret例如provisioned-secret-lokiLoki Canaries 与 Grafana 都依赖 provisioner 供给的 secret——因此 provisioner job 完成后这些组件才会转为 online。从 values/enterprise-logs.yaml 可以看到相关配置loki: querier: multi_tenant_queries_enabled: true # 开启多租户查询 enterprise: enabled: true adminToken: secret: gel-admin-token # tokengen 生成的 secret 名称 additionalNamespaces: - k3d-helm-cluster useExternalLicense: true # 使用外部 license externalLicenseName: gel-license # main.jsonnet 创建的 gel-license secret provisioner: provisionedSecretPrefix: provisioned-secret additionalTenants: - name: team-a # 额外租户 team-a namespace: k3d-helm-cluster read: legacyReadTarget: false minio: enabled: true在集群侧main.jsonnet 的 enterprise 分支还会创建gel-licensesecret内容来自secrets/gel.jwt、将 Grafana 换成grafana/grafana-enterprise:9.5.1并注入企业 license同时把GEL_ADMIN_TOKEN、PROVISIONED_TENANT_TOKEN等环境变量挂入 Grafana 容器形成完整的租户凭据闭环。高可用单二进制企业版对应make enterprise-logs-ha-single-binaryvalues 文件为 values/enterprise-logs-ha-single-binary.yaml即企业版配置加上singleBinary.replicas: 3。七、在本地构建并注入自定义 Loki 镜像开发时往往需要验证刚编译的代码tools/dev/k3d/Makefile 提供了build-latest-imagemake build-latest-image它会在仓库根目录执行make loki-image构建本地镜像将grafana/loki:IMAGE_TAG打标签为grafana.k3d.localhost:REGISTRY_PORT/loki:latest其中IMAGE_TAG来自 tools/image-tagdocker push到 k3d 的本地 registry供集群拉取使用。这与create_cluster.sh中--registry-use k3d-grafana:port的配置相呼应集群内的节点通过grafana.k3d.localhost访问该 registry从而实现本地构建 → 本地推送 → 集群即时使用的开发闭环。八、常见问题与调试技巧问题/需求处理方法Docker 无法解析 registry 主机名按文档在/etc/hosts添加127.0.0.1 k3d-grafanahelm 安装耗时较长make默认在安装前 sleep 5 秒等待集群就绪可用make SLEEP10 target加大等待建议用 k9s 等工具实时观察 pod 状态需要 helm 详细日志make DEBUGtrue targetMakefile 中HELM : helm --debug$(DEBUG)会透传--debughelm 仓库需要刷新make update-repos等价 add-repos helm repo updatetk tool charts vendorjb update手动安装某个组件先make helm-cluster再执行helm-install-*系列 target完全清场make downk3d cluster delete helm-cluster九、小结tools/dev/k3d 目录把 k3d 集群编排、tanka/Jsonnet 基础设施渲染、Helm Chart 安装这三层能力封装为一组声明式的 Makefile target覆盖了 Loki 从单二进制到分布式、从 OSS 到 Enterprise Logs 的主流本地部署形态。对于希望深入理解 Loki 部署拓扑、验证 Chart 变更或调试多租户与监控链路开发者而言这是一套低门槛、可复现、贴近真实发布物的本地开发环境。相关代码与配置可直接在 tools/dev/k3d/Makefile、tools/dev/k3d/scripts/create_cluster.sh、tools/dev/k3d/environments/helm-cluster/main.jsonnet 中继续研读。【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考