企业官网建设流程全解析

使用 Loki Helm Chart 在 GKE 上基于 Simple Scalable 架构快速部署 Loki（OSS 与 Enterprise 模式）

【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki

导读

本文以 Loki 官方仓库 examples 目录 中的两个入门示例为骨架，完整讲解如何在 Google Kubernetes Engine（GKE）集群上、使用 Google Cloud Storage（GCS）作为对象存储，通过loki-simple-scalableHelm Chart 分别部署 Loki 开源版（OSS）与 Grafana Enterprise Logs（Enterprise 许可模式）。读完本文你将掌握：示例目录的组织方式与适用场景、Secret 与 overrides 文件的填充方法、完整的helm upgrade --install安装命令、Enterprise 模式下管理员 Token 与多租户 Provisioner 的用法，以及这些配置背后的 Helm Chart 参数语义与源码级实现依据。

一、示例目录概览：两个开箱即用的"Getting Started"方案

仓库中的 production/helm/loki/docs/examples 目录专为"快速上手"设计，提供了两个基于Simple Scalable 架构（简单可扩展架构）的部署示例，对应 Loki 的两种运行模式：

两个示例的共同部署环境前提是：

• 一个可访问的 Kubernetes 集群（示例基于 GKE）；
• 一个 GCS Bucket；
• 一个对该 Bucket 具有读写权限的 GCP Service Account（服务账号）。

选择哪一个示例，取决于你是否持有 Grafana Enterprise Logs 的许可密钥：持有则走 enterprise 流程，否则走 oss 流程。两者的部署骨架高度一致——都围绕"填充 Secret → 配置 overrides 文件 → 执行 helm 命令"三步展开，区别仅在于 Enterprise 模式额外引入 License、管理员 Token 与租户管理环节。

二、为什么使用 overrides 文件：与核心 values.yaml 的关系

在进入具体步骤之前，有必要先理解示例文件在 Helm Chart 中的角色。Loki 官方 Chart 的核心配置位于 production/helm/loki/values.yaml，而 Chart 元信息（名称、依赖等）位于 production/helm/loki/Chart.yaml，其中声明了minio、rollout-operator等作为默认依赖。

示例中的overrides-*-gcs.yaml文件并不是独立的 Chart，而是一个用于传给helm upgrade --install --values的覆盖值文件（overrides values file）。Helm 在渲染 Chart 时会先加载默认values.yaml，再用用户指定的 overrides 文件做增量覆盖（后者优先级更高）。因此官方文档的建议是：先看核心 values.yaml 了解全部可配置项，再在示例 overrides 文件里按需追加自己的覆盖项。这种设计让你既有一个能直接跑通的最小配置，又能基于完整参数面做生产化改造。

三、部署 Loki OSS（开源版）：逐步实操

本节完整展开 oss/README.md 的部署流程，并对 overrides 文件逐段解读。

3.1 填充 Secret：注入 GCP 服务账号凭据

OSS 示例的 Secret 模板位于 production/helm/loki/docs/examples/oss/oss-secrets.yaml，内容如下：

apiVersion: v1 kind: Secret metadata: name: loki-secrets type: Opaque stringData: gcp_service_account.json: | { GCP_SERVICE_ACCOUNT_JSON_HERE }

操作要点：

1. 将GCP_SERVICE_ACCOUNT_JSON_HERE占位符替换为你 GCP Service Account 的 JSON 密钥完整内容；
2. 部署该 Secret 到集群：

kubectl apply -f loki-secrets.yaml

注意：原文档中该命令引用的文件名与模板文件名（oss-secrets.yaml）略有出入，实操时请以你实际保存的 Secret 文件名为准。Secret 的名字loki-secrets必须与后续 overrides 文件中的secretName: loki-secrets保持一致，否则 Pod 无法挂载凭据。

3.2 配置 overrides 文件：替换 GCS Bucket 名称

