Backstage Kubernetes 插件安装与配置指南让软件目录呈现集群资源【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageKubernetes 功能是 Backstage 的一个插件以软件目录Software Catalog中实体页面的一个 Tab 形式呈现。本文围绕 Kubernetes 安装文档 的核心脉络完整讲解前端插件、后端插件的安装步骤、自定义集群发现Custom Cluster Discovery的扩展机制并衔接集群配置、认证与故障排查帮助读者在本地或生产环境中快速把 Kubernetes 资源接进 Backstage 软件目录。插件概览前端与后端的分工Backstage 的 Kubernetes 功能由两个插件组成backstage/plugin-kubernetes前端插件以可读的方式把集群信息暴露给最终用户并为软件目录中的实体提供 Kubernetes Tabbackstage/plugin-kubernetes-backend后端插件封装了与 Kubernetes 集群建立连接、收集相关信息的底层机制同时支持通过异步迭代器 watch 资源以接收实时变更通知。从源码看前端插件的入口在 plugins/kubernetes/src/plugin.ts它注册了KubernetesBackendClient、KubernetesProxyClient、KubernetesAuthProviders以及集群链接格式化器等 API后端插件的入口在 plugins/kubernetes-backend/src/plugin.ts通过createBackendPlugin暴露集群供应Cluster Supplier、认证策略Auth Strategy、资源抓取Fetcher、服务定位Service Locator等扩展点。如果你还没有搭建好 Backstage 应用请先阅读入门指南。第一步安装 Kubernetes 前端插件在 Backstage 仓库根目录下执行yarn --cwd packages/app add backstage/plugin-kubernetes安装完成后插件会通过默认的特性发现机制default feature discovery自动在应用中可用它为关联了 Kubernetes 资源的实体页面添加一个 Kubernetes Tab。更多细节和替代安装方式参见安装插件指南。定制 Tab 的实体过滤器默认情况下只要实体标注了 Kubernetes 相关注解Kubernetes Tab 就会显示。可以在app-config.yaml中通过app.extensions定制该 Tab 的实体过滤器例如只让带有backstage.io/kubernetes-id注解的实体显示app: extensions: - entity-content:kubernetes/kubernetes: config: filter: metadata.annotations.backstage.io/kubernetes-id: $exists: true从源码可以确认这一机制的默认行为plugins/kubernetes/src/alpha/entityContents.tsx 中EntityContentBlueprint的默认filter是注解backstage.io/kubernetes-id存在或注解backstage.io/kubernetes-label-selector存在$any组合。因此在app-config.yaml中覆盖filter时需要自行包含所有希望生效的匹配规则。第二步安装 Kubernetes 后端插件前端要正常工作还必须安装后端插件。首先添加后端包yarn --cwd packages/backend add backstage/plugin-kubernetes-backend然后在后端入口文件packages/backend/src/index.ts中注册该插件const backend createBackend(); // Other plugins... backend.add(import(backstage/plugin-kubernetes-backend)); backend.start();至此Kubernetes 前端与后端插件已添加到 Backstage 应用中。从源码看后端插件在启动时检查配置中是否存在kubernetes段若缺少有效配置会记录警告日志Failed to initialize kubernetes backend: valid kubernetes config is missing相关逻辑见 plugins/kubernetes-backend/src/plugin.ts。第三步自定义集群发现Custom Cluster Discovery如果内置的集群定位器都不满足你的场景可以实现自定义的KubernetesClustersSupplier。下面是官方文档给出的简化示例需安装backstage/plugin-kubernetes-node与luxon依赖import { createBackend } from backstage/backend-defaults; import { createBackendModule } from backstage/backend-plugin-api; import { Duration } from luxon; import { ClusterDetails, KubernetesClustersSupplier, kubernetesClusterSupplierExtensionPoint, kubernetesServiceLocatorExtensionPoint, } from backstage/plugin-kubernetes-node; export class CustomClustersSupplier implements KubernetesClustersSupplier { constructor(private clusterDetails: ClusterDetails[] []) {} static create(refreshInterval: Duration) { const clusterSupplier new CustomClustersSupplier(); // setup refresh, e.g. using a copy of runPeriodically from the kubernetes-backend plugin runPeriodically( () clusterSupplier.refreshClusters(), refreshInterval.toMillis(), ); return clusterSupplier; } async refreshClusters(): Promisevoid { this.clusterDetails []; // fetch from somewhere } async getClusters(): PromiseClusterDetails[] { return this.clusterDetails; } } const backend createBackend(); export const kubernetesModuleCustomClusterDiscovery createBackendModule({ pluginId: kubernetes, moduleId: custom-cluster-discovery, register(env) { env.registerInit({ deps: { clusterSupplier: kubernetesClusterSupplierExtensionPoint, serviceLocator: kubernetesServiceLocatorExtensionPoint, }, async init({ clusterSupplier, serviceLocator }) { // simple replace of the internal dependency clusterSupplier.addClusterSupplier( CustomClustersSupplier.create(Duration.fromObject({ minutes: 60 })), ); // theres also the ability to get access to some of the default implementations of the extension points where // necessary: serviceLocator.addServiceLocator( async ({ getDefault, clusterSupplier }) { // get access to the default service locator: const defaultImplementation await getDefault(); // build your own with the clusterSupplier dependency: return new MyNewServiceLocator({ clusterSupplier }); }, ); }, }); }, }); // Other plugins... backend.add(import(backstage/plugin-kubernetes-backend)); backend.add(kubernetesModuleCustomClusterDiscovery); backend.start();[!NOTE] 该示例使用了backstage/plugin-kubernetes-node和luxon包中的内容需要为示例能够原样运行而添加这些依赖。背后的实现原理从源码可以进一步理解这个例子的运作方式参考的runPeriodically工具函数实现在 plugins/kubernetes-backend/src/service/runPeriodically.ts它以固定间隔重复执行传入的异步函数静默忽略异常并返回一个可用于停止循环的取消函数——示例中的每 60 分钟刷新一次集群列表正是建立在该机制上。扩展点的注册在 plugins/kubernetes-backend/src/plugin.tskubernetesClusterSupplierExtensionPoint只允许注册一个集群供应器重复注册会抛出 Multiple Kubernetes Cluster Suppliers is not supported at this time 错误addClusterSupplier同时接受实例或工厂函数两种形式。serviceLocator.addServiceLocator的回调中getDefault()会解析到默认的服务定位器实现可用于包装或组合默认行为而不是完全替换。第四步配置集群安装完插件代码后需要继续配置 Kubernetes 集成。配置分为两大步骤让后端能够从你的 Kubernetes 集群收集对象让这些 Kubernetes 对象在软件目录实体上呈现出来。集群配置的完整示例以下是一份完整的app-config.yaml中kubernetes配置示例kubernetes: 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核心配置项速览配置段作用serviceLocatorMethod决定如何判断组件运行在哪些集群上multiTenant所有组件运行在所有集群、singleTenant当前组件运行在其中一个集群、catalogRelation当前组件只运行在其依赖的所有集群上clusterLocatorMethods数组决定从哪里获取集群配置支持catalog、config、gke、localKubectlProxy以及自定义KubernetesClustersSupplierclusterLocatorContinueOnError可选默认false设为true时单个定位器失败只记录日志其余定位器仍返回集群避免一个 GKE 项目权限问题阻塞所有集群frontend.podDelete.enabled可选控制容器面板中删除 Pod按钮的可见性默认falsecustomResources可选默认空数组配置默认要查找的自定义资源如 Argo RolloutsapiVersionOverrides可选兼容旧版 Kubernetes 时覆盖对象请求使用的 API 版本如cronjobs: v1beta1objectTypes可选覆盖默认拉取的对象类型默认类型包括pods、services、configmaps、deployments、replicasets、ingresses、statefulsets、daemonsets等目前唯一可额外添加的类型是secretsproxy.middlewareCache可选配置 Kubernetes API 代理的中间件缓存maxSize默认100ttl.milliseconds默认60000authProvider 的取值值说明aks使用用户在 Microsoft auth provider 的 AKS 访问令牌访问 AKS 集群 APIaws使用 AWS 凭证访问 EKS 集群资源azure使用 Azure Identity 访问集群资源google使用用户在 Google auth provider 的访问令牌访问 GKE 集群googleServiceAccount使用 Google Cloud 服务账号凭证访问集群资源oidc使用 OIDC Token 认证需同时设置oidcTokenProvider且集群需支持 OIDC当前 AKS 不支持serviceAccount使用 Kubernetes 服务账号令牌需同时设置serviceAccountToken或让 Backstage 以集群内in-cluster方式运行更多认证细节参见 Kubernetes 认证文档服务端认证 Provideraws、azure、googleServiceAccount、localKubectlProxy、serviceAccount认证的是应用本身任何登录用户包括 guest获得相同权限客户端 Provideraks、google、oidc则认证用户每个用户被提示凭证并按各自授权访问集群。让实体关联 Kubernetes 资源有两种方式把 Kubernetes 组件挂到实体上label selector 优先级高于注解/service id公共标签backstage.io/kubernetes-id在实体的catalog-info.yaml中添加注解backstage.io/kubernetes-id: dice-roller可用backstage.io/kubernetes-namespace注解指定命名空间同时给 Kubernetes 组件本身打上backstage.io/kubernetes-id: BACKSTAGE_ENTITY_NAME标签。自定义标签选择器注解backstage.io/kubernetes-label-selector: appmy-app,componentfront-end语义类似kubectl --selector。集群选择注解backstage.io/kubernetes-cluster: dice-cluster仅适用于singleTenant定位方式用于指定实体所在的单个集群未指定时默认从所有已定义集群拉取。若使用catalog集群定位器Resource实体需带kubernetes.io/api-server、kubernetes.io/api-server-certificate-authority、kubernetes.io/auth-provider等注解且使用该资源的组件实体需建立dependsOn: [resource:my-cluster]关系非默认命名空间写作resource:my-namespace/my-cluster。RBAC 权限后端插件所需的权限为集群级只读下面这份 Kubernetes 清单覆盖了插件正常工作所需的全部对象--- 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 信息没有在实体上显示先检查集群是否已与 Backstage 建立连接可以直接调用后端接口验证curl --location --request POST {{backstage-backend-url}}:{{backstage-backend-port}}/api/kubernetes/services/:service-entity-name \ --header Content-Type: application/json \ --data-raw { entity: { metadata: { name: service-entity-name } } } 正常响应应包含来自集群的资源{ items: [ { cluster: { name: cluster-name }, resources: [ { type: services, resources: [ { metadata: { creationTimestamp: 2022-03-13T13:52:46.000Z, labels: { app: k8s-app-name, backstage: selector, backstage.io/kubernetes-id: service-entity-name }, name: k8s-app-name, namespace: namespace } } ] }, { type: pods, resources: [] } ], errors: [] } ] }最常见的问题注解与标签不匹配Kubernetes Tab 不显示任何内容的最常见原因是catalog 注解与 Kubernetes 资源上的标签不匹配。官方建议给 Kubernetes 相关资源service.yaml、deployment.yaml、ingress.yaml打上backstage.io/kubernetes-id: entity-service-name标签在 catalog-info.yaml 中使用标签选择器注解backstage.io/kubernetes-label-selector: label-selector。k8s-app-name与service-entity-name可以不同但如果你希望 Kubernetes 与 Backstage 命名保持一致建议使用相同名称。从源码看标签选择器在请求时被转换为 Kubernetes API 的labelSelector参数相关逻辑见 KubernetesFetcher.ts。小结安装 Backstage Kubernetes 插件的完整链路是安装前端插件 → 安装后端插件并注册 → 可选实现自定义集群发现 → 配置集群与认证 → 为实体添加注解/标签 → 按需排查。前端负责呈现后端通过 Cluster Supplier、Auth Strategy、Fetcher、Service Locator 等扩展点封装了与集群交互的全部细节实际抓取逻辑包括 Pod 指标通过metrics.k8s.io/v1beta1查询可参考 plugins/kubernetes-backend/src/service 目录下的实现。关于配置项、认证策略、代理、watch 与审计事件可继续阅读同目录下的 configuration.md、authentication.md、proxy.md、watch.md 与 audit-events.md。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考