Backstage Kubernetes 集成配置全指南：集群接入、资源关联与源码级原理剖析

Backstage Kubernetes 集成配置全指南集群接入、资源关联与源码级原理剖析【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage 的 Kubernetes 插件为服务所有者提供了跨集群查看其服务健康状态的能力——无论是本地测试环境还是分布在全球的几十个生产集群开发者都可以在软件目录Software Catalog中直接下钻查看 Deployment、Pod 等对象的运行状况。本文以官方配置文档为主线完整讲解app-config.yaml中 Kubernetes 集成的全部配置项并深入plugins/kubernetes-backend与plugins/kubernetes-common源码说明每个配置项背后的实现逻辑帮助你完成从「启用后端采集集群对象」到「在 Catalog 实体上呈现 Kubernetes 对象」的完整接入。在 Backstage 中配置 Kubernetes 集成需要完成两步启用后端让后端能够从你的 Kubernetes 集群中采集对象关联实体让 Kubernetes 对象以 Catalog 实体的形式呈现给用户。下面先从最核心的集群配置说起。配置 Kubernetes 集群app-config.yaml 完整示例以下是一份app-config.yaml中kubernetes配置段的完整示例涵盖了前端特性、服务定位方式以及多种集群定位器cluster locatorkubernetes: frontend: podDelete: enabled: true serviceLocatorMethod: type: multiTenant clusterLocatorMethods: - type: config clusters: - url: http://127.0.0.1:9999 name: minikube authProvider: serviceAccount skipTLSVerify: false skipMetricsLookup: true serviceAccountToken: ${K8S_MINIKUBE_TOKEN} dashboardUrl: http://127.0.0.1:64713 # url copied from running the command: minikube service kubernetes-dashboard -n kubernetes-dashboard dashboardApp: standard caData: ${K8S_CONFIG_CA_DATA} caFile: # local path to CA file customResources: - group: argoproj.io apiVersion: v1alpha1 plural: rollouts - url: http://127.0.0.2:9999 name: aws-cluster-1 title: My AWS Cluster Number One authProvider: aws - type: gke projectId: gke-clusters region: europe-west1 skipTLSVerify: true skipMetricsLookup: true exposeDashboard: true该配置段的整体结构由以下顶级键组成后文将逐一展开配置键是否必填作用frontend可选配置若干前端特性目前仅podDeleteserviceLocatorMethod是决定组件运行在哪些集群上的定位策略clusterLocatorContinueOnError可选控制单个集群定位器失败时是否继续返回其余集群clusterLocatorMethods是决定从何处获取集群配置数组proxy可选Kubernetes API 代理/api/kubernetes/proxy的缓存选项customResources可选默认要查找的自定义资源CRD列表apiVersionOverrides可选覆盖请求时使用的 Kubernetes API 版本objectTypes可选覆盖默认从集群拉取的对象类型frontend前端特性配置可选这是一个用于配置前端特性的数组。当前有效的取值只有一个podDeletepodDelete可选该配置控制容器面板container panel中「删除 Pod」按钮的行为其下唯一的配置项为enabled用于控制该特性的可见性取值范围为true/false默认值为falsekubernetes: frontend: podDelete: enabled: true组件文案国际化如果想自定义或翻译部分组件的文案可以使用 Backstage 的翻译机制createTranslationMessages结合backstage/plugin-kubernetes-react、backstage/plugin-kubernetes、backstage/plugin-kubernetes-cluster三个包导出的翻译引用import { createTranslationMessages } from backstage/core-plugin-api/alpha; import { kubernetesReactTranslationRef } from backstage/plugin-kubernetes-react/alpha; import { kubernetesTranslationRef } from backstage/plugin-kubernetes/alpha; import { kubernetesClusterTranslationRef } from backstage/plugin-kubernetes-cluster/alpha; const app createApp({ __experimentalTranslations: { resources: [ createTranslationMessages({ ref: kubernetesReactTranslationRef, messages: { podDrawer.buttons.delete: Restart Pod } }), createTranslationMessages({ ref: kubernetesTranslationRef, messages: { kubernetesContentPage.permissionAlert.title: Insufficient permissions, kubernetesContentPage.permissionAlert.message: You do not have permissions to view Kubernetes objects., }, }), createTranslationMessages({ ref: kubernetesClusterTranslationRef, messages: { kubernetesClusterContentPage.permissionAlert.title: Insufficient permissions, kubernetesClusterContentPage.permissionAlert.message: You do not have permissions to view Kubernetes objects., }, }), ] }, ...serviceLocatorMethod服务定位方式该配置决定如何判断一个组件运行在哪些集群中。可选值有三种multiTenant—— 假设所有组件都运行在你提供的全部集群上。这也是上文完整示例中使用的模式。从源码看MultiTenantServiceLocator 的实现会忽略实体信息直接返回集群供应商提供的全部集群其注释明确说明 every service is located on every cluster。singleTenant—— 假设当前组件运行在所提供的集群中的某一个集群上。配合实体上的backstage.io/kubernetes-cluster注解使用详见后文「Cluster Selection 注解」。catalogRelation—— 假设当前组件只运行在它所依赖dependsOn的全部集群上。对应实现见 CatalogRelationServiceLocator。clusterLocatorContinueOnError可选控制当一个或多个集群定位器失败时Kubernetes 后端是否继续返回其余集群设为true单个定位器的错误会被记录到日志其余成功定位器返回的集群仍然有效设为false默认值任何一个定位器失败都会导致整个集群列表请求失败。该选项在配置了多个集群定位器时非常有用例如某个 GKE 项目因权限问题导致定位失败不会阻塞其他所有集群的访问kubernetes: clusterLocatorContinueOnError: true源码层面getCombinedClusterSupplier见 cluster-locator/index.ts会读取kubernetes.clusterLocatorContinueOnError默认false当为true时改用Promise.allSettled逐一定位器收集结果失败的定位器仅记录Failed to retrieve clusters from cluster locator method #N日志而不会中断整体流程同时CombinedClustersSupplier还会对合并结果中重复的集群名打印Duplicate cluster name警告。clusterLocatorMethods集群定位器这是一个数组用于决定从哪里读取集群配置。可选定位器包括catalogconfiggkelocalKubectlProxy自定义KubernetesClustersSupplier在 cluster-locator/index.ts 中getCombinedClusterSupplier会根据每个定位器的type字段做分发catalog创建CatalogClusterLocator、config创建ConfigClusterLocator、gke创建GkeClusterLocator、localKubectlProxy创建LocalKubectlProxyClusterLocator遇到未知类型则抛出Unsupported kubernetes.clusterLocatorMethods错误。catalog从软件目录发现集群该定位器会从 Catalog 中收集type为kubernetes-cluster的Resource实体并将其作为 Kubernetes 插件可用的集群。要被该定位器识别资源必须带有以下三个注解kubernetes.io/api-server—— Kubernetes 控制平面的基础 URLkubernetes.io/api-server-certificate-authority—— Base64 编码的 PEM 格式 CA 证书包Backstage 会校验控制平面出示的证书是否由该 CA 签发kubernetes.io/auth-provider—— 与控制平面通信所采用的认证策略。此外还有大量其他注解可配置 Backstage 的通信方式详见plugin-kubernetes-common包导出的注解常量如kubernetes.io/oidc-token-provider、kubernetes.io/skip-metrics-lookup、kubernetes.io/skip-tls-verify、kubernetes.io/dashboard-url、kubernetes.io/dashboard-app、kubernetes.io/dashboard-parameters、kubernetes.io/aws-assume-role、kubernetes.io/aws-external-id等定义见 catalog-entity-constants.ts。下面是一个 Catalog 中集群资源示例apiVersion: backstage.io/v1alpha1 kind: Resource metadata: name: my-cluster annotations: kubernetes.io/api-server: https://my-cluster.example.com kubernetes.io/api-server-certificate-authority: # base64-encoded CA kubernetes.io/auth-provider: oidc kubernetes.io/oidc-token-provider: microsoft kubernetes.io/skip-metrics-lookup: true spec: type: kubernetes-cluster owner: user:guest需要特别注意的几点不要存储 Service Account Token把 Kubernetes 服务账号 token 放在 Catalog 实体的注解中是不安全的可能被 Catalog API 意外泄露因此不存在与config定位器serviceAccountToken字段对应的注解catalog定位器不支持serviceAccount认证策略会忽略试图使用它的 Catalog 实体。这一点在 CatalogClusterLocator.ts 中有明确实现toClusterDetails检测到authProvider serviceAccount时直接打印警告并返回undefined。URL 安全校验Catalog 来源的集群 API Server URL 必须使用 HTTPS且不得指向私有地址、link-local、回环地址或云元数据地址不满足条件的实体将被忽略并记录警告。本地开发例如127.0.0.1上的 minikube可在catalog定位器上通过dangerouslyAllowClusterUrls列出受信任主机名使其允许 HTTP 或非公网地址dangerouslyAllowSkipTLSVerify则启用 skip-TLS 注解kubernetes: clusterLocatorMethods: - type: catalog dangerouslyAllowClusterUrls: - 127.0.0.1 - localhost # dangerouslyAllowSkipTLSVerify: truekubernetes.io/skip-tls-verify注解只有在dangerouslyAllowSkipTLSVerify开启时才会被采用。另外只有kubernetes.io/*注解会被透传到集群认证元数据中serviceAccountToken等其他敏感键无法通过 Catalog 实体提供。配合自动发现使用该定位器与GkeEntityProviderbackstage/plugin-catalog-backend-module-gcp、AwsEKSClusterProcessorbackstage/plugin-catalog-backend-module-aws等采集流程配合时可以自动更新 Backstage 追踪的集群集合。dependsOn关系任何希望借助该 Resource 驱动 Catalog 实体页中 Kubernetes 详情的实体都需要建立dependsOn关系。示例如下apiVersion: backstage.io/v1alpha1 kind: Component metadata: annotations: backstage.io/kubernetes-id: dice-roller backstage.io/kubernetes-namespace: default name: dice-roller description: It rolls dice tags: - go spec: type: service lifecycle: production owner: guest dependsOn: [resource:my-cluster]该示例假设使用默认命名空间如果不是默认命名空间需要写成resource:my-namespace/my-cluster的形式。从实现上看CatalogClusterLocator.ts 的getClusters会以kind: Resource、spec.type: kubernetes-cluster以及三个必备注解存在为过滤条件调用 Catalog API再逐实体通过toClusterDetails转换为集群详情期间会执行 URL 安全校验与注解元数据过滤。config从 app-config 读取集群该定位器直接从应用配置中读取集群信息见上文完整示例中的clusters数组。以下是clusters.*下每个字段的详细说明。clusters.*.urlKubernetes 控制平面的基础 URL。可通过运行kubectl cluster-info命令从输出的 Kubernetes master 结果中获取。clusters.*.name用于表示该集群的名称在clusters数组中必须唯一。用户会在软件目录的 Kubernetes 插件中看到该值。源码中 ConfigClusterLocator.ts 会通过Set检测重复名称发现重复直接抛出Duplicate cluster name错误。clusters.*.title集群的人类可读名称在目录展示时会覆盖name字段用于显示。clusters.*.authProvider决定 Kubernetes 客户端如何对集群进行认证。有效值如下值说明aks使用用户在 Microsoft auth provider 获取的 AKS 访问令牌访问 AKS 集群上的 Kubernetes APIaws使用 AWS 凭证访问 EKS 集群中的资源azure使用 Azure Identity 访问集群中的资源google使用用户在 Google auth provider 获取的访问令牌访问 GKE 集群上的 Kubernetes APIgoogleServiceAccount使用 Google Cloud 服务账号凭证访问集群中的资源oidc使用 OIDC Token 认证 Kubernetes API使用时需同时设置oidcTokenProvider字段。注意集群必须支持 OIDC目前 AKS 集群不支持 OIDCserviceAccount使用 Kubernetes 服务账号访问 Kubernetes API使用时需同时设置serviceAccountToken字段否则 Backstage 需要以 in-cluster 方式运行更多说明参见 Kubernetes 认证。在源码层面每种认证策略都有独立实现类位于 plugins/kubernetes-backend/src/authAksStrategy、AwsIamStrategy、AzureIdentityStrategy、GoogleStrategy、GoogleServiceAccountStrategy、OidcStrategy、ServiceAccountStrategy、AnonymousStrategy并由buildDefaultAuthStrategyMap统一注册。ConfigClusterLocator.fromConfig在解析每个集群时会调用对应认证策略的validateCluster方法做配置校验校验失败会抛出Invalid cluster xxx: ...错误。clusters.*.skipTLSVerify决定 Kubernetes 客户端是否校验 API Server 出示的 TLS 证书。默认为false。clusters.*.skipMetricsLookup决定 Kubernetes 客户端是否查询 API Server 返回的 Pod 的 CPU/内存资源指标。默认为false。clusters.*.serviceAccountToken可选使用serviceAccount认证提供方时要使用的服务账号 token。需要注意除非你已有有效的凭证轮换机制或只有一个同时运行 Backstage 和全部服务的 Kubernetes 集群否则该认证方式在生产环境并不理想。假设你已在命名空间NAMESPACE中创建了名为SERVICE_ACCOUNT_NAME的服务账号且其拥有下文「基于角色的访问控制」一节所述的权限以下是获取长期有效 token 的两种方式Kubernetes 1.24 之前可以通过以下命令获取自动生成的tokenkubectl -n NAMESPACE get secret $(kubectl -n NAMESPACE get sa SERVICE_ACCOUNT_NAME -ojson \ | jq -r .secrets[0].name) -ojson \ | jq -r .data[token] \ | base64 --decodeKubernetes 1.24可通过创建 Secret 来获得长期 tokenkubectl apply -f - EOF apiVersion: v1 kind: Secret metadata: name: SECRET_NAME namespace: NAMESPACE annotations: kubernetes.io/service-account.name: SERVICE_ACCOUNT_NAME type: kubernetes.io/service-account-token EOF等待 token 控制器填充 token 后再执行kubectl -n NAMESPACE get secret SECRET_NAME -o go-template{{.data.token | base64decode}}如果集群设置了authProvider: serviceAccount但省略了serviceAccountToken字段Backstage 会忽略配置的 URL 和证书数据转而尝试通过 in-cluster 客户端访问 Kubernetes API。clusters.*.oidcTokenProvider可选该字段用于oidc认证提供方会使用已配置的 Backstage auth provider 提供的 id token 来认证集群。被选中的oidcTokenProvider需要正确配置在auth段下才能生效kubernetes: clusterLocatorMethods: - type: config clusters: - name: test-cluster url: http://localhost:8080 authProvider: oidc oidcTokenProvider: okta # This value needs to match a config under auth.providers auth: providers: okta: development: clientId: ${AUTH_OKTA_CLIENT_ID} clientSecret: ${AUTH_OKTA_CLIENT_SECRET} audience: ${AUTH_OKTA_AUDIENCE}前端默认支持以下oidcTokenProvider取值gitlab其 auth provider 的clientId应用应被授予openidscope、google、microsoft、okta、onelogin。请注意oidcTokenProvider只是 token 的签发方issuer你可以将任意一个与支持 OIDC 的集群搭配使用例如用microsoft作为 EKS 集群的 issuer。clusters.*.dashboardUrl可选指定管理该集群的 Kubernetes dashboard 链接。应通过dashboardApp属性指定 dashboard 应用类型以便正确格式化指向 Kubernetes 资源的链接否则会假定你运行的是标准standarddashboard对部分 dashboard如 GKE该属性可选因为 GKE 需要额外的dashboardParameters参数。clusters.*.dashboardApp可选指定提供 Kubernetes dashboard 的应用用于格式化 dashboard 内指向 Kubernetes 对象的链接。支持的 dashboard 包括aks、eks、gke、headlamp、openshift、rancher、standard。其中并非全部已实现欢迎贡献代码。默认会回退到 Kubernetes 项目提供的标准 dashboardstandard它可运行在任何 Kubernetes 集群上。注意事项对于gke应用必须在dashboardParameters中提供额外信息可以在应用项目中向clusterLinksFormatters字典注册自定义 formatterimport { clusterLinksFormatters } from backstage/plugin-kubernetes; clusterLinksFormatters.myDashboard (options) ...;plugin-kubernetes-react包中src/api/formatters目录提供了真实的 formatter 实现示例可作参考。clusters.*.dashboardParameters可选为选定的dashboardAppformatter 指定额外信息。虽然它是可选的但对某些 dashboard如 GKE可能是必填的。GKE 必填参数名称说明projectId包含你的 Kubernetes 集群的 GCP 项目 IDregion包含你的 Kubernetes 集群的 GCP 区域clusterName在projectIdGCP 项目内、你的 Kubernetes 集群的名称注意如果将 GKE 集群定位器的exposeDashboard属性设为true它会自动提供dashboardApp和dashboardParameters的值。示例kubernetes: serviceLocatorMethod: type: multiTenant clusterLocatorMethods: - type: config clusters: - url: http://127.0.0.1:9999 name: my-cluster dashboardApp: gke dashboardParameters: projectId: my-project region: us-east1 clusterName: my-clusterclusters.*.caData可选Base64 编码的 PEM 格式 CA 证书包。Kubernetes 客户端会校验 API Server 出示的 TLS 证书由该 CA 签发。可通过查看kubeconfig文件通常在~/.kube/config中的clusters[*].cluster.certificate-authority-data获取该值。对于 GKE可执行以下命令获取gcloud container clusters describe YOUR_CLUSTER_NAME \ --zoneYOUR_COMPUTE_ZONE \ --formatvalue(masterAuth.clusterCaCertificate)clusters.*.caFile可选指向 PEM 格式 CA 证书包的文件系统路径位于运行 Backstage 进程的主机上。Kubernetes 客户端会校验 API Server 出示的 TLS 证书由该 CA 签发。注意只有通过config集群定位器在 app-config 中定义的集群才能以这种方式配置。clusters.*.customResources可选配置在返回实体的 Kubernetes 资源时需要在集群中查找哪些自定义资源CRD规范与全局customResources一致见下文。Headlamp dashboard 的两种配置方式使用headlamp作为 dashboard 时有两种配置外部 Headlamp 实例kubernetes: clusterLocatorMethods: - type: config clusters: - url: http://127.0.0.1:9999 name: my-cluster dashboardUrl: http://headlamp.example.com # Your Headlamp instance URL dashboardApp: headlamp dashboardParameters: clusterName: my-cluster # Optional, defaults to default内部 Headlamp使用 Backstage 的 Headlamp 插件时kubernetes: clusterLocatorMethods: - type: config clusters: - url: http://127.0.0.1:9999 name: my-cluster dashboardApp: headlamp dashboardParameters: internal: true headlampRoute: /headlamp # Optional, defaults to /headlamp clusterName: my-cluster # Optional, defaults to defaultgke自动发现 GKE 集群该定位器面向运行在 Google Cloud 项目中的 GKE 集群使用google认证机制并通过GOOGLE_APPLICATION_CREDENTIALS环境变量配置 Google Cloud 服务账号。示例- type: gke projectId: gke-clusters region: europe-west1 # optional authProvider: google # optional skipTLSVerify: false # optional skipMetricsLookup: false # optional exposeDashboard: false # optional matchingResourceLabels: # optional - key: environment value: production以上配置会让 Kubernetes 插件连接项目gke-clusters中、区域europe-west1内的所有 GKE 集群。各字段说明projectId要在其中查找 Kubernetes 集群的 Google Cloud 项目必填。region可选要在其中查找集群的 Google Cloud 区域默认为所有区域。authProvider可选设置发现集群和收集资源信息时的认证方式。默认为google利用登录用户的 Google OAuth 凭证设为googleServiceAccount则利用 Application Default Credentials可通过在 Backstage 后端设置GOOGLE_APPLICATION_CREDENTIALS环境变量指向服务账号 JSON 密钥文件不推荐来指定账号。skipTLSVerify可选是否校验 API Server 的 TLS 证书默认为false。skipMetricsLookup可选是否查询 Pod 的 CPU/内存指标默认为false。exposeDashboard可选是否自动配置dashboardApp和dashboardParameters以从 Kubernetes 插件暴露 GKE dashboard默认为false。matchingResourceLabels可选键值标签数组用于过滤掉没有匹配资源标签的集群。从源码看GkeClusterLocator.ts 使用google-cloud/container的ClusterManagerClient调用listClusters获取集群列表再按matchingResourceLabels逐个过滤当exposeDashboard开启时会自动生成dashboardApp: gke与包含projectId、region、clusterName的dashboardParameters。它还支持endpointType: public | dns选项默认public来选择集群端点获取方式并通过runPeriodically按刷新间隔定期刷新集群列表。localKubectlProxy本地开发专用该定位器假定本地有一个使用默认端口8001运行的kubectl proxy进程。注意此定位器仅用于本地开发不应在生产环境使用。从源码看LocalKubectlProxyLocator.ts 会返回一个名为local、URL 为http://localhost:8001、skipMetricsLookup: true的集群并主动通过 DNS 解析localhost优先 IPv4与kubectl proxy默认监听127.0.0.1的行为保持一致来确定实际访问地址。自定义KubernetesClustersSupplier如果基于配置的集群定位器无法满足你的用例还可以实现自定义的KubernetesClustersSupplier详见 安装文档 中的「Custom cluster discovery」一节。proxyKubernetes API 代理配置可选/api/kubernetes/proxy代理的选项。目前支持的子配置为proxy.middlewareCache代理按集群缓存http-proxy-middleware实例条目在集群详情变化、TTL 到期或缓存达到大小上限时刷新。来自config的集群在后端启动时加载修改app-config后仍需要重启才能刷新来自Catalog及其他动态集群源的集群一旦集群供应商返回新详情无需重启即可生效。kubernetes: proxy: middlewareCache: maxSize: 100 ttl: milliseconds: 60000maxSize—— 缓存的最大中间件实例数默认100ttl.milliseconds—— 缓存条目存活时间毫秒默认60000。源码层面ProxyMiddlewareCache.ts 定义了默认值常量DEFAULT_PROXY_MIDDLEWARE_CACHE_TTL_MS 60_000与DEFAULT_PROXY_MIDDLEWARE_CACHE_MAX_SIZE 100并通过buildProxyMiddlewareFingerprint基于url、skipTLSVerify、caData、caFile生成缓存指纹集群详情一旦变化即可触发缓存失效重建。customResources全局自定义资源可选配置在返回实体的 Kubernetes 资源时默认要查找哪些自定义资源。注意集群级别的customResources会覆盖该全局配置。默认为空数组。示例--- kubernetes: customResources: - group: argoproj.io apiVersion: v1alpha1 plural: rollouts每个条目包含三个字段customResources.*.group—— 自定义资源的 groupcustomResources.*.apiVersion—— 自定义资源的apiVersioncustomResources.*.plural—— 表示该自定义资源的复数形式。apiVersionOverridesAPI 版本覆盖可选用于覆盖请求对应对象时所使用的 API 版本。如果集群运行的是旧版 Kubernetes可以用该配置把默认 API 版本覆盖为集群支持的版本--- kubernetes: apiVersionOverrides: cronjobs: v1beta1objectTypes对象类型覆盖可选覆盖从集群拉取的 Kubernetes 对象类型。默认对象类型包括podsservicesconfigmapslimitrangesresourcequotasdeploymentsreplicasetshorizontalpodautoscalersjobscronjobsingressesstatefulsetsdaemonsets你可以用该配置只保留需要的对象类型但目前唯一可额外追加的对象类型是secrets。示例--- kubernetes: objectTypes: - configmaps - deployments - limitranges - pods - services - statefulsets - secrets基于角色的访问控制RBACKubernetes 插件所需的当前 RBAC 权限为集群范围的只读权限下面的清单描述了需要访问的对象可确保插件正常工作--- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: backstage-read-only rules: - apiGroups: - * resources: - pods - pods/log - configmaps - services - deployments - replicasets - horizontalpodautoscalers - ingresses - statefulsets - limitranges - resourcequotas - daemonsets verbs: - get - list - watch - apiGroups: - batch resources: - jobs - cronjobs verbs: - get - list - watch - apiGroups: - metrics.k8s.io resources: - pods verbs: - get - list将 Kubernetes 组件呈现在 Catalog 实体上完成集群配置后还需要把实体的 Kubernetes 对象「暴露」到软件目录中。Backstage 提供两种方式标签选择器label selector的优先级高于注解/服务 ID。方式一公共backstage.io/kubernetes-id标签添加实体注解要让 Backstage 检测到实体拥有 Kubernetes 组件需要在实体的catalog-info.yaml中添加如下注解annotations: backstage.io/kubernetes-id: dice-roller添加命名空间注解实体可以带backstage.io/kubernetes-namespace注解使实体的 Kubernetes 资源通过该命名空间进行查找annotations: backstage.io/kubernetes-namespace: dice-space为 Kubernetes 组件打标签为了让 Kubernetes 组件作为实体的一部分出现在软件目录中Kubernetes 组件自身可以打上如下标签标签值应等于 Backstage 实体名backstage.io/kubernetes-id: BACKSTAGE_ENTITY_NAME在plugin-kubernetes-common中该注解由常量KUBERNETES_ANNOTATION backstage.io/kubernetes-id定义见 catalog-entity-constants.ts。插件的错误检测测试夹具如 deploy-healthy.json、pod-crashing.json中也以dice-roller为例展示了backstage.io/kubernetes-id同时出现在 Deployment/Pod 标签与注解中的真实形态可作参考。方式二标签选择器查询注解你可以编写自定义的标签选择器查询Backstage 会用它来查找对象与kubectl --selectoryour query here类似backstage.io/kubernetes-label-selector: appmy-app,componentfront-end该注解在源码中对应常量KUBERNETES_LABEL_SELECTOR_QUERY_ANNOTATION backstage.io/kubernetes-label-selector见 catalog-entity-constants.ts其值应为合法的 Kubernetes 标签选择器查询字符串。Cluster Selection 注解仅singleTenant适用该注解仅适用于serviceLocatorMethod为singleTenant的场景用于从所有已定义的集群中选择实体所在的单个集群backstage.io/kubernetes-cluster: dice-cluster在上面的例子中我们在实体catalog-info.yaml上配置了backstage.io/kubernetes-cluster注解指定当前组件运行在名为dice-cluster的单个集群中因此该集群必须已按上文「配置 Kubernetes 集群」一节在app-config.yaml的 Kubernetes 集群配置中定义。如果未指定该注解Backstage默认从所有已定义的集群获取。源码层面SingleTenantServiceLocator.ts 在实体存在backstage.io/kubernetes-cluster注解时会按集群name与注解值精确匹配过滤集群列表未配置注解时则返回全部集群。小结与配置检查清单完成 Backstage Kubernetes 集成配置本质上就是回答三个问题集群从哪来通过clusterLocatorMethods选择config静态配置、catalog目录驱动、gke云自动发现或localKubectlProxy本地调试之一或组合并用clusterLocatorContinueOnError控制容错组件在哪个集群通过serviceLocatorMethod选择multiTenant/singleTenant/catalogRelation配合实体注解精确定位资源怎么关联在catalog-info.yaml中为实体添加backstage.io/kubernetes-id或backstage.io/kubernetes-label-selector、backstage.io/kubernetes-namespace、backstage.io/kubernetes-cluster注解并为集群账号授予前文backstage-read-only的只读 RBAC 权限。建议在接入新集群时按以下顺序自检先通过kubectl cluster-info确认url与证书caData/caFile正确再确认authProvider与对应的认证策略及serviceAccountToken或oidcTokenProvider是否配套随后核对 RBAC 权限清单是否覆盖所需对象类型最后在软件目录实体上补充关联注解并在页面中验证资源展示。相关源码可进一步参考 kubernetes-backend 的集群定位与认证实现、认证策略实现 以及 kubernetes-common 的注解常量定义安装与认证的完整流程见 安装文档 与 认证文档。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考