打开 production/helm/loki/docs/examples/oss/overrides-oss-gcs.yaml，将其中所有的{YOUR_GCS_BUCKET}占位符替换为你的 GCS Bucket 名称。替换完成后，该文件的实际语义可以拆解为四大部分：

（1）Enterprise 相关开关——保持关闭

enterprise: enabled: false adminApi: enabled: false useExternalLicense: false

这一段的含义是：即使在同一个 Chart 中部署，也要明确关闭 Enterprise 特性，包括管理 API 与外部 License，确保走纯 OSS 路径。它同时证明了 OSS 与 Enterprise 是同一套 Chart 下的两种开关模式。

（2）Enterprise 配置块中的 admin_client 与认证

config: | admin_client: storage: gcs: bucket_name: {YOUR_GCS_BUCKET} auth: type: trust auth_enabled: false cluster_name: loki-logs

config是一段内嵌的 Loki 配置文本，用于声明 admin client 的 GCS 存储位置，并把认证设置为trust（信任模式）、关闭auth_enabled——这是 OSS 单租户场景的典型做法，无需租户令牌即可访问。

（3）Loki 核心存储与通用配置

loki: auth_enabled: false commonConfig: path_prefix: /var/loki replication_factor: 3 storage: type: gcs bucketNames: chunks: {YOUR_GCS_BUCKET} ruler: {YOUR_GCS_BUCKET} admin: {YOUR_GCS_BUCKET}

• commonConfig.path_prefix: /var/loki：Loki 各组件统一的本地数据目录前缀（用于 WAL、缓存等）；
• commonConfig.replication_factor: 3：数据复制因子设为 3，与 Simple Scalable 架构中 write 副本数搭配，保证写入冗余；
• storage.type: gcs：声明后端对象存储为 GCS；
• bucketNames：分别指定 chunks（日志块）、ruler（规则状态）、admin（管理数据）使用的 Bucket，示例中三者指向同一个 Bucket。

（4）关闭内置 MinIO，为 write/read/gateway 注入 GCS 凭据

minio: enabled: false

由于示例改用 GCS 而非本地 MinIO，必须显式关闭 Chart 默认的 MinIO 依赖，避免启动多余组件。

随后，write、read、gateway三个组件分别配置了完全对称的"三件套"：extraEnv设置GOOGLE_APPLICATION_CREDENTIALS环境变量指向挂载路径、extraVolumeMounts声明挂载点/etc/loki_secrets、extraVolumes从loki-secretsSecret 中取出gcp_service_account.json键。例如 write 组件：

write: extraEnv: - name: GOOGLE_APPLICATION_CREDENTIALS value: "/etc/loki_secrets/gcp_service_account.json" extraVolumeMounts: - name: loki-secrets mountPath: "/etc/loki_secrets" extraVolumes: - name: loki-secrets secret: secretName: loki-secrets items: - key: gcp_service_account.json path: gcp_service_account.json

这是 GCS 鉴权的关键机制：GOOGLE_APPLICATION_CREDENTIALS是 Google Cloud 客户端库的标准环境变量，指向服务账号 JSON 文件后，Loki 的 GCS 客户端即可自动完成身份认证。由于 write（写入）、read（读取）、gateway（网关）都可能与 GCS 交互，三者必须都注入该凭据。

3.3 安装 Helm Chart

helm upgrade --install --values {PATH_TO_YOUR_OVERRIDES_YAML_FILE} {YOUR_RELEASE_NAME} grafana/loki-simple-scalable --namespace {KUBERNETES_NAMESPACE}

参数说明：

• --values {PATH_TO_YOUR_OVERRIDES_YAML_FILE}：指向你修改后的 overrides 文件绝对/相对路径；
• {YOUR_RELEASE_NAME}：本次 Helm Release 的名称（例如loki）；
• grafana/loki-simple-scalable：Chart 的仓库名，即上文 Chart.yaml 中名为loki的 Chart（Helm 仓库中的别名）；
• --namespace：目标 Kubernetes 命名空间，建议提前创建或使用已存在命名空间。

