16장 90일 도입 roadmap과 운영 루프를 완성한다

0–30일: 발견과 catalog

개발자 journey 열 건을 관찰한다. production service와 team ownership을 연결한다. 최소 entity schema와 quality check를 만든다. tool 설치보다 baseline을 먼저 기록한다.

31–60일: 한 개 Golden Path

가장 흔한 web service 하나를 고른다. repository·CI·SBOM·dev GitOps·telemetry·runbook을 만든다. 2개 pilot team과 pairing하며 실패를 기록한다.

61–90일: adoption과 enforcement

성공률과 first deployment 시간을 공개한다. scorecard는 warning으로 시작한다. 반복되는 예외는 extension point로 제품화하고, 사용되지 않는 option은 제거한다. production guardrail만 단계적으로 enforce한다.

월간 제품 review:

사용자 outcome: lead time, task success, 인지 부하
안전 outcome: ownership, SBOM, SLO, rollback
운영 outcome: platform availability, support ticket, upgrade lag
다음 결정: 개선할 journey 하나, 폐기할 기능 하나

좋은 플랫폼은 개발자에게 존재감을 과시하지 않는다. 안전한 기본값이 자연스럽게 선택되고, 예외가 설명 가능하며, 팀이 제품 문제에 집중할 때 가치가 드러난다.

부록 A PathLab 실습 정답

기본 요청은 다음 plan을 반환한다.

Repository   services/answer-router
Catalog      owner=team-support
CI           test · SBOM · image
GitOps       environments/answer-router/dev
Observability SLO · dashboard · alerts

다음 요청은 거절돼야 한다.

{
  name: 'customer-data',
  owner: 'team-support',
  template: 'web-service',
  dataClass: 'restricted',
  publicIngress: true
}

결과에 RESTRICTED_DATA_CANNOT_BE_PUBLIC이 포함된다. frontend field를 숨기는 것만으로는 policy가 아니다. API를 직접 호출해도 같은 validation이 동작해야 한다.

부록 B Backstage template 적용 순서

lab/templates/service/template.yaml은 학습용 조직·repository placeholder를 포함한다.

1. 별도 test Backstage에서 Template Editor dry-run을 실행한다.
2. YOUR_ORG, integration credential, allowed owner를 조직 값으로 바꾼다.
3. skeleton에 catalog-info.yaml, CI, runbook을 넣는다.
4. custom action 없이 기본 action으로 먼저 검증한다.
5. 실패 cleanup과 audit event를 test한다.
6. pilot repository 두 개를 만들고 즉시 삭제·보존 정책을 확인한다.

Backstage version에 따라 action schema와 feature가 바뀔 수 있으므로 공식 문서를 기준으로 한다. UI screenshot의 버튼 위치보다 template contract를 학습한다.

부록 C Argo CD 적용과 rollback rehearsal

lab/manifests/argocd-application.yaml은 prune: false로 시작한다. 실제 적용 전 repoURL, project, namespace와 접근 정책을 바꾼다.

kubectl apply -f lab/manifests/argocd-application.yaml
argocd app get answer-router-dev
argocd app diff answer-router-dev

처음에는 자동 sync 없이 diff와 manual sync로 이해한다. auto-sync를 켠 뒤 drift를 만들고 self-heal을 관찰한다. resource 삭제는 prune policy와 finalizer, data 보존을 검토한 뒤 별도 rehearsal한다. production rollback은 이전 digest Git commit과 DB compatibility를 함께 검증한다.

부록 D 트러블슈팅

부록 E 저작권·상표·출간 확인

원고, PathLab code, SVG 도식은 이 책을 위해 독자적으로 작성했다. 표지 비주얼은 외부 reference 없이 생성하고 provenance를 기록했다. Backstage, Argo CD, Kubernetes, GitHub 등 이름은 기술을 정확히 설명하기 위해 사용한 각 권리자의 상표이며 제휴나 보증을 뜻하지 않는다.

공식 문서 screenshot을 복제하지 않고 local PathLab 화면을 직접 만들었다. 설정 예시는 placeholder domain과 조직을 사용하며 실제 credential을 포함하지 않는다. 출간 전 clean Backstage와 staging Kubernetes에서 확장 실습을 다시 실행하고 플랫폼 엔지니어의 현장 감수를 마친다.

부록 F 10일 플랫폼 제품 워크북

1일차 journey shadowing

개발자 한 명이 최근 service나 environment를 만든 과정을 다시 수행하게 한다. 화면 전환, 대기, 질문, 복사, 실패를 시간순으로 기록한다. 해결책을 즉시 제안하지 않고 문제를 “사용자·상황·막힘·영향”으로 쓴다.

2일차 catalog 최소 schema

production service 열 개를 골라 name, type, lifecycle, owner, system, repository, dependency만 채운다. 모든 cloud resource를 넣지 않는다. owner가 실제 group과 on-call로 이어지는지 검증한다.

3일차 플랫폼 API 계약

PathLab의 validateRequest처럼 portal 밖에서도 같은 규칙이 적용되도록 입력·출력·error를 정한다. name, owner, data class, public ingress의 negative test를 먼저 쓴다.

4일차 Golden Path service blueprint

개발자: parameter 입력 → review → 생성 상태 → 결과 link
플랫폼: authz → validation → repo → CI → catalog → GitOps → telemetry
지원: 실패 log → retry/cleanup → owner notification → audit

각 단계의 부분 실패와 compensation을 쓴다. “원자적으로 모두 성공”이라고 가정하지 않는다.

5일차 template acceptance test

clean organization 또는 test namespace에서 template를 실행한다. 생성 시간, 첫 CI, catalog processing, dev health, telemetry를 측정한다. 생성된 repository를 수동으로 고쳐야 통과한다면 template 실패다.

