企业官网建设流程全解析

Loki Operator 本地开发实战：用make run在 Kind 与 OpenShift 上快速迭代

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

导读

本文以 operator/docs/operator/hack_operator_make_run.md 为主线，系统讲解如何在不打包、不推送容器镜像的前提下，使用make run在本地机器上直接运行 Loki Operator，并在 Kind 或 OpenShift 集群中完成开发与联调。读完本文，你将掌握：本地启动 Operator 的完整命令链、MinIO/S3 对象存储与 OIDC 网关 Secret 的配置方法、代码改动的快速热迭代流程，以及常见的多集群 Context 切换与网关 Secret 缺失类故障排查手段，并能结合仓库 Makefile 与 main.go 源码理解make run背后的真实调用链。

为什么用make run做开发

Loki Operator 是管理 Loki 日志堆栈的 Kubernetes Operator（自定义资源为LokiStack），常规的部署方式（如make deploy）需要把 Operator 构建成镜像并部署到集群内。然而在开发迭代阶段，每次改动一行 Go 代码就重新构建镜像、推送到仓库、滚动更新 Pod，成本极高。

make run的价值在于：Operator 以本地进程的方式运行在你的开发机上，直接通过~/.kube/config中的集群凭据与集群 API 通信。这意味着：

• 改动代码后只需CTRL + C停掉本地进程，重新执行make run即可生效；
• 无需反复构建和部署 Operator 镜像；
• Operator 与集群之间走的是标准 kubeconfig 认证，与集群内运行时行为一致，适合最后的端到端验证。

从 Makefile 可以看到该目标的具体定义：

.PHONY: run run: generate manifests ## Run against the configured Kubernetes cluster in ~/.kube/config go run ./cmd/loki-operator/main.go

也就是说make run会先执行generate（通过controller-gen生成深拷贝代码）与manifests（生成 CRD、RBAC 等清单），随后直接go run启动 cmd/loki-operator/main.go，完全绕过了镜像构建环节。这也解释了文档中"每次改动代码只需重启本地进程"的可行性。

在 Kind 上使用make run开发

前置要求

• 安装 [kubectl] 或 OpenShift CLI，用于与集群通信（下文示例使用kubectl）；
• 使用 kind 创建一个正在运行的 Kubernetes 集群。kind 是基于 Docker 容器"节点"的本地 Kubernetes 集群工具，最初用于测试 Kubernetes 本身，也常用于本地开发与 CI。

安装 Loki Operator

第一步：安装 CRD

make install

该命令通过 kustomize 构建 config/crd 下的 CRD 清单并应用到集群，会创建名为lokistacks.loki.grafana.com的自定义资源定义，可用以下命令验证：

kubectl get crd lokistacks.loki.grafana.com

从 Makefile 看，install实际执行的是：

.PHONY: install install: manifests $(KUSTOMIZE) ## Install CRDs into a cluster $(KUSTOMIZE) build config/crd | kubectl apply -f -

第二步：部署 MinIO 作为对象存储

kubectl apply -k config/overlays/development/minio

该命令会在default命名空间创建 MinIO 的deployment、service、pvc和secret。目录下共有五个资源文件（kustomization.yaml 引用了 pvc、service、secret、deployment），其中值得关注的是 secret.yaml，它正是 LokiStack 声明要使用的对象存储凭据：

apiVersion: v1 kind: Secret metadata: name: test stringData: endpoint: http://minio.default.svc:9000 bucketnames: loki access_key_id: minio access_key_secret: minio123 type: Opaque

对应的 deployment.yaml 以minio/minio镜像启动，root 用户/密码为minio/minio123，并会在启动时创建/storage/loki目录，数据落在名为minio的 PVC 上。这个testSecret 的名字与下文 LokiStack 示例中storage.secret.name: test严格对应，这也体现了"Secret 名称必须与 LokiStack 引用一致"的约定。

第三步：创建 LokiStack 实例

kubectl apply -f hack/lokistack_dev.yaml

仓库中的 hack/lokistack_dev.yaml 是一个极简示例：

apiVersion: loki.grafana.com/v1 kind: LokiStack metadata: name: lokistack-dev spec: size: 1x.demo storage: schemas: - version: v13 effectiveDate: 2023-10-15 secret: name: test type: s3 storageClassName: standard

