Kubernetes 통합 구성하기

원문 보기 위키 갱신 2026.10.07

Backstage Kubernetes 통합을 구성하는 데는 두 단계가 있어요.

백엔드가 여러분의 Kubernetes 클러스터에서 객체를 수집하도록 활성화.
Kubernetes 객체를 카탈로그 엔티티에 표시(surfacing).

출처: 문서

본문

Backstage Kubernetes 통합을 구성하는 데는 두 단계가 있어요.

백엔드가 여러분의 Kubernetes 클러스터에서 객체를 수집하도록 활성화.
Kubernetes 객체를 카탈로그 엔티티에 표시(surfacing).

Kubernetes 클러스터 구성하기

다음은 app-config.yaml의 완전한 예시 항목이에요.

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

`frontend` (선택)

일부 프론트엔드 기능을 구성하는 데 사용되는 배열이에요.

유효한 값은 다음과 같아요.

podDelete

`podDelete` (선택)

컨테이너 패널에서 파드 삭제 버튼의 동작을 구성해요.

유효한 구성은 다음과 같아요.

enabled

`enabled`

이 구성은 이 기능의 가시성을 제어해요.

유효한 값은 다음과 같아요.

true
false

기본값은 false예요.

국제화(Internationalization)

일부 컴포넌트의 텍스트를 사용자 지정하거나 번역하려면 다음 접근 방식을 사용하세요.

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 - 모든 컴포넌트가 제공된 모든 클러스터에서 실행된다고 가정해요.
singleTenant - 현재 컴포넌트가 제공된 클러스터 중 하나의 클러스터에서 실행된다고 가정해요.
catalogRelation - 현재 컴포넌트가 의존하는 모든 클러스터에서만 실행된다고 가정해요.

`clusterLocatorContinueOnError` (선택)

하나 이상의 클러스터 locator가 실패할 때 Kubernetes 백엔드가 클러스터 반환을 계속할지 제어해요. true로 설정하면 개별 locator의 오류가 기록되고 나머지 성공한 locator의 클러스터는 여전히 반환돼요. false(기본값)로 설정하면 단일 locator 실패가 전체 클러스터 목록 요청을 실패하게 해요.

이것은 여러 클러스터 locator를 구성했고 한 소스의 문제(예: 단일 GKE 프로젝트의 권한 오류)가 다른 모든 클러스터를 차단하는 것을 피하고 싶을 때 유용해요.

kubernetes:
  clusterLocatorContinueOnError: true

기본값은 false예요.

`clusterLocatorMethods`

클러스터 구성을 어디에서 검색할지 결정하는 데 사용되는 배열이에요.

유효한 클러스터 locator 메서드는 다음과 같아요.

catalog
config
gke
localKubectlProxy
사용자 지정 KubernetesClustersSupplier

`catalog`

이 클러스터 locator 메서드는 카탈로그에서 kubernetes-cluster 유형의 Resource를 수집해 Kubernetes 플러그인 목적에 맞게 클러스터로 취급해요. 리소스가 이 메서드에 감지되려면 다음 주석(코드에서 여기서 보듯)도 있어야 해요.

kubernetes.io/api-server: Kubernetes 제어 평면의 기본 URL을 나타내요.
kubernetes.io/api-server-certificate-authority: PEM 형식의 base64 인코딩 인증 기관 번들을 포함해요. Backstage는 제어 평면이 이 기관이 서명한 인증서를 제시하는지 확인할 거예요.
kubernetes.io/auth-provider: 제어 평면과 인증할 전략을 나타내요.

Backstage가 통신하는 방식을 구성하기 위해 클러스터 리소스에 적용할 수 있는 다른 주석도 많으며, API 참조의 여기에 문서화되어 있어요. 다음은 카탈로그에 있는 클러스터 예시를 보여주는 YAML 스니펫이에요.

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

카탈로그 엔티티의 주석에 Kubernetes 서비스 계정 토큰을 저장하는 것은 안전하지 않다는 점에 유의하세요(카탈로그 API로 쉽게 우연히 노출될 수 있음). 따라서 config 클러스터 locator가 사용하는 serviceAccountToken 필드에 해당하는 주석은 없어요. 이에 따라 catalog 클러스터 locator는 serviceAccount 인증 전략을 지원하지 않으며, 그것을 사용하려는 카탈로그 엔티티를 무시해요.

