Backstage 확장하기: 커스텀 애노테이션 정의와 예약어 충돌 방지 전략

안녕하세요! 오늘은 Backstage의 유연성을 극대화해주는 애노테이션(Annotations), 그중에서도 관리를 위해 필수적인 네임스페이싱(Namespacing) 규칙에 대해 깊이 있게 다뤄보겠습니다. 🚀

Backstage를 운영하다 보면 기본 기능 외에 우리 조직만의 특별한 데이터를 추가하고 싶을 때가 많죠. 이때 사용하는 것이 애노테이션입니다. 하지만 아무 이름이나 사용하면 시스템 내부 충돌이 발생할 수 있습니다. 오늘은 절대로 사용해서는 안 되는 '예약된 접두사'와 올바른 네임스페이싱 전략을 완벽히 정리해 드립니다! 💡

---

🏗️ Backstage 애노테이션이란?

Backstage의 catalog-info.yaml 파일에서 metadata.annotations 섹션은 엔티티에 대한 비정형 메타데이터를 저장하는 곳입니다.

플러그인들은 이 애노테이션을 읽어서 특정 기능을 활성화하거나 데이터를 가져옵니다. 예를 들어, "이 컴포넌트의 GitHub 레포지토리는 어디인가?" 또는 "이 서비스의 ArgoCD 어플리케이션 이름은 무엇인가?"와 같은 정보를 담습니다. 🏷️

---

🚫 핵심 질문: 코어 컴포넌트를 위해 예약된 접두사는?

결론부터 말씀드리면, Backstage의 코어 기능과 공식 플러그인을 위해 예약된 접두사는 바로 backstage.io/입니다.

왜 이 접두사를 피해야 하나요?

• 시스템 충돌 방지: Backstage 엔진이 내부적으로 사용하는 로직과 여러분의 커스텀 설정이 충돌하는 것을 막기 위함입니다.
• 미래의 호환성: 지금은 사용되지 않더라도, 나중에 Backstage 업데이트를 통해 backstage.io/new-feature라는 공식 애노테이션이 추가될 수 있습니다. 이때 여러분이 같은 이름을 쓰고 있다면 시스템이 꼬일 수 있습니다. 꼬인 실타래를 푸는 건 정말 힘들죠! 🧶

---

🌟 올바른 네임스페이싱 전략 (Custom Annotations)

조직 내에서 커스텀 애노테이션을 정의할 때는 다음과 같은 규칙을 권장합니다.

1. 조직만의 접두사 사용하기 🏢

가장 좋은 방법은 회사의 도메인을 접두사로 사용하는 것입니다.

• 나쁜 예: my-custom-plugin: value (네임스페이스 없음)
• 좋은 예: acme.com/project-id: "PRJ-123"

2. 하위 도메인 활용하기 📂

특정 팀이나 특정 도구를 위한 것이라면 더 세분화하세요.

• engineering.acme.com/cost-center: "DEPT-404"
• security.acme.com/scan-id: "SCAN-99"

---

🛠️ 실무 예시: catalog-info.yaml 구성하기

실제로 어떻게 적용되는지 코드로 확인해 봅시다.

YAML

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: billing-service
  annotations:
    # ✅ 공식/코어 애노테이션 (backstage.io 접두사 사용)
    backstage.io/managed-by-location: url:https://github.com/...
    backstage.io/techdocs-ref: dir:.

    # ✅ 외부 공식 플러그인 애노테이션 (각 서비스 도메인 사용)
    github.com/project-slug: backstage/backstage
    argocd.io/app-name: billing-app

    # ✅ 우리 조직만의 커스텀 애노테이션 (우리 도메인 사용)
    company.com/team-slack-channel: "#team-billing"
    company.com/on-call-rotation: "https://pagerduty.com/..."
spec:
  type: service
  owner: billing-team
  lifecycle: production

위 예시처럼 backstage.io/는 시스템이 관리하는 영역에 양보하고, 우리만의 영역을 구축하는 것이 유지보수의 핵심입니다. 🛠️

---

🧐 자주 묻는 질문 (FAQ)

Q: 접두사 없이 애노테이션을 쓰면 어떻게 되나요?

A: 당장은 동작할 수 있지만, 규모가 커질수록 어떤 플러그인이 어떤 값을 쓰는지 추적하기 어려워집니다. 나중에 같은 이름의 다른 데이터가 들어오면 덮어쓰기 오류가 발생할 수 있습니다. 😱

Q: backstage.io/ 외에 또 주의할 접두사가 있나요?

A: 널리 쓰이는 오픈소스 플러그인들의 접두사(예: github.com/, jenkins.io/, sentry.io/)도 해당 도구를 쓰지 않더라도 피하는 것이 관례입니다.

---

🏁 결론: 깔끔한 네임스페이싱이 건강한 카탈로그를 만듭니다!

Backstage의 소프트웨어 카탈로그는 조직의 모든 유산을 담는 보물 창고와 같습니다. backstage.io/라는 성역을 존중하면서 우리만의 체계적인 네임스페이스를 구축한다면, 수천 개의 서비스를 관리하더라도 혼란 없는 완벽한 플랫폼을 운영하실 수 있을 겁니다. 🚀

---