6일차 GitOps promotion rehearsal

고정 digest를 dev에 적용하고 environment repository PR로 staging에 승격한다. live cluster에서 직접 수정해 drift를 만들고 controller가 어떻게 보여 주는지 확인한다. prune은 켜지 않은 상태로 시작한다.

7일차 scorecard evidence

runbook URL 존재를 지난 90일 game day 통과로 개선하는 식으로 형식 지표를 행동 증거로 바꾼다. bronze·silver·gold가 lifecycle별로 합리적인지 pilot team과 검토한다.

8일차 adoption funnel

template_viewed
request_validated / validation_failed(reason)
task_started / step_failed(step)
repository_created / first_ci_green
first_dev_healthy / catalog_entity_processed

page view가 아니라 first_dev_healthy conversion과 걸린 시간을 본다.

9일차 support와 break-glass

platform outage, source provider 장애, 잘못된 template release를 가정한다. 승인된 manual path, 최소 권한, 사후 reconcile을 문서화한다. break-glass는 항상 열려 있는 우회 계정이 아니다.

10일차 제품 review

pilot 두 팀과 결과를 비교한다. 더 만들 기능 하나보다 제거할 friction 하나를 결정한다. 사용되지 않는 parameter를 삭제하고 반복 예외 한 개를 extension point로 만든다.

플랫폼 capability 카드

# Capability: 표준 웹서비스 생성
- 사용자와 문제:
- 지원/비지원 범위:
- 입력과 결과:
- 기본값과 고정 guardrail:
- extension point:
- service owner / technical owner:
- support SLO:
- adoption·outcome 지표:
- 비용 driver와 폐기 정책:

Golden Path acceptance criteria

[ ] 새 사용자가 문서 저자 도움 없이 입력을 완료한다.
[ ] 잘못된 owner·이름·data exposure를 실행 전에 거절한다.
[ ] 30분 안에 첫 dev health가 보인다.
[ ] first CI가 test·SBOM·artifact를 만든다.
[ ] catalog에 owner·repository·runbook이 연결된다.
[ ] GitOps controller가 desired digest를 표시한다.
[ ] trace·metric·log의 최소 signal이 보인다.
[ ] 부분 실패가 단계와 복구 행동을 설명한다.

플랫폼 RFC 골격

# RFC-___: Golden Path 변경
- 사용자 문제와 evidence:
- 현재 journey baseline:
- 제안과 하지 않을 것:
- security·data·cost 영향:
- 기존 service migration:
- pilot과 success metric:
- rollback·deprecation과 재검토일:

완료 기준은 portal demo가 아니다. pilot 개발자가 공식 경로로 healthy dev service를 만들고, platform 팀은 실패 단계와 adoption을 설명하며, 생성된 service에는 owner·공급망 증거·관측·복구 경로가 있어야 한다.

부록 G 캡스톤 통합 시나리오: answer-router를 30분 안에 만든다

지원 팀은 고객 질문을 분류하는 answer-router service가 필요하다. 이전 방식은 repository ticket 1일, cloud 권한 2일, CI 복사와 수정 반나절이 걸렸다. 플랫폼 팀은 시간을 숨기지 않고 기준 흐름과 비교한다.

1단계 사용자가 의도를 입력한다

개발자는 service name, owner, template, data class, public ingress만 선택한다. CPU 숫자, namespace, alert 이름은 묻지 않는다. 일반적인 내부 web service의 기본값은 platform이 소유한다.

2단계 실행 전에 policy를 설명한다

answer-router는 이름 규칙과 owner directory를 통과한다. restricted data와 public ingress 조합이라면 repository를 일부 만든 뒤 실패하지 않고 입력 단계에서 거절한다. 오류는 허용되는 대안과 review 경로를 알려 준다.

3단계 task가 단계별 결과를 남긴다

repository created → branch policy requested
catalog registered → owner=team-support
CI first run → tests, SBOM, artifact digest
GitOps PR → dev environment
telemetry → health, RED metrics, trace

catalog 등록이 실패해도 repository URL과 retry action이 보인다. platform operator는 task ID로 audit를 찾는다.

4단계 첫 healthy endpoint를 검증한다

생성 완료 page가 아니라 dev health, first CI green, catalog processing을 성공으로 센다. PathLab의 local plan에서는 외부 자원을 만들지 않으므로 실제 pilot에서는 별도의 clean test organization에서 이 시간을 측정한다.

5단계 scorecard와 예외를 연결한다

새 service는 dev lifecycle의 silver로 시작한다. production 승격 전 SLO, on-call, game-day runbook evidence가 필요하다. data science 실험 service에 같은 기준을 강제하지 않는다.

6단계 GitOps로 같은 artifact를 승격한다

CI가 만든 digest를 dev에 배포하고 staging PR로 옮긴다. production에서 rebuild하지 않는다. Argo CD의 diff와 health를 확인하고, 삭제가 필요한 변경은 prune과 data 보존을 별도 승인한다.

7단계 adoption feedback을 제품으로 돌린다

첫 pilot에서 owner picker에 실제 새 팀이 없었다. 팀은 free-text 우회를 추가하지 않고 directory sync latency를 고친다. template task가 image build에서 12분 걸리면 문서를 늘리는 대신 cache와 runner queue를 개선한다.

결과 기록

baseline: 첫 dev healthy까지 3.5일, 4개 ticket
pilot: 27분, ticket 0, manual edit 0
첫 CI 성공률: 8/10
실패 2건: owner sync 1, registry quota 1
결정: 두 원인 개선 뒤 3개 팀으로 확대
강제 policy: restricted/public 조합과 owner만 우선 적용

장별 산출물 지도