Catalog에서 제공하는 클러스터 API 서버 URL은 HTTPS를 사용해야 하며 프라이빗, 링크-로컬, 루프백, 클라우드 메타데이터 주소를 대상으로 하면 안 돼요. 이 검사를 통과하지 못하는 엔티티는 무시되고 경고가 기록돼요. 로컬 개발(예: 127.0.0.1의 minikube)을 위해 운영자는 catalog 클러스터 locator 메서드의 dangerouslyAllowClusterUrls에 신뢰할 수 있는 호스트 이름을 나열해 그 호스트들이 HTTP나 비공개 주소를 사용할 수 있게 할 수 있어요. dangerouslyAllowSkipTLSVerify는 skip-TLS 주석을 활성화해요.

kubernetes:
  clusterLocatorMethods:
    - type: catalog
      dangerouslyAllowClusterUrls:
        - '127.0.0.1'
        - 'localhost'
      # dangerouslyAllowSkipTLSVerify: true

kubernetes.io/skip-tls-verify 주석은 dangerouslyAllowSkipTLSVerify가 활성화되지 않는 한 무시돼요. 클러스터 인증 메타데이터에는 kubernetes.io/* 주석만 전달돼요. serviceAccountToken과 기타 민감한 키는 카탈로그 엔티티에서 제공될 수 없어요.

이 메서드는 GkeEntityProvider(설치는 여기에 문서화)나 AwsEKSClusterProcessor 같은 수집 절차와 함께 사용하면 Backstage가 추적하는 클러스터 집합을 자동으로 업데이트하는 데 매우 유용할 수 있어요.

이 메서드가 작동하려면 이 Resource를 사용해 Catalog의 Entity 페이지에서 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처럼 포함해야 해요.

`config`

이 클러스터 locator 메서드는 app-config(아래 참조)에서 클러스터 정보를 읽어요.

`clusters`

config 클러스터 locator 메서드가 Kubernetes 클라이언트를 구성하는 데 사용해요.

`clusters.*.url`

Kubernetes 제어 평면의 기본 URL이에요. kubectl cluster-info 명령을 실행한 "Kubernetes master" 결과를 사용해 찾을 수 있어요.

`clusters.*.name`

이 클러스터를 나타내는 이름으로, clusters 배열 안에서 고유해야 해요. 사용자는 Software Catalog Kubernetes 플러그인에서 이 값을 볼 거예요.

`clusters.*.title`

클러스터의 사람이 읽을 수 있는 이름이에요. 이 값은 카탈로그에서 표시 목적으로 name 필드를 덮어써요.

`clusters.*.authProvider`

Kubernetes 클라이언트가 Kubernetes 클러스터와 인증하는 방식을 결정해요. 유효한 값은 다음과 같아요.

	Value	Description
	`aks`	This will use a user's AKS access token from the Microsoft auth provider to access the Kubernetes API on AKS clusters.
	`aws`	This will use AWS credentials to access resources in EKS clusters
	`azure`	This will use Azure Identity to access resources in clusters
	`google`	This will use a user's Google access token from the Google auth provider to access the Kubernetes API on GKE clusters.
	`googleServiceAccount`	This will use the Google Cloud service account credentials to access resources in clusters
	`oidc`	This will use Oidc Tokens to authenticate to the Kubernetes API. When this is used the `oidcTokenProvider` field should also be set. Please note the cluster must support OIDC, at the time of writing AKS clusters do not support OIDC.
	`serviceAccount`	This will use a Kubernetes service account to access the Kubernetes API. When this is used the `serviceAccountToken` field should also be set, or else Backstage should be running in-cluster.

추가 설명은 Kubernetes 인증 섹션을 확인하세요.

`clusters.*.skipTLSVerify`

Kubernetes 클라이언트가 API 서버가 제시하는 TLS 인증서를 검증할지 결정해요. 기본값은 false예요.

`clusters.*.skipMetricsLookup`

Kubernetes 클라이언트가 API 서버가 반환한 파드에 대한 리소스 지표 CPU/메모리를 조회할지 결정해요. 기본값은 false예요.

`clusters.*.serviceAccountToken` (선택)

serviceAccount 인증 프로바이더를 사용할 때 사용할 서비스 계정 토큰이에요. 효과적인 자격 증명 순환 절차가 있거나 Backstage와 모든 서비스가 실행되는 단일 Kubernetes 클러스터가 없다면, 이 인증 프로바이더는 아마 프로덕션에 이상적이지 않다는 점에 유의하세요.

NAMESPACE 네임스페이스에 SERVICE_ACCOUNT_NAME이라는 서비스 계정을 이미 만들었고 충분한 권한이 있다고 가정하면, 이 프로바이더에 사용할 장기(long-lived) 서비스 계정 토큰을 얻는 몇 가지 예시 절차는 다음과 같아요.

Kubernetes 1.24 이전 버전에서는 서비스 계정에 대한 (자동 생성된) 토큰을 다음으로 얻을 수 있었어요.

kubectl -n <NAMESPACE> get secret $(kubectl -n <NAMESPACE> get sa <SERVICE_ACCOUNT_NAME> -o=json \| jq -r '.secrets[0].name') -o=json \| jq -r '.data["token"]' \| base64 --decode

Kubernetes 1.24+에서는 이 가이드에 설명된 대로, 시크릿을 만들어 장기 토큰을 얻을 수 있어요.

kubectl 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

토큰 컨트롤러가 토큰을 채울 때까지 기다린 뒤 다음으로 검색해요.

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 인증 프로바이더의 id 토큰을 사용해 클러스터에 인증할 거예요. 선택한 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}

프론트엔드가 기본으로 지원하는 값은 gitlab(인증 프로바이더가 사용하는 clientId를 가진 애플리케이션에 openid 스코프가 부여되어야 함), google, microsoft, okta, onelogin이에요.

oidcTokenProvider는 토큰의 발급자일 뿐이며, EKS 클러스터에 발급자로 microsoft를 사용하는 것처럼 OIDC 활성 클러스터와 함께 이 중 아무거나 사용할 수 있다는 점에 유의하세요.

`clusters.*.dashboardUrl` (선택)

이 클러스터를 관리하는 Kubernetes 대시보드에 대한 링크를 지정해요.

Kubernetes 리소스에 대한 링크를 올바르게 형식화하려면 dashboardApp 속성으로 대시보드에 사용되는 앱을 지정해야 한다는 점에 유의하세요. 그렇지 않으면 표준 대시보드를 실행 중이라고 가정할 거예요.

또한 이 속성은 dashboardParameters 옵션에 추가 매개변수가 필요한 GKE 같은 일부 종류의 대시보드에는 선택 사항이라는 점도 유의하세요.

`clusters.*.dashboardApp` (선택)

Kubernetes 대시보드를 제공하는 앱을 지정해요.

이것은 대시보드 안의 Kubernetes 객체에 대한 링크를 형식화하는 데 사용될 거예요.

지원되는 대시보드는 aks, eks, gke, headlamp, openshift, rancher, standard예요. 하지만 그중 전부가 아직 구현된 것은 아니므로 기여해주세요!

참고로 기본값은 Kubernetes 프로젝트가 제공하는 일반 대시보드(standard)이며, 어떤 Kubernetes 클러스터에서도 실행될 수 있어요.

gke 앱의 경우 dashboardParameters 옵션에 추가 정보를 제공해야 한다는 점에 유의하세요.

앱 프로젝트의 clusterLinksFormatters 사전에 등록해 나만의 formatter를 추가할 수 있다는 점도 유의하세요.

예시:

import { clusterLinksFormatters } from '@backstage/plugin-kubernetes';
clusterLinksFormatters.myDashboard = (options) => ...;

실제 예시는 https://github.com/backstage/backstage/tree/master/plugins/kubernetes-react/src/api/formatters 도 참고하세요.

`clusters.*.dashboardParameters` (선택)

선택한 dashboardApp formatter에 대한 추가 정보를 지정해요.

dashboardParameters는 선택 사항이지만 GKE 같은 일부 대시보드에는 필수일 수 있다는 점에 유의하세요.

GKE에 필요한 매개변수

	Name	Description
	`projectId`	the ID of the GCP project containing your Kubernetes clusters
	`region`	the region of GCP containing your Kubernetes clusters
	`clusterName`	the name of your kubernetes cluster, within your `projectId` GCP project

GKE 클러스터 locator는 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-cluster

`clusters.*.caData` (선택)

PEM 형식의 base64 인코딩 인증 기관 번들이에요. Kubernetes 클라이언트는 API 서버가 제시하는 TLS 인증서가 이 CA가 서명한 것인지 검증할 거예요.

이 값은 kubeconfig 파일(보통 ~/.kube/config)의 clusters[*].cluster.certificate-authority-data 아래를 살펴보아 얻을 수 있어요. GKE의 경우 다음 명령을 실행해 값을 얻으세요.

gcloud container clusters describe <YOUR_CLUSTER_NAME> \
    --zone=<YOUR_COMPUTE_ZONE> \
    --format="value(masterAuth.clusterCaCertificate)"

gcloud 없는 GKE에 대한 완전한 문서는 https://cloud.google.com/kubernetes-engine/docs/how-to/api-server-authentication#environments-without-gcloud 도 참고하세요.

`clusters.*.caFile` (선택)

PEM 형식의 인증 기관 번들에 대한(Backstage 프로세스가 실행되는 호스트의) 파일시스템 경로예요. Kubernetes 클라이언트는 API 서버가 제시하는 TLS 인증서가 이 CA가 서명한 것인지 검증할 거예요. config 클러스터 locator 메서드를 통해 app-config에 정의된 클러스터만 이 방식으로 구성할 수 있다는 점에 유의하세요.

`clusters.*.customResources` (선택)

클러스터에 속한 엔티티의 Kubernetes 리소스를 반환할 때 찾을 사용자 지정 리소스를 구성해요. customResources와 같은 사양이에요.

`headlamp`

대시보드로 headlamp를 사용할 때 두 가지 구성 옵션이 있어요.

외부 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 'default'

`gke`

이 클러스터 locator는 GKE에서 실행되는 Kubernetes 클러스터와 함께 작동하도록 설계됐어요. Google Cloud 프로젝트 안에서 실행되는 클러스터에 요청하도록 Kubernetes 백엔드 플러그인을 구성할 거예요.

이 클러스터 locator 메서드는 google 인증 메커니즘을 사용할 거예요.

사용할 Google Cloud 서비스 계정은 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'

이것은 europe-west1 리전의 gke-clusters 프로젝트에 있는 모든 GKE 클러스터에 연결하도록 Kubernetes 플러그인을 구성할 거예요.

GKE 클러스터 locator는 exposeDashboard 옵션을 활성화하면 dashboardApp과 dashboardParameters 옵션의 값을 자동으로 제공할 수 있다는 점에 유의하세요.

`projectId`

Kubernetes 클러스터를 찾을 Google Cloud 프로젝트예요.

`region` (선택)

Kubernetes 클러스터를 찾을 Google Cloud 리전이에요. 기본값은 모든 리전이에요.

`authProvider` (선택)

클러스터를 발견하고 리소스에 대한 정보를 수집하는 인증 방법을 설정해요.

기본값은 로그인한 사용자의 Google OAuth 자격 증명을 활용하는 google이에요.

Application Default Credentials(https://cloud.google.com/docs/authentication/application-default-credentials)를 활용하려면 googleServiceAccount로 설정하세요. 서비스 계정 JSON 키를 사용하려면(권장하지 않음) Backstage 백엔드에서 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 서비스 계정 키 파일의 경로로 설정하세요.

`skipTLSVerify` (선택)

Kubernetes 클라이언트가 API 서버가 제시하는 TLS 인증서를 검증할지 결정해요. 기본값은 false예요.

`skipMetricsLookup` (선택)

Kubernetes 클라이언트가 API 서버가 반환한 파드에 대한 리소스 지표 CPU/메모리를 조회할지 결정해요. 기본값은 false예요.

`exposeDashboard` (선택)

Kubernetes 플러그인에서 GKE 대시보드를 노출하기 위해 dashboardApp과 dashboardParameters를 자동으로 구성할지 결정해요.

기본값은 false예요.

`matchingResourceLabels` (선택)

일치하는 리소스 라벨이 없는 클러스터를 걸러내는 데 사용되는 키-값 라벨 배열이에요.

`localKubectlProxy`

이 클러스터 locator 메서드는 기본 포트(8001)를 사용하는 로컬에서 실행되는 kubectl proxy 프로세스를 가정해요.

참고: 이 클러스터 locator 메서드는 로컬 개발 전용이며 프로덕션에서 사용해서는 안 돼요.

사용자 지정 `KubernetesClustersSupplier`

구성 기반 클러스터 locator가 사용 사례에 맞지 않으면 사용자 지정 KubernetesClustersSupplier를 구현하는 것도 가능해요.

`proxy` (선택)

Kubernetes API 프록시(/api/kubernetes/proxy)에 대한 옵션이에요.

`proxy.middlewareCache` (선택)

프록시는 클러스터당 하나의 http-proxy-middleware 인스턴스를 캐싱해요. 항목은 클러스터 세부 정보가 변경되거나, 구성 가능한 TTL 후에, 또는 캐시가 크기 제한에 도달하면 새로 고쳐져요.

config의 클러스터는 백엔드가 시작할 때 로드돼요. app-config를 변경해도 그 값이 새로 고쳐지려면 여전히 재시작이 필요해요. 카탈로그와 기타 동적 클러스터 소스는 클러스터 공급자가 새 세부 정보를 반환하면 재시작 없이 클러스터 세부 정보 변경을 받아들일 수 있어요.

kubernetes:
  proxy:
    middlewareCache:
      maxSize: 100
      ttl:
        milliseconds: 60000

maxSize — 캐시된 미들웨어 인스턴스의 최대 수(기본 100).
ttl.milliseconds — 캐시 항목의 수명(밀리초)(기본 60000).

`customResources` (선택)

엔티티의 Kubernetes 리소스를 반환할 때 기본적으로 찾을 사용자 지정 리소스를 구성해요.

참고:

선택적 kubernetes.customResources 속성은 클러스터 수준의 customResources로 덮어써져요.

기본값은 빈 배열이에요. 예시:

---
kubernetes:
  customResources:
    - group: 'argoproj.io'
      apiVersion: 'v1alpha1'
      plural: 'rollouts'

`customResources.*.group`

사용자 지정 리소스의 그룹이에요.

`customResources.*.apiVersion`

사용자 지정 리소스의 apiVersion이에요.

`customResources.*.plural`

사용자 지정 리소스를 나타내는 복수형이에요.

`apiVersionOverrides` (선택)

해당 객체에 대한 요청을 만드는 데 사용되는 API 버전의 오버라이드예요. 레거시 Kubernetes 버전을 사용한다면 이 구성으로 기본 API 버전을 클러스터가 지원하는 버전으로 덮어쓸 수 있어요.

예시:

---
kubernetes:
  apiVersionOverrides:
    cronjobs: 'v1beta1'

클러스터가 지원하는 API 버전에 대한 자세한 내용은 Kubernetes 버전에 대한 Kubernetes API 문서(예: v1.22용 API Groups)를 참고하세요.

`objectTypes` (선택)

클러스터에서 가져오는 Kubernetes 객체 유형의 오버라이드예요. 기본 객체 유형은 다음과 같아요.

pods
services
configmaps
limitranges
resourcequotas
deployments
replicasets
horizontalpodautoscalers
jobs
cronjobs
ingresses
statefulsets
daemonsets

특정 유형만 원한다면 이 구성으로 기본 객체 유형을 덮어쓸 수 있어요. 하지만 현재 가져올 수 있는 추가 객체 유형은 secrets뿐이에요.

예시:

---
kubernetes:
  objectTypes:
    - configmaps
    - deployments
    - limitranges
    - pods
    - services
    - statefulsets
    - secrets

역할 기반 액세스 제어(Role Based Access Control)

현재 필요한 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 컴포넌트를 엔티티의 일부로 표시하기

Kubernetes 컴포넌트를 엔티티의 일부로 표시하는 방법은 두 가지가 있어요. 라벨 셀렉터가 주석/서비스 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.io/kubernetes-id': <BACKSTAGE_ENTITY_NAME>

라벨 셀렉터 쿼리 주석

Backstage가 객체를 조회할 때 사용할 나만의 사용자 지정 라벨 셀렉터 쿼리를 작성할 수 있어요(kubectl --selector="your query here"와 비슷). 자세한 내용은 labels and selectors Kubernetes 문서를 참고하세요.

'backstage.io/kubernetes-label-selector': 'app=my-app,component=front-end'

클러스터 선택 주석

이것은 singleTenant serviceLocatorMethod에만 적용돼요.

이제 모든 정의된 Kubernetes 클러스터 중에서 엔티티가 속한 single Kubernetes 클러스터를 선택할 수 있어요. 적용하려면 다음 주석을 사용하세요.

SingleTenant 클러스터:

'backstage.io/kubernetes-cluster': dice-cluster

위 예시에서 우리는 엔티티 catalog-info.yaml 파일의 "backstage.io/kubernetes-cluster" 주석을 구성해 현재 컴포넌트가 "dice-cluster"라는 단일 클러스터에서 실행되고 있음을 지정했어요. 따라서 이 클러스터는 app-config.yaml의 Kubernetes 클러스터 구성(자세한 내용은 Configuring Kubernetes clusters 참조) 아래에 지정되어 있어야 해요.

주석을 지정하지 않으면 기본적으로 Backstage는 정의된 모든 Kubernetes 클러스터에서 가져와요.

Kubernetes 통합 구성하기

본문

Kubernetes 클러스터 구성하기

frontend (선택)

podDelete (선택)

enabled

국제화(Internationalization)

serviceLocatorMethod

clusterLocatorContinueOnError (선택)

clusterLocatorMethods

catalog

config

clusters

clusters.*.url

clusters.*.name

clusters.*.title

clusters.*.authProvider

clusters.*.skipTLSVerify

clusters.*.skipMetricsLookup

clusters.*.serviceAccountToken (선택)

clusters.*.oidcTokenProvider (선택)

clusters.*.dashboardUrl (선택)

clusters.*.dashboardApp (선택)

clusters.*.dashboardParameters (선택)

GKE에 필요한 매개변수

clusters.*.caData (선택)

clusters.*.caFile (선택)

clusters.*.customResources (선택)

headlamp

gke

projectId

region (선택)

authProvider (선택)

skipTLSVerify (선택)

skipMetricsLookup (선택)

exposeDashboard (선택)

matchingResourceLabels (선택)

localKubectlProxy

사용자 지정 KubernetesClustersSupplier

proxy (선택)

proxy.middlewareCache (선택)

customResources (선택)

customResources.*.group

customResources.*.apiVersion

customResources.*.plural

apiVersionOverrides (선택)

objectTypes (선택)

역할 기반 액세스 제어(Role Based Access Control)

Kubernetes 컴포넌트를 엔티티의 일부로 표시하기

공통 backstage.io/kubernetes-id 라벨

엔티티 주석 추가하기

네임스페이스 주석 추가하기

Kubernetes 컴포넌트에 라벨 지정하기

라벨 셀렉터 쿼리 주석

클러스터 선택 주석

더 알아보기 (Learn more)

`frontend` (선택)

`podDelete` (선택)

`enabled`

`serviceLocatorMethod`

`clusterLocatorContinueOnError` (선택)

`clusterLocatorMethods`

`catalog`

`config`

`clusters`

`clusters.*.url`

`clusters.*.name`

`clusters.*.title`

`clusters.*.authProvider`

`clusters.*.skipTLSVerify`

`clusters.*.skipMetricsLookup`

`clusters.*.serviceAccountToken` (선택)

`clusters.*.oidcTokenProvider` (선택)

`clusters.*.dashboardUrl` (선택)

`clusters.*.dashboardApp` (선택)

`clusters.*.dashboardParameters` (선택)

`clusters.*.caData` (선택)

`clusters.*.caFile` (선택)

`clusters.*.customResources` (선택)

`headlamp`

`gke`

`projectId`

`region` (선택)

`authProvider` (선택)

`skipTLSVerify` (선택)

`skipMetricsLookup` (선택)

`exposeDashboard` (선택)

`matchingResourceLabels` (선택)

`localKubectlProxy`

사용자 지정 `KubernetesClustersSupplier`

`proxy` (선택)

`proxy.middlewareCache` (선택)

`customResources` (선택)

`customResources.*.group`

`customResources.*.apiVersion`

`customResources.*.plural`

`apiVersionOverrides` (선택)

`objectTypes` (선택)

공통 `backstage.io/kubernetes-id` 라벨