Loki Operator 本地开发实战：基于 kind 与 OpenShift 的镜像注册表 Hack 指南

Loki Operator 本地开发实战基于 kind 与 OpenShift 的镜像注册表 Hack 指南【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki本篇技术指南聚焦 Grafana Loki 官方仓库中 Loki Operator 的本地开发与调试流程核心主题是借助个人容器镜像注册表在 kind 或 OpenShift 集群中部署并验证 Loki Operator。读完本文你将掌握make oci-build oci-push deploy与make olm-deploy两条开发部署链路的完整操作、LokiStack 实例的创建与组件核对方法、Gateway 可选组件的启停技巧以及常见问题的排障手段可直接复用于日常的 Operator 迭代开发。背景为什么需要镜像注册表式 HackLoki Operator 是 Loki 的 Kubernetes Operator参见 operator/README.md 与 docs/_index.md它通过自定义资源LokiStack来编排 Loki 的分布式组件。在开发过程中代码改动需要被打包成容器镜像并推送到集群可达的镜像仓库再通过 Operator 部署到本地集群才能真正验证改动效果。这就是本文标题中 Hacking using an image registry 的含义——把本地改代码 → 构建镜像 → 推镜像 → 部署 Operator → 创建 LokiStack串成一条可重复的迭代回路。从 operator/Makefile 的源码可以看到这条链路的两个关键目标oci-build/oci-push用本机容器运行时OCI_RUNTIME ? $(shell which podman || which docker)构建并推送$(IMG)镜像deploy先用 kustomize 把config/manager中的镜像替换为刚推送的IMG再渲染config/overlays/development应用到集群operator/Makefile。在开始之前请确认本仓库已包含完整的 operator 子项目含Makefile、hack/、config/、bundle/等目录并已安装好 Go 工具链与 make。在 kind 集群上部署 Loki Operator前置条件安装 kubectl 或 OpenShift CLI 用于与集群通信下文统一使用kubectl用 kind 创建一个运行中的 Kubernetes 集群kind 使用 Docker 容器充当集群节点适用于本地开发与 CI准备一个你和你的 Kubernetes 集群都能访问到的容器注册表文档推荐使用 quay.io 的账号作为个人仓库位置。安装 Loki Operator构建并推送容器镜像然后部署 Operatormake oci-build oci-push deploy REGISTRY_BASE$YOUR_REPO_ORG VERSIONlatest其中$YOUR_REPO_ORG是你个人的注册表位置例如一个 quay.io 账号。这条命令会把 Operator 部署到你本地 kubeconfig 指向的当前激活集群中运行在default命名空间。结合 operator/Makefile 与 operator/Makefile 可以还原这条命令的完整行为IMG ? $(REGISTRY_BASE)/loki-operator:$(VERSION)即镜像会被标记为$YOUR_REPO_ORG/loki-operator:latest随后deploy目标执行cd config/manager kustomize edit set image controller${IMG}将 operator/config/manager/manager.yaml 中的image: controller:latest占位符替换为真实镜像地址。确认 Operator 已启动kubectl get pods此时应能看到controller-manager-xxxx和minio-xxxx两个 Pod 在运行。其中minioPod 来自开发 overlay 中内置的 S3 兼容对象存储供 LokiStack 的存储配置使用详见 operator/config/overlays/development。创建 LokiStack 实例现在创建一个 LokiStack 实例让 Loki 的各组件运行起来kubectl apply -f hack/lokistack_dev.yaml从仓库根目录看该文件位于 operator/hack/lokistack_dev.yaml其内容是一个最小化的 LokiStack 自定义资源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指定 LokiStack 的规模配置1x.demo是适合本地开发的最小规格storage.schemas声明存储 schema 版本v13及生效日期Operator 会依据该 schema 初始化对象存储索引与块布局storage.secret引用名为test的 Kubernetes Secret类型为s3即对象存储凭据storageClassName: standard指定 Loki 各 StatefulSet 使用的存储类。应用该实例后Operator 会创建distributor、compactor、ingester、querier、query-frontend五个组件。对deployments确认滚动状态kubectl rollout status deployment/DEPLOYMENT_NAMEDEPLOYMENT_NAME可通过下面命令查到kubectl get deployments对statefulsets同样确认kubectl rollout status statefulset/STATEFULSET_NAMESTATEFULSET_NAME可通过下面命令查到kubectl get statefulsets清理部署如需清理 Operator 部署make undeploy该命令会从 kubeconfig 指向的 Kubernetes 集群中卸载 controller。从 operator/Makefile 看它实际执行kustomize build config/overlays/development | kubectl delete --ignore-not-found... -f -即先渲染开发 overlay 再整体删除。在 OpenShift 上部署 Loki Operator前置条件安装 kubectl 或 OpenShift CLI下文统一使用kubectl在 AWS 上创建并运行一个 OpenShift 集群准备一个你和 OpenShift 集群都能访问到的容器注册表推荐 quay.io在某个 AWS Region 创建一个 S3 bucket作为 Loki 的对象存储后端。安装 Loki Operator先在集群中创建openshift-operators-redhat命名空间kubectl create ns openshift-operators-redhat构建并推送容器镜像然后通过 OLM 部署 Operatormake olm-deploy REGISTRY_BASE$YOUR_REPO_ORG VERSION$VERSION$YOUR_REPO_ORG是你的个人注册表位置$VERSION可以是任意随机版本号例如v0.0.1。这条命令会把 Operator 部署到你本地 kubeconfig 指向的 OpenShift 集群运行在openshift-operators-redhat命名空间。从 operator/Makefile 可以看出olm-deploy的组成先执行olm-deploy-bundlemake bundle bundle-build VERSION$(OLM_VERSION) 推送 bundle 镜像与olm-deploy-operatormake oci-build oci-push IMG$(OLM_IMG)最后用operator-sdk run bundle -n $(LOKI_OPERATOR_NS) --install-mode AllNamespaces ...通过 OLM 把 bundle 跑起来。注意 Makefile 中有个保护逻辑若REGISTRY_BASE恰好包含openshift-logging字样olm-deploy会直接报错要求你为本地开发显式设置自定义注册表组织账号。确认 Operator 已启动kubectl -n openshift-operators-redhat get pods接下来创建openshift-logging命名空间kubectl create ns openshift-logging创建对象存储 Secret为 Operator 创建对象存储 Secret./hack/deploy-aws-storage-secret.sh BUCKET_NAME该脚本位于 operator/hack/deploy-aws-storage-secret.sh会把 Secret 创建在openshift-logging命名空间。脚本默认通过awsCLI 拉取当前 profile 的凭据但这些值都可以用环境变量覆盖例如REGIONus-west-1 ./hack/deploy-aws-storage-secret.sh BUCKET_NAME结合脚本源码可以看到其完整行为operator/hack/deploy-aws-storage-secret.shnamespace${NAMESPACE:-openshift-logging}命名空间默认openshift-logging可用NAMESPACE覆盖region${REGION:-$(aws configure get region)}Region 默认取自 AWS CLI 配置可用REGION覆盖access_key_id/secret_access_key默认取自aws configure get可用ACCESS_KEY_ID/SECRET_ACCESS_KEY覆盖静态认证模式下STSfalse默认Secret 会写入region、bucketnames、access_key_id、access_key_secret、endpoint形如https://s3.region.amazonaws.com五个字段托管模式STStrue下只写region、bucketnames并可传入可选第二个参数role_arn写入role_arn字段脚本最终以kubectl -n namespace create secret generic test ...创建名为test的 Secret——这与 operator/hack/lokistack_gateway_dev.yaml 中spec.storage.secret.name: test的引用保持一致。创建 Gateway Secret再为 Operator 创建 gateway Secretkubectl -n openshift-logging create secret generic test1 \ --from-literalclientIDCLIENT_ID \ --from-literalclientSecretCLIENT_SECRET \ --from-literalissuerCAPathISSUER_CA_PATHOIDC 配置需要clientID、clientSecret、issuerCAPath三个字段由 LokiStack 管理员预先通过 Kubernetes Secret 提供。每个租户的 Secret 必须满足两个约束metadata.name与TenantsSecretsSpec.Name匹配metadata.namespace与LokiStack.metadata.namespace匹配。创建 LokiStack 实例含 Gateway对象存储 Secret 就绪后即可创建带多租户网关的 LokiStack 实例kubectl -n openshift-logging apply -f hack/lokistack_gateway_dev.yaml对应文件为 operator/hack/lokistack_gateway_dev.yaml它是一个包含 OIDC 租户认证配置的完整示例--- apiVersion: v1 kind: Secret stringData: clientID: lokistack metadata: name: test-oidc --- 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 tenants: mode: static authentication: - tenantName: test-oidc tenantId: test-oidc oidc: secret: name: test-oidc issuerURL: http://hydra.hydra.svc:4444/ authorization: roleBindings: - name: test-oidc roles: - read-write subjects: - kind: user name: user roles: - name: read-write permissions: - read - write resources: - logs tenants: - test-oidc该实例会创建distributor、compactor、ingester、querier、query-frontend以及lokistack-gateway共六个组件。其中tenants.mode: static声明静态多租户模式authentication定义了名为test-oidc的租户及其 OIDC 签发端authorization通过 role 与 roleBinding 声明了该租户的读写权限。确认 deployments 状态kubectl -n openshift-logging rollout status deployment/DEPLOYMENT_NAMEDEPLOYMENT_NAME可通过下面命令查到kubectl -n openshift-logging get deployments确认 statefulsets 状态kubectl -n openshift-logging rollout status statefulset/STATEFULSET_NAMESTATEFULSET_NAME可通过下面命令查到kubectl -n openshift-logging get statefulsets可选跳过 lokistack-gateway 组件如果不想要lokistack-gateway组件可以移除loki-operator-controller-managerDeployment 中的--with-lokistack-gateway参数kubectl -n openshift-operators-redhat edit deployment/loki-operator-controller-manager从args段删除--with-lokistack-gateway标志并保存Deployment 会随之更新之后即可用不带网关的实例文件创建 LokiStackkubectl -n openshift-logging apply -f hack/lokistack_dev.yaml此时只会创建distributor、compactor、ingester、querier、query-frontend五个组件。关于lokistack-gateway组件的定位文档注释给出了明确说明它是 Loki Operator 部署的可选组件通过向 OIDC/OAuth 端点查询请求主体的身份为 Loki 的 distributor推送日志和 query-frontend查询日志提供安全访问。更详细的 Gateway 配置如外部访问资源、自定义 TLS 证书等可参考 operator/docs/user-guides/gateway-config.md。清理部署make olm-undeploy该命令会通过 OLM 清理 Operator bundle 及 Operator 部署。从 operator/Makefile 看它执行的是operator-sdk cleanup -n $(LOKI_OPERATOR_NS) loki-operator。补充说明构建镜像时如果出现多个镜像可供选择且要求你选择其一请选择docker.io/library/golang:1.18每个租户的 Secret 必须满足metadata.name与TenantsSecretsSpec.Name一致、metadata.namespace与LokiStack.metadata.namespace一致的要求。开发辅助组件Promtail 与 logcli为方便测试与开发仓库在hack/目录下提供了 Promtail日志采集与 logcli日志查询的开发部署文件。示例文件默认配置为配合lokistack-gateway工作即通过网关的application租户入口收发日志如果不需要该组件需要把 URL 改为直接指向distributor与query-frontend的 Service。部署顺序先按上文步骤部署好 Operator 与 LokiStack 实例然后执行kubectl apply -f ./hack/addons_dev.yaml从仓库根目录看对应文件为 operator/hack/addons_dev.yaml其中lokistack-dev-addons-logcliDeployment 使用docker.io/grafana/logcli:3.7.7镜像设置LOKI_ADDRhttp://lokistack-dev-gateway-http.openshift-logging.svc:8080/api/logs/v1/application并通过 ServiceAccount token 认证循环执行logcli query {namespacedefault}lokistack-dev-addons-promtailDaemonSet 使用docker.io/grafana/promtail:3.6镜像挂载/var/log/pods、/var/log/journal等宿主路径配置了 journal 与 kubernetes-pods 多组采集任务客户端 URL 指向网关的 push 端点/api/logs/v1/application/loki/api/v1/push配套的 ClusterRole / ClusterRoleBinding 为 logcli 授予get权限、为 promtail 授予create与节点发现权限用于网关侧的授权校验。注意事项在 OpenShift 集群上应使用hack/addons_ocp.yaml即 operator/hack/addons_ocp.yaml原生 K8s 集群才使用addons_dev.yaml。OpenShift 环境使用SecurityContextConstraints来限制或开启 Pod 能力因此两份清单在 URL 协议httpsvshttp、CA 证书参数与安全上下文的写法上有所差异在原生 K8s 集群部署时请确保ClusterRoleBinding对象中ServiceAccount的 namespace 已改为对应的命名空间示例文件中的 subject namespace 写的是openshift-logging。常见问题排查改动未被 Loki Operator 感知修改了 Operator 代码并重新部署后运行时却看不到新改动——这通常是因为 Deployment 的imagePullPolicy为IfNotPresent集群拉取了旧镜像。解决办法打开 operator/config/manager/manager.yaml将imagePullPolicy改为AlwaysimagePullPolicy: Always重新部署 Operator。kubectl 使用了旧集群上下文同时使用 kind 集群与 OpenShift 集群时切换集群后 kubectl 可能不会自动切换上下文需要手动切换列出所有可用上下文kubectl config get-contexts带*标记的即为当前使用的上下文。切换到目标上下文kubectl config use-context $CONTEXTNAME其中$CONTEXTNAME是上一步列出的、你希望切换到的上下文名。Missing Secrets / Invalid Secrets 错误出现该错误通常是忘了先创建 gateway Secret导致 Operator 运行在degraded状态。请按上文创建 Gateway Secret的步骤先补建 Secret再创建 LokiStack 实例。可通过conditions字段验证kubectl get lokistack lokistack-dev -o yaml在 OpenShift 上则为kubectl -n openshift-logging get lokistack lokistack-dev -o yamlMandatory Configuration / Incompatible Configuration 错误该错误通常发生在 LokiStack CR 针对 lokistack-gateway 配置错误时。可参考多租户模式与网关配置的相关文档operator/docs/user-guides/tenancy-modes.md、operator/docs/user-guides/gateway-config.md核对tenants段与 Secret 引用是否一致。结语基于镜像注册表的 hack 流程把改代码 → 出镜像 → 上集群 → 建实例压缩成几条 make 命令是 Loki Operator 本地开发最直接的迭代方式。kind 路径适合快速验证核心编排逻辑OpenShift 路径则能覆盖 OLM 部署、S3 存储与多租户网关等生产特性。配合hack/目录下的开发辅助清单与本节排障要点即可在本地完整跑通 Operator 的日常开发闭环。【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考