其中size: 1x.demo表示使用 demo 级堆栈规格，storage.secret.name: test指向刚创建的 MinIO Secret，storage.secret.type: s3声明后端为 S3 兼容存储。

第四步：本地运行 Operator

make run

此时 Operator 在本地启动，它会识别集群中的LokiStackCRD 实例，并自动创建distributor、compactor、ingester、querier和query-frontend等 Loki 核心组件。

第五步：确认组件就绪

Deployment 类的组件用 rollout 状态确认：

kubectl rollout status deployment/<DEPLOYMENT_NAME>

其中<DEPLOYMENT_NAME>可通过以下命令获取：

kubectl get deployments

StatefulSet 类的组件同理：

kubectl rollout status statefulset/<STATEFULSET_NAME>

名称列表来自：

kubectl get statefulsets

代码热迭代：改完即跑

如果你修改了 Operator 的代码，只需在本地终端按CTRL + C停掉 Operator，更新代码后重新执行：

make run

即可让新代码立即生效，无需反复把 Operator 部署到集群中，这是开发效率的关键所在。当所有改动验证通过后，再按正式流程将全部内容部署到集群做最终测试（可参考 operator 文档目录下 operator/docs/operator 中关于完整部署流程的文档）。

清理

• 按CTRL + C停止本地 Operator 进程；
• 清理集群中的 LokiStack 实例、CRD 与相关资源：

make uninstall

uninstall目标同样基于 kustomize 构建 CRD 清单执行删除，并支持ignore-not-found=true忽略不存在资源的报错：

.PHONY: uninstall uninstall: manifests $(KUSTOMIZE) ## Uninstall CRDs from the K8s cluster specified in ~/.kube/config. Call with ignore-not-found=true to ignore resource not found errors during deletion. $(KUSTOMIZE) build config/crd | kubectl delete --ignore-not-found=$(ignore-not-found) -f -

• 删除 MinIO 相关资源：

kubectl delete -k config/overlays/development/minio

在 OpenShift 上使用make run开发

前置要求

• 安装 kubectl 或 OpenShift CLI（下文示例使用kubectl）；
• 在 AWS 上创建一个运行中的 OpenShift 集群；
• 在某个 AWS Region 中创建一个 S3 bucket。

安装 Loki Operator

第一步：安装 CRD

make install

验证方式与 Kind 场景一致：

kubectl get crd lokistacks.loki.grafana.com

第二步：创建命名空间

kubectl create ns openshift-logging

第三步：创建对象存储 Secret

./hack/deploy-aws-storage-secret.sh <BUCKET_NAME>

该脚本会在openshift-logging命名空间中创建名为test的 Secret。查看 hack/deploy-aws-storage-secret.sh 可了解其内部逻辑：默认情况下，它通过awsCLI 从当前 profile 读取region、access_key_id、secret_access_key，并生成包含region、bucketnames、access_key_id、access_key_secret、endpoint（格式为https://s3.<region>.amazonaws.com）等字段的 Secret。这些值都可以通过环境变量覆盖，例如：

REGION=us-west-1 ./hack/deploy-aws-storage-secret.sh <BUCKET_NAME>

脚本还支持其他覆盖项：NAMESPACE（默认openshift-logging）、ACCESS_KEY_ID、SECRET_ACCESS_KEY。若传入STS=true，则切换为 STS 托管认证模式，此时只写入region、bucketnames与可选的role_arn（第二个命令行参数），用于配合 OpenShift Cloud-Credentials-Operator 的托管场景。

第四步：创建 LokiStack 实例

kubectl -n openshift-logging apply -f hack/lokistack_dev.yaml

第五步：本地运行 Operator

make run

此时只会创建distributor、compactor、ingester、querier和query-frontend组件（不含网关）。

验证方式与 Kind 场景一致，但需要带上命名空间参数：

kubectl -n openshift-logging rollout status deployment/<DEPLOYMENT_NAME> kubectl -n openshift-logging get deployments kubectl -n openshift-logging rollout status statefulset/<STATEFULSET_NAME> kubectl -n openshift-logging get statefulsets

可选组件：lokistack-gateway

lokistack-gateway是 Loki Operator 部署的可选组件，它通过校验请求主体的 OAuth/OIDC 端点，为 Loki 的 distributor（推送日志）与 query-frontend（查询日志）提供安全访问。

