Backstage의 원자, 'Entity(엔터티)' 완벽 해부 - 서비스부터 팀까지 하나로!

플랫폼 엔지니어링의 세계에 오신 것을 환영합니다! 🌟 Backstage를 처음 접하면 모든 것이 '카탈로그'를 중심으로 돌아간다는 것을 알게 됩니다. 그런데 이 카탈로그를 구성하는 가장 작은 벽돌, 즉 기본 단위가 무엇인지 알고 계신가요?

오늘은 Backstage의 근간을 이루는 'Entity(엔터티)'에 대해 아주 상세히 파헤쳐 보겠습니다. 이 글을 읽고 나면 여러분의 복잡한 인프라가 어떻게 하나의 일관된 데이터 모델로 변신하는지 이해하게 될 거예요!

---

1. Entity(엔터티)란 무엇인가요? 🧱

Backstage에서 Entity는 소프트웨어 생태계 내의 모든 개별 구성 요소를 설명하는 표준화된 기본 단위입니다.

단순히 소스 코드가 들어있는 '서비스'만을 의미하는 것이 아닙니다. 여러분의 시스템을 구성하는 유기적인 모든 존재들이 엔터티가 될 수 있습니다.

• 서비스(Component): 실제 구동되는 마이크로서비스나 웹 앱
• API: 서비스가 제공하거나 소비하는 인터페이스
• 팀(Group) & 개발자(User): 누가 만들고 관리하는지에 대한 정보
• 인프라 자원(Resource): DB, S3 버킷, Kubernetes 클러스터 등

---

2. 엔터티는 어떻게 생겼나요? (YAML 구조) 📝

엔터티는 보통 catalog-info.yaml이라는 파일에 정의됩니다. 이 파일은 Kubernetes의 리소스 정의와 매우 유사한 구조를 가지고 있어 익숙하실 거예요. 모든 엔터티는 크게 세 부분으로 구성됩니다.

YAML

apiVersion: backstage.io/v1alpha1
kind: Component # 엔터티의 종류
metadata:
  name: my-awesome-service # 엔터티의 이름
  description: 우리 팀의 메인 API 서비스입니다.
  tags: ["java", "spring-boot"]
  annotations:
    backstage.io/managed-by-location: url:https://github.com/...
spec:
  type: service
  owner: team-alpha # 소유팀 (다른 엔터티와의 관계)
  lifecycle: production

1. apiVersion & kind: 이 엔터티가 무엇인지(컴포넌트인지, 그룹인지 등) 정의합니다.
2. metadata: 이름, 설명, 태그 등 검색과 식별을 위한 정보를 담습니다.
3. spec: 해당 종류(Kind)에 특화된 상세 정보와 다른 엔터티와의 관계(Relationship)를 정의합니다.

---

3. 엔터티가 강력한 이유: 관계(Relationship) 🕸️

엔터티가 단순한 "설명서"를 넘어 강력한 힘을 발휘하는 이유는 엔터티 간의 연결 고리 때문입니다.

예를 들어, Component 엔터티의 spec.owner 필드에 특정 Group 엔터티의 이름을 적는 순간, Backstage는 자동으로 이 둘을 연결합니다.

• "이 서비스는 누가 관리해?" 👉 Group 엔터티로 연결
• "이 서비스가 쓰는 DB는 뭐야?" 👉 Resource 엔터티로 연결
• "이 팀은 어떤 API를 개발했어?" 👉 역방향으로 조회 가능

이런 관계들이 모여 거대한 소프트웨어 그래프(Software Graph)를 형성하게 됩니다.

---

4. 주요 엔터티 종류(Kinds) 살펴보기 🧐

Backstage는 기본적으로 다음과 같은 핵심 Kind를 제공합니다.

Kind	설명	예시
Component	코드로 이루어진 소프트웨어 조각	서비스, 웹사이트, 라이브러리
API	서비스 간의 인터페이스 계약	REST API, GraphQL, gRPC
Resource	소프트웨어가 작동하는 데 필요한 인프라	PostgreSQL, S3, RDS
Group	조직 내의 팀 또는 부서	플랫폼 팀, 결제 파트
User	개별 개발자	홍길동, 김철수
System	연관된 엔터티들의 큰 추상화 그룹	결제 시스템, 유저 관리 시스템

---

5. 엔터티가 개발자에게 주는 이점 💡

1. 일관성: 모든 팀이 동일한 포맷으로 자신의 서비스를 설명합니다.
2. 발견 가능성(Discoverability): "누가 만들었는지 모르는 API"가 사라집니다. 카탈로그에서 엔터티 검색 한 번으로 모든 정보를 찾을 수 있습니다.
3. 자동화의 기반: 엔터티 정보를 바탕으로 배포 상태 확인, 보안 취약점 스캔 결과를 자동으로 연동할 수 있습니다. 🤖

---

🏁 마무리하며

Backstage 카탈로그의 근간인 Entity는 단순한 데이터 조각이 아니라, 조직의 복잡한 소프트웨어 지도를 그리는 좌표와 같습니다. 엔터티를 잘 정의하고 연결할수록, 개발자들은 불필요한 커뮤니케이션 대신 실제 "개발"에 더 집중할 수 있게 됩니다.

여러분의 프로젝트 루트에 지금 바로 catalog-info.yaml을 만들고 첫 번째 엔터티를 정의해 보는 건 어떨까요? 🚀

---