upgrade --install语义为"存在则升级、不存在则安装"，是官方推荐的可重复执行方式。

四、部署 Grafana Enterprise Logs（Loki Enterprise 模式）

本节完整展开 enterprise/README.md 的部署流程，覆盖从 License 注入到多租户管理的完整链路。

4.1 填充 Secret：同时注入 GCP 凭据与 License

Enterprise 示例的 Secret 模板位于 production/helm/loki/docs/examples/enterprise/enterprise-secrets.yaml：

apiVersion: v1 kind: Secret metadata: name: gel-secrets type: Opaque stringData: gcp_service_account.json: | { GCP_SERVICE_ACCOUNT_JSON_HERE } license.jwt: LICENSE_HERE

与 OSS 版本相比，这里需要填充两项内容：

• gcp_service_account.json：GCP 服务账号 JSON 密钥（同上）；
• license.jwt：Grafana Labs 颁发给你的 Grafana Enterprise Logs License 密钥（JWT 格式）。

部署命令：

kubectl apply -f enterprise-secrets.yaml

Secret 名称gel-secrets必须与 overrides 文件中的externalLicenseName和secretName保持一致。

4.2 配置 overrides 文件

打开 production/helm/loki/docs/examples/enterprise/overrides-enterprise-gcs.yaml，替换{YOUR_GCS_BUCKET}后，其核心差异点如下：

（1）开启 Enterprise 并引用外部 License

enterprise: enabled: true useExternalLicense: true externalLicenseName: gel-secrets # If using provisioner, specify the admin token secret # adminToken: # secret: loki-admin-token

与 OSS 版相反，这里将enabled设为true，并通过useExternalLicense: true+externalLicenseName: gel-secrets告诉 Chart 从名为gel-secrets的 Secret 中读取license.jwt。被注释掉的adminToken段则提示：如果后续要使用 Provisioner 自动创建租户，需要在此引用管理员 Token Secret（见 4.4）。

（2）启用认证

loki: auth_enabled: true

Enterprise 多租户场景必须开启auth_enabled，这意味着所有请求都需要携带租户标识与令牌。

（3）存储与凭据注入

存储部分与 OSS 版一致（storage.type: gcs+ 三个bucketNames+ 关闭minio），区别在于：

• 凭据挂载路径变为/etc/gel_secrets；
• 每个组件的extraVolumes同时挂载两个 key：license.jwt与gcp_service_account.json，例如：

write: extraEnv: - name: GOOGLE_APPLICATION_CREDENTIALS value: "/etc/gel_secrets/gcp_service_account.json" extraVolumeMounts: - name: gel-secrets mountPath: "/etc/gel_secrets" extraVolumes: - name: gel-secrets secret: secretName: gel-secrets items: - key: license.jwt path: license.jwt - key: gcp_service_account.json path: gcp_service_account.json

read与gateway组件也采用同样的对称配置，确保所有组件既能访问 GCS，也能读取 License。

4.3 创建管理员 Token Secret（Provisioner 前置条件）

如果你打算使用 Enterprise Provisioner 自动创建租户，就必须先准备一个管理员 Token。原文档提供了两种生成方式：

方式一：使用 Loki CLI 生成（tokengen 目标）

docker run grafana/enterprise-logs:latest -target=tokengen -tokengen.token-file=/tmp/token # Copy the generated token from the container docker cp <container-id>:/tmp/token ./admin-token

-target=tokengen让 Enterprise Logs 以"令牌生成器"模式运行，把生成的 admin token 写入容器内/tmp/token，再用docker cp拷出到宿主机./admin-token文件。

方式二：在集群内以 Job 方式运行

原文档同时提示可参考 production/helm/loki/docs/examples/enterprise/batchjob.yaml 使用 Kubernetes Job 完成同样工作。该 Job 的关键设计是：