若需要部署该组件，必须先为 Operator 创建网关 Secret：

kubectl -n openshift-logging create secret generic test1 \ --from-literal=clientID="<CLIENT_ID>" \ --from-literal=clientSecret="<CLIENT_SECRET>" \ --from-literal=issuerCAPath="<ISSUER_CA_PATH>"

OIDC 配置需要clientID、clientSecret与issuerCAPath三个字段，由 LokiStack 管理员预先以 Kubernetes Secret 形式提供。每个租户 Secret 必须满足：

• metadata.name与TenantsSecretsSpec.Name一致；
• metadata.namespace与LokiStack.metadata.namespace一致。

接着应用带网关配置的 LokiStack 示例：

kubectl -n openshift-logging apply -f hack/lokistack_gateway_dev.yaml

仓库中的 hack/lokistack_gateway_dev.yaml 展示了完整的多租户网关配置，其中包含一个名为test-oidc的 OIDC 认证 Secret（clientID: lokistack）以及配套的tenants.mode: static、authentication、authorization（角色read-write拥有logs资源的读写权限）定义，可作为网关场景的参考模板。

随后编辑 operator/cmd/loki-operator/main.go，将网关相关的 feature gate 标志（如LokiStackGateway）设置为true，再重新运行：

make run

此时会创建distributor、compactor、ingester、querier、query-frontend以及lokistack-gateway共六个组件。从 main.go 源码可以看到，网关开关会触发额外依赖注入（如 OpenShift 的route、cloudcredential等 API 注册进 scheme），并在LokiStackReconciler中携带FeatureGates配置参与组件编排；同时 main.go 中还做了强校验，例如LokiStackAlerts标志依赖ServiceMonitors、ServiceMonitorTLSEndpoints依赖HTTPEncryption，不满足会直接报错退出，这解释了为什么改动这些标志后必须重启本地进程。

与之前相同的代码热迭代流程依然适用：CTRL + C停止 → 修改代码 →make run重启，无需反复部署。

清理

• 按CTRL + C停止本地 Operator；
• 清理 LokiStack 实例、CRD 与集群资源：

make uninstall

常见问题排查

场景一：kubectl 使用了过期的 Context

当你在 Kind 集群与 OpenShift 集群之间来回切换测试时，kubectl 可能不会自动切换 context，导致命令发往了错误的集群。解决方法是手动切换：

先列出所有可用 context（*标记表示当前正在使用的 context）：

kubectl config get-contexts

再切换到目标 context：

kubectl config use-context $CONTEXTNAME

其中$CONTEXTNAME取自上一步列出的 context 名称。

场景二：Missing Secrets / Invalid Secrets 错误

如果你没有先创建网关 Secret 就直接应用了带网关的 LokiStack，Operator 会进入degraded（降级）状态并报出该错误。解决办法是：按照上文步骤先创建网关 Secret，再创建 LokiStack 实例。

可以通过查看 LokiStack 的conditions字段验证当前状态：

kubectl get lokistack lokistack-dev -o yaml

OpenShift 环境下需要加上命名空间参数：

kubectl -n openshift-logging get lokistack lokistack-dev -o yaml

场景三：Mandatory Configuration / Incompatible Configuration 错误

这通常意味着 LokiStack CR 针对 lokistack-gateway 的配置有误。需要核对 OIDC 相关配置（如clientID、clientSecret、issuerCAPath、租户 Secret 的 name/namespace 匹配关系等）是否符合 LokiStack 网关配置的规范要求，参考上文"可选组件：lokistack-gateway"一节的字段说明逐一检查。

小结

make run为 Loki Operator 开发者提供了一条"改代码 → 重启本地进程 → 立即验证"的极速迭代路径。无论底层是 Kind 还是 OpenShift，核心套路一致：make install装 CRD → 准备对象存储（MinIO 或 AWS S3 Secret）→ 应用 LokiStack 实例 →make run本地起 Operator → rollout 验证组件 →CTRL + C热迭代 →make uninstall清理。若涉及网关场景，则额外补齐 OIDC 网关 Secret 并开启对应 feature gate。配套的 Makefile、cmd/loki-operator/main.go、hack/ 目录下的示例清单以及 config/overlays/development/minio 的 MinIO overlay，都是快速搭建本地开发环境时可参考的直接依据。

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