Backstage 실전: Service Catalog와 Software Templates로 골든 패스를 만드는 방법

Backstage 실전: Service Catalog와 Software Templates로 골든 패스를 만드는 방법

플랫폼 팀이 좋은 규칙을 만들어도 개발자가 찾고 쓰기 어렵다면 결국 각자 복사해 쓰게 된다.

중급 플랫폼에서는 Backstage를 포털로만 보지 말고, 서비스 등록과 템플릿 배포를 묶는 운영 체계로 설계해야 한다.

왜 지금 이 주제가 중요한가

• 서비스 수가 늘수록 소유권, 문서, 배포 경로를 추적하기 어려워진다.
• 골든 패스가 문서로만 있으면 새 프로젝트는 다시 제각각 시작된다.
• 서비스 카탈로그와 템플릿이 연결되어야 플랫폼 표준이 실제 코드로 이어진다.

핵심 설계 포인트

• Service Catalog는 메타데이터 저장소가 아니라 ownership과 운영 문맥의 출발점으로 본다.
• Software Templates는 새 서비스 생성뿐 아니라 운영 기준을 코드로 넣는 장치다.
• 플랫폼 표준은 너무 많기보다 자주 쓰는 기본값 2~3개를 먼저 제공한다.
• 카탈로그와 대시보드, 문서, 온콜 정보를 연결한다.

예시 구성

catalog-info.yaml -> owner, lifecycle, system, links
template -> repo 생성 + CI + observability 기본값 + runbook 링크
portal -> 서비스 목록, 문서, 온콜 연결

적용 순서(실무 플로우)

큰 설계보다도, 작게 도입하고 관측하면서 범위를 넓히는 순서가 운영 성공률을 결정한다.

1. 현재 서비스 메타데이터가 어디에 흩어져 있는지 파악한다.
2. 공통 템플릿으로 만들 가치가 큰 서비스 유형을 고른다.
3. 카탈로그 메타데이터와 템플릿 입력값을 정리한다.
4. 한 팀 파일럿으로 템플릿 생성부터 배포까지 검증한다.
5. 정기적으로 템플릿 drift를 정리한다.

운영 체크포인트

• 카탈로그 메타데이터 필수 항목을 최소화해 온보딩 마찰을 줄인다.
• 템플릿 버전과 변경 이력을 운영 문서처럼 관리한다.
• 포털이 오래된 정보를 보여주지 않도록 소스 오브 트루스를 정한다.

운영 지표/알람 추천

• 배포 성공률과 drift 발생 횟수
• 변경 lead time과 rollback 시간
• 플랫폼 셀프서비스 요청 처리 시간
• 구성 차이로 인한 장애 재발 비율

빠른 점검 명령/쿼리

# GitOps 저장소와 실제 클러스터/계정 설정 차이를 diff
# 플랫폼 요청이 수동 승인에 막히는 단계 확인
# 구성 템플릿이 팀마다 갈라진 지점 조사

구조화 로그 필드 추천

• requestId/traceId/eventId처럼 흐름을 잇는 키를 남긴다.
• 버전, 테넌트, 리전, 대상 리소스 같은 핵심 차원을 구조화한다.
• 실패 이유(reasonCode)와 재시도 횟수(retryAttempt)를 분리한다.
• 민감정보는 마스킹하고, payload는 원본 대신 요약 정보만 남긴다.

{
  "level": "INFO",
  "message": "request completed",
  "requestId": "req_123",
  "traceId": "4bf92f...",
  "status": 200,
  "latencyMs": 123,
  "reasonCode": null
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대한 성공 경로와 상태 전이가 유지되는지
2) 실패: 오류가 예측 가능한 상태/코드로 떨어지는지
3) 동시성/재시도: 중복 요청·이벤트·배포 상황에서도 깨지지 않는지

추가(가능하면):
- 장애 복구: 프로세스 재시작, 네트워크 지연, 설정 rollback 이후에도 회복되는지
- 운영 검증: 대시보드와 알람만으로 원인을 좁힐 수 있는지

트레이드오프/대안

• 운영 복잡도를 줄이면 유연성이 줄고, 유연성을 높이면 운영 비용이 올라간다.
• 기본값은 정답이 아니라 출발점이다. 실제 트래픽과 장애 패턴을 보고 조정해야 한다.
• 문서와 자동화가 없으면 좋은 설계도 팀이 늘어나는 순간 무너진다.
• 관측 없이 최적화하면 체감 개선과 회귀를 구분하기 어렵다.