apiVersion: batch/v1 kind: Job metadata: name: tokengen namespace: loki # The namespace of the GEL installation spec: backoffLimit: 0 template: spec: serviceAccountName: loki-enterprise-logs restartPolicy: Never containers: - name: tokengen image: grafana/enterprise-logs:latest args: - -target=tokengen - -config.file=/etc/loki/config/config.yaml - -tokengen.token-file=/tmp/token volumeMounts: - name: config-volume mountPath: /etc/loki/config readOnly: true volumes: - name: config-volume configMap: name: enterprise-logs items: - key: config.yaml path: config.yaml

从源码结构看，该 Job 的思路是：复用 GEL 安装的 ServiceAccount（loki-enterprise-logs，其 IAM 权限足以访问存储桶）、复用其 ConfigMap（enterprise-logs中的config.yaml，内含存储桶配置），在集群内直接完成 tokengen。注意，这种方式要求 GEL 已经通过helm install部署就绪，因为 Job 依赖现成的 ConfigMap 与 ServiceAccount。此外示例默认命名空间为loki，backoffLimit: 0表示失败不重试。

生成 token 后，创建 Kubernetes Secret：

kubectl create secret generic loki-admin-token \ --from-file=token=./admin-token \ --namespace {KUBERNETES_NAMESPACE}

然后在 overrides 文件中取消注释并引用该 Secret：

enterprise: adminToken: secret: loki-admin-token

4.4 安装 Helm Chart

与 OSS 版完全相同的命令：

helm upgrade --install --values {PATH_TO_YOUR_OVERRIDES_YAML_FILE} {YOUR_RELEASE_NAME} grafana/loki-simple-scalable --namespace {KUBERNETES_NAMESPACE}

4.5 使用 Provisioner 自动创建租户

如果你启用了 Provisioner，它会根据配置自动创建额外的租户。例如下面的配置会创建一个名为loki-a的租户：

enterprise: adminToken: secret: loki-admin-token provisioner: enabled: true additionalTenants: - name: loki-a secretNamespace: loki

其中：

• adminToken.secret指向 4.3 中创建的管理员 Token Secret；
• provisioner.enabled: true开启自动租户供给；
• additionalTenants以列表形式声明额外租户（名称及其 Token Secret 所在命名空间）。

此外，一个用于监控的租户也会被自动创建，其名称取自.Values.monitoring.selfMonitoring.tenant的值——这是 Chart 内建的自监控机制与租户管理的联动点。

Provisioner 以 Job（loki-provisioner）的形式运行，排查时可查看其日志：

kubectl logs -l job-name=loki-provisioner --namespace {KUBERNETES_NAMESPACE}

4.6 手动生成租户 Token（不使用 Provisioner）

如果你不使用 Provisioner，可以手动为租户生成 Token：

步骤 1：端口转发到 gateway 服务

kubectl port-forward svc/loki-gateway 3100:80 --namespace {KUBERNETES_NAMESPACE}

将本地 3100 端口映射到loki-gateway服务的 80 端口，从而在本机访问管理 API。

步骤 2：通过 Admin API 创建租户 Token

# Example: Create a token for a tenant curl -X POST http://localhost:3100/admin/api/v1/tokens \ -H "Authorization: Bearer <admin-token>" \ -H "Content-Type: application/json" \ -d '{"name": "my-tenant", "displayName": "My Tenant", "access_policy": "logs:write,logs:read"}'

请求体中的name、displayName、access_policy（如logs:write,logs:read）共同定义了租户的身份与权限。务必妥善保存生成的 Token——后续将 Grafana Enterprise Logs 接入 Grafana 数据源时需要使用这些租户 Token。

五、源码与配置层面的深度理解

5.1 Simple Scalable 架构与示例的对应关系

