Backstage와 쿠버네티스의 만남: Kubernetes 백엔드 플러그인 완벽 가이드

안녕하세요! 오늘은 Backstage의 강력한 기능 중 하나인 Kubernetes 통합을 가능하게 만드는 핵심 구성 요소, 바로 Kubernetes 백엔드 플러그인에 대해 아주 상세히 알아보겠습니다. 🚀

클라우드 네이티브 환경에서 개발자 포털(Backstage)을 운영할 때, 자신이 만든 서비스가 쿠버네티스 클러스터 위에서 어떻게 돌아가고 있는지(Pod 상태, 배포 현황 등)를 한눈에 보는 것은 매우 중요합니다. 이 마법 같은 연결을 담당하는 주인공을 지금 바로 만나보시죠! 💡

---

🏗️ 정답은 바로: @backstage/plugin-kubernetes-backend ☸️

Backstage 포털에 쿠버네티스 리소스 데이터를 통합하고 API를 제공하는 핵심 백엔드 플러그인은 바로 **@backstage/plugin-kubernetes-backend**입니다.

이 플러그인은 각 서비스(Entity)와 관련된 실제 쿠버네티스 리소스(Pods, Deployments, Services, Ingress 등)를 조회하여 프론트엔드에 전달하는 중추적인 역할을 수행합니다.

---

🌟 Kubernetes 백엔드 플러그인의 핵심 역할

단순히 데이터를 가져오는 것을 넘어, 이 플러그인은 다음과 같은 복잡한 작업들을 수행합니다.

1. 다중 클러스터 데이터 수집 (Multi-cluster Support) 🌐

대부분의 기업은 개발, 스테이징, 운영 등 여러 개의 쿠버네티스 클러스터를 운용합니다. 이 플러그인은 설정된 모든 클러스터에 접속하여 관련 데이터를 긁어모으는 역할을 합니다.

2. 엔티티 매핑 (Service-to-Cluster Mapping) 🔗

가장 중요한 기능입니다! Backstage 카탈로그에 등록된 특정 '서비스'가 쿠버네티스 상의 어떤 '리소스'인지 매칭합니다. 보통 YAML 파일에 설정된 backstage.io/kubernetes-id 레이블을 기준으로 데이터를 필터링합니다.

3. 인증 및 보안 (Authentication) 🔐

각 클러스터에 안전하게 접근하기 위해 Service Account 토큰, 클러스터 인증서, 혹은 클라우드 제공자(AWS EKS, GCP GKE 등)의 인증 방식을 처리합니다.

---

🛠️ 어떻게 설치하고 설정하나요?

Backstage 모노레포 구조에서 이 플러그인을 활성화하는 방법은 다음과 같습니다.

1단계: 패키지 설치 📦

터미널에서 백엔드 패키지에 라이브러리를 추가합니다.

Bash

yarn workspace backend add @backstage/plugin-kubernetes-backend

2단계: 백엔드 코드 등록 ⚙️

최신 Backstage 시스템(New Backend System) 기준, packages/backend/src/index.ts에 아래 내용을 추가합니다.

TypeScript

backend.add(import('@backstage/plugin-kubernetes-backend/alpha'));

3단계: app-config.yaml 설정 📝

가장 중요한 부분입니다. 어떤 클러스터에 어떻게 접속할지 명시해야 합니다.

YAML

kubernetes:
  serviceLocatorMethod:
    type: 'multiTenant'
  clusterLocatorMethods:
    - type: 'config'
      clusters:
        - url: https://<apiserver-url>
          name: my-cluster
          authProvider: 'serviceAccount'
          skipTLSVerify: false
          # ... 기타 인증 설정

---

🔍 프론트엔드와의 찰떡궁합: plugin-kubernetes

백엔드 플러그인이 데이터를 가져온다면, 사용자가 보는 화려한 대시보드는 @backstage/plugin-kubernetes(프론트엔드 플러그인)가 담당합니다. 🎨

• 백엔드: 클러스터 API와 통신하여 JSON 데이터를 가져옴.
• 프론트엔드: 가져온 데이터를 바탕으로 Pod의 상태(Running, Error 등)를 시각화하고 로그를 보여줌.

---

💡 실전 팁: 내 서비스가 왜 안 보일까요? 🤔

만약 플러그인을 설치했는데도 데이터가 보이지 않는다면 다음 두 가지만 확인하세요!

1. 레이블 확인: 서비스의 쿠버네티스 리소스(Deployment 등)에 backstage.io/kubernetes-id: <내-앱-ID> 레이블이 붙어있나요?
2. 어노테이션 확인: Backstage catalog-info.yaml 파일에 backstage.io/kubernetes-id: <내-앱-ID> 어노테이션이 추가되어 있나요?

이 두 ID가 일치해야 백엔드 플러그인이 "아! 이 Pod가 이 서비스꺼구나!"라고 인지합니다. ✨

---

🏁 결론: 인프라 가시성의 완성

@backstage/plugin-kubernetes-backend는 파편화된 인프라 정보를 개발자 중심의 뷰로 통합하는 핵심 도구입니다. 이 플러그인을 통해 개발자들은 인프라 부서에 문의하지 않고도 자신의 서비스 상태를 스스로 점검할 수 있는 Self-service 환경을 구축할 수 있습니다! 🚀

---