성공 기준(SLO) 예시

• 핵심 경로 에러율: 0.1% 이하
• 핵심 요청/이벤트 p95 지연: 서비스 목표 내 유지
• 중복 실행/유실/권한 우회 같은 치명적 부작용: 0건
• 장애 감지 후 임시 조치까지 걸리는 시간: 10분 이내

자주 터지는 실수/트러블슈팅

1. Backstage를 링크 모음집으로만 쓴다.
2. 템플릿이 너무 많고 차이가 불분명하다.
3. 서비스 소유자가 비어 있는 카탈로그를 허용한다.

바로 적용 템플릿

Backstage 도입 템플릿:
필수 catalog 메타데이터
골든 패스 템플릿 종류
포털 연동 대상(docs/oncall/dashboard)
템플릿 drift 관리 절차

검증 방법

• 새 서비스 하나를 템플릿으로 만들고 운영 준비 시간이 실제로 줄었는지 확인한다.
• 카탈로그만 보고 서비스 owner와 운영 문서를 찾을 수 있는지 검증한다.

장애 대응 Runbook(초안)

• 현상: 어디서 무엇이 깨졌는지 한 문장으로 적는다.
• 범위: 언제부터, 누구에게, 어느 경로에서 발생했는지 정리한다.
• 증거: 로그 3줄, 지표 1개, 최근 배포/설정 변경 1개를 먼저 모은다.
• 임시 조치: 차단, rollback, 스위치 전환, 재시도 제한 중 무엇을 할지 정한다.
• 근본 원인: 계약, 설정, 타임아웃, 리소스, 운영 절차 중 어느 축이 깨졌는지 좁힌다.
• 재발 방지: 테스트, 알람, 기본값, 문서를 함께 바꾼다.

리뷰 체크리스트

1. 상태 전이와 실패 시나리오가 문서와 코드에서 같은 의미로 정의돼 있다.
2. 타임아웃, 재시도, 권한, 캐시 같은 보호 장치가 서로 충돌하지 않는다.
3. 운영 중 재현 가능한 로그/지표/상관관계 키가 있다.
4. 롤백 또는 비상 스위치가 준비돼 있다.
5. 최소 1개 이상의 실패/동시성/복구 테스트가 자동화돼 있다.
6. 공식 문서 링크와 팀 의사결정 근거가 남아 있다.

도입 전 질문 체크리스트

• 이 주제의 기본값을 누가 바꿀 수 있고, 변경 기록은 어디에 남는가?
• 배포 직후 문제가 생기면 10분 안에 되돌릴 수 있는가?
• 새로운 팀원이 문서만 보고도 같은 규칙을 재현할 수 있는가?
• 장애가 났을 때 고객 영향 범위를 바로 설명할 수 있는가?

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 어떤 장애/비용을 줄이려는가
2) 범위: 어느 API/토픽/클러스터/브라우저/테넌트에 적용하는가
3) 규칙: 버전, TTL, timeout, retry, 소유 팀, 기본값
4) 예외: 차단 조건과 에러 코드, 수동 개입 조건
5) 운영: 대시보드, 알람, 배포/실험 주기
6) 장애 대응: 임시 조치, rollback, 후속 공지 절차
7) 변경 이력: 언제 누가 왜 값을 바꿨는가

FAQ(자주 묻는 질문)

Q. 처음부터 완벽하게 도입해야 하나요?
A. 아니다. 핵심 경로 1개부터 시작해서 지표와 장애 패턴을 보며 넓히는 편이 안전하다.

Q. "Backstage 실전: Service Catalog와 Software Templates로 골든 패스를 만드는 방법"를 넣었는데도 문제가 남습니다. 어디부터 봐야 하나요?
A. 최근 변경점과 상관관계 키가 있는 로그를 먼저 보고, 기본값과 경계 조건이 실제 트래픽에 맞는지 확인한다.

Q. 팀마다 구현이 달라집니다. 무엇을 가장 먼저 고정해야 하나요?
A. 상태 전이, 예외 처리, 기본값, rollback 기준 네 가지를 먼저 문서화해야 한다.

참고/출처

• Backstage Documentation
• Backstage Software Templates