两个示例均基于 Simple Scalable 架构，即把 Loki 拆分为 write（写入）、read（读取）、gateway（网关）三大类工作负载。这一点在 overrides 文件中有直接体现：write、read、gateway三节完全并列且结构对称。官方 Chart 同时提供了其他架构形态的预置 values（如 simple-scalable-values.yaml 与 distributed-values.yaml），说明同一 Chart 可通过 values 在不同部署形态间切换；examples 目录选择 Simple Scalable 正是因为它兼具扩展性与运维简洁性，适合作为 Getting Started 模板。

5.2 为什么需要给 write/read/gateway 都挂凭据

从代码结构可以推断，Simple Scalable 架构下 read 组件负责查询（需要读 GCS 中的 chunks 与索引）、write 组件负责写入（需要写 GCS）、gateway 作为统一入口负责路由（需要感知租户与后端）。由于三者都可能直接与对象存储交互，因此示例为每个组件都重复注入GOOGLE_APPLICATION_CREDENTIALS环境变量与 Secret 卷。理解了这一点，你在为其他组件（如 querier、compactor）扩展配置时就能举一反三。

5.3 GCS 凭据的注入机制

GOOGLE_APPLICATION_CREDENTIALS是 Google 官方客户端库（Google Cloud Client Libraries）的标准鉴权环境变量。示例通过extraEnv设置该变量、通过extraVolumes/extraVolumeMounts将 Secret 中的 JSON 密钥挂载为文件，二者配合即可让运行在 GKE 中的 Loki 组件以服务账号身份访问 GCS。这是 Helm Chart 提供extra*扩展点（extraEnv/extraVolumes/extraVolumeMounts）的典型应用：在不修改 Chart 模板的前提下，为任意组件注入自定义环境变量与卷。

5.4 OSS 与 Enterprise 的差异总览

这一对比也印证了同一套loki-simple-scalableChart 通过 values 开关即可同时支撑 OSS 与 Enterprise 两种部署形态的设计意图。

六、最佳实践与注意事项

1. 先跑通最小示例，再扩展配置：官方推荐先使用 examples 中的 overrides 文件完成部署，再对照核心 values.yaml 按需覆盖其他参数（副本数、资源限额、Ingress 等），避免一开始就陷入庞大参数面。
2. 保持 Secret 名与引用一致：OSS 的loki-secrets、Enterprise 的gel-secrets、管理员 Token 的loki-admin-token必须与 overrides 文件中的secretName/externalLicenseName/adminToken.secret严格对应，否则组件启动即失败。
3. 确认 Service Account 的 GCS 权限：两个示例都假设 GCP Service Account 对目标 Bucket 具备读写权限。建议提前用gcloud或 IAM 策略验证权限，并留意 Enterprise 的 batchjob 方案会复用 GEL 安装的 ServiceAccount（loki-enterprise-logs）。
4. Enterprise 模式的 License 与 Token 安全：license.jwt与 admin token 均为敏感凭据，应以 Kubernetes Secret 管理并控制访问范围；租户 Token 生成后要立即记录，丢失后需通过 Admin API 重新签发。
5. 留意文档中的命名差异：官方 OSS 文档在示例命令中写的是kubectl apply -f loki-secrets.yaml，而实际模板文件名为oss-secrets.yaml；Enterprise 文档提到overides-oss-gcs.yaml，实际文件为overrides-oss-gcs.yaml。实操时以 oss 与 enterprise 目录中的实际文件名为准。

结语

通过本文的完整拆解，你可以基于 examples 目录 中的两份 Getting Started 配置，在 GKE + GCS 环境下一步步完成 Loki OSS 或 Grafana Enterprise Logs 的 Simple Scalable 部署：从 Secret 注入、overrides 参数解读，到helm upgrade --install安装、Enterprise 模式下的 Admin Token 与 Provisioner 租户管理。这套示例的价值在于"最小的完整闭环"——它既是新手的第一条部署路径，也是理解 Loki Helm Chart 参数体系与 Simple Scalable 架构的绝佳入口。

【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki