우리 회사 개발자 플랫폼 만들기

1장 플랫폼은 도구 모음이 아니라 내부 제품이다

Kubernetes, CI, Backstage를 설치했다고 플랫폼이 생기지 않는다. 사용자가 같은 ticket과 복사 작업을 반복하고 있다면 도구가 늘었을 뿐이다. 플랫폼은 반복되는 개발 경험을 제품처럼 개선한다.

제품으로 본다는 말에는 네 가지가 포함된다.

• 명확한 사용자와 가장 불편한 journey
• 검증할 outcome과 baseline
• 선택을 줄이는 기본 경로
• feedback, adoption, 폐기까지 책임지는 owner

“developer portal 구축”을 목표로 잡으면 화면 공개가 완료가 된다. “새 web service가 production readiness를 갖추는 시간을 5일에서 4시간으로 줄인다”라고 잡으면 repository·pipeline·문서·권한이 실제로 연결됐는지 보게 된다.

플랫폼 팀의 backlog도 사용자 문제로 쓴다. “plugin 추가”보다 “새 service owner가 on-call과 runbook을 한 화면에서 찾는다”가 낫다.

↑ 목차로 돌아가기

2장 사용자 조사에서 ticket 뒤의 대기와 인지 부하를 찾는다

가장 많이 들어오는 요청만 세면 쉬운 password reset이 1위가 될 수 있다. 개발자 시간을 많이 빼앗는 문제는 빈도가 낮아도 환경 생성 대기, 권한 책임 불명확, 배포 실패 복구일 수 있다.

일주일 동안 다섯 유형의 evidence를 모은다.

1. ticket 생성부터 해결까지 wait time
2. 새 service를 만드는 실제 screen recording과 handoff
3. CI template fork 수와 drift
4. 배포 실패·rollback·incident postmortem
5. 팀별 자체 script와 unofficial path

인터뷰에서는 “어떤 기능이 필요합니까?”보다 최근 행동을 묻는다.

마지막으로 service를 만든 날을 보여 주세요.
어디서 멈췄고 누구에게 물었나요?
어떤 문서를 믿지 못해 source를 직접 읽었나요?
공식 경로를 쓰지 않았다면 무엇이 더 빨랐나요?
실패했을 때 되돌아갈 기준은 어디 있었나요?

인지 부하는 선택 수와 숨은 전제로 나타난다. cluster·namespace·IAM·image registry·alert 이름을 개발자가 매번 정한다면 플랫폼이 조직 표준을 전달하지 못한 것이다.

↑ 목차로 돌아가기

3장 최소 플랫폼 제품의 경계를 정한다

처음부터 모든 언어, cloud, database, compliance를 지원하면 가장 복잡한 예외가 기본 설계를 지배한다. 첫 90일은 한 사용자와 한 journey를 고른다.

HelpDesk AI의 최소 제품:

사용자: Node.js web service를 만드는 6개 product team
입력: service name, owner, data class, public 여부
출력: repository, CI, SBOM, dev GitOps path, dashboard, runbook skeleton
성공: 30분 안에 dev health endpoint 확인
제외: production DB 자동 생성, multi-cloud, legacy VM migration

platform API와 portal UI를 구분한다. 핵심 capability가 API·template·Git repository로 제공되면 CLI, portal, automation이 같은 계약을 사용한다. UI click에만 logic이 있으면 test와 재사용이 어렵다.

↑ 목차로 돌아가기

4장 catalog는 CMDB 복제가 아니라 발견과 책임의 지도다

Backstage Software Catalog는 source control의 metadata YAML을 정본으로 service·website·library·pipeline 등 software와 owner를 추적한다. catalog가 모든 runtime 자원을 완벽히 복제하려 하면 data가 오래되고 아무도 고치지 않는다.

최소 entity:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: helpdesk-ai
  annotations:
    github.com/project-slug: withai/helpdesk-ai
spec:
  type: service
  lifecycle: production
  owner: group:team-support
  system: customer-care
  dependsOn:
    - resource:ticket-db

좋은 catalog 질문:

• 이 service의 owner와 on-call은 누구인가?
• source와 배포 artifact는 어디 있는가?
• 어떤 API와 data resource에 의존하는가?
• SLO와 runbook은 있는가?
• production에 실행 중인가?

entity 수보다 owner 없는 production service 수를 본다. 자동 discovery로 entity를 채운 뒤 팀이 유지하도록 normal Git review에 넣는다.

↑ 목차로 돌아가기

5장 ownership을 사람 이름이 아니라 팀 책임으로 만든다

개인 owner는 퇴사·이동에 약하다. team entity와 escalation을 연결한다. owner는 단지 승인자가 아니라 문서, SLO, dependency, incident를 돌볼 책임 주체다.

ownership coverage를 계산할 때 metadata 존재만 세지 않는다.

valid owner = catalog group 존재
           AND on-call 또는 support channel 연결
           AND 최근 90일 안에 team membership 동기화

공유 library와 platform resource도 owner가 필요하다. “공용”은 책임 없음의 동의어가 아니다. dependency graph에서 owner가 없는 node가 여러 production service에 연결되면 우선 정리한다.

↑ 목차로 돌아가기

6장 Golden Path는 정답 하나가 아니라 안전한 기본값이다

Golden Path는 자주 만드는 service 유형에 검증된 선택을 제공한다. 모든 예외를 막는 철길이 아니다. 기본값, guardrail, extension point를 분리한다.

PathLab은 service name, owner, template을 받고 repository·catalog·CI·GitOps·관측 다섯 단계를 계획한다. restricted data에 public ingress를 요청하면 거절한다. 이 policy는 portal JavaScript만이 아니라 server-side validateRequest에 있어 우회 경로도 같은 검사를 받는다.

↑ 목차로 돌아가기

7장 Backstage Software Template를 안전하게 작성한다

Backstage Software Templates는 skeleton code에 변수를 넣고 GitHub·GitLab 같은 위치에 publish하고 catalog에 등록할 수 있다. /create에서 parameter를 입력하고 review한 뒤 task를 실행한다.

이 책의 lab/templates/service/template.yaml은 세 단계다.

steps:
  - id: fetch
    action: fetch:template
  - id: publish
    action: publish:github
  - id: register
    action: catalog:register

template에 cloud admin credential을 직접 넣지 않는다. custom action은 최소 권한 service identity를 사용하고 입력을 schema로 제한한다. repository name을 shell command에 그대로 이어 붙이지 않는다. action ID의 naming과 expression 문법은 적용 version의 공식 문서를 확인한다.

실패 뒤 cleanup도 설계한다. repository 생성 후 catalog 등록이 실패하면 orphan을 지울지, retry 가능한 상태로 남길지 결정한다. 무조건 삭제하면 개발자가 추가한 변경을 잃을 수 있으므로 task 단계와 owner에게 명확히 보여 준다.

↑ 목차로 돌아가기

8장 template repository를 복사본 공장으로 만들지 않는다

template로 생성된 code는 그 순간 fork된다. 이후 보안 수정이 기존 수백 repository에 자동 전파되지 않는다. template에 들어갈 것과 중앙 service로 제공할 것을 나눈다.

• repository에 남을 것: 최소 build file, ownership, service contract
• 중앙에서 제공할 것: reusable workflow, base image, policy, observability collector
• versioned library: logging·auth client
• 문서 link: 변경이 잦은 운영 guide

template version을 entity annotation에 기록하면 오래된 service를 찾을 수 있다. 자동 PR로 upgrade를 제안하되 breaking change와 application code를 한 번에 섞지 않는다.

생성 직후 test:

repository exists
default branch protection requested
catalog entity processed
CI first run green
dev manifest reconciled
health and telemetry visible
runbook has owner and rollback

↑ 목차로 돌아가기

9장 CI는 artifact를 만들고 GitOps는 환경을 바꾼다

CI가 kubectl apply로 cluster를 직접 변경하면 cloud credential과 환경 상태가 pipeline 안에 섞인다. GitOps에서는 CI가 test·scan·build·attest를 마치고 immutable image digest를 환경 repository에 제안한다. deployment controller가 Git의 desired state와 cluster를 reconcile한다.

application repo → CI → image digest + attestation
                        ↓ pull request
environment repo → review → Argo CD → cluster

Argo CD automated sync는 Git과 live state 차이를 감지해 자동 동기화할 수 있다. 기본적으로 resource 삭제는 자동 prune되지 않는 안전 동작이므로, prune과 allowEmpty를 이해하지 않고 켜지 않는다. 이 책의 manifest는 prune: false, selfHeal: true로 시작한다.

↑ 목차로 돌아가기

10장 environment repository와 promotion을 설계한다

branch 하나를 dev, 다른 branch를 production으로 쓰면 merge 의미와 environment 의미가 섞일 수 있다. directory 또는 repository 전략을 조직 크기와 권한에 맞춰 고른다.

environments/
  answer-router/
    dev/
    staging/
    production/

promotion은 같은 digest를 다음 환경으로 옮긴다. production에서 다시 build하지 않는다. configuration change도 review와 audit이 필요하다. secret 값은 Git에 저장하지 않고 external secret system reference만 둔다.

rollback은 이전 Git commit으로 desired state를 되돌리는 절차와 data migration 복구를 함께 다룬다. application version만 낮춰도 DB schema가 호환되지 않으면 복구가 아니다.

↑ 목차로 돌아가기

11장 scorecard를 처벌표가 아니라 개선 안내로 쓴다

PathLab은 owner, repository, runbook, SLO, SBOM, on-call 여섯 항목으로 bronze·silver·gold를 계산한다. 실제 조직에서도 score 하나만 공개하면 팀 간 순위 경쟁이 되어 metadata를 형식적으로 채울 수 있다.

좋은 scorecard:

• 검사 항목이 자동으로 검증 가능하다.
• 왜 필요한지와 고치는 link가 있다.
• service lifecycle과 data class에 따라 기준이 다르다.
• exception owner와 expiry가 보인다.
• 점수보다 미통과 항목을 먼저 보여 준다.

예를 들어 prototype에 24시간 on-call을 강제하지 않는다. production public API는 SLO·runbook·on-call·SBOM을 요구한다. scorecard 변경은 platform RFC와 migration 기간을 거친다.

↑ 목차로 돌아가기

12장 관측 가능성과 SLO를 생성 첫날부터 넣는다

dashboard link만 자동 생성하고 telemetry가 없으면 빈 화면이다. Golden Path는 structured log, trace context, RED metric(rate, error, duration), health endpoint를 포함한다. OpenTelemetry처럼 vendor-neutral instrumentation을 쓰면 backend 변경 비용을 줄일 수 있다.

SLO template:

service: answer-router
indicator: successful HTTP requests / valid HTTP requests
objective: 99.9
window: 28d
owner: team-support
alert:
  burn_rate_fast: 14.4
  burn_rate_slow: 6

모든 service에 같은 99.99를 넣지 않는다. 사용자 약속과 dependency, 운영 역량을 반영한다. platform은 형식을 제공하고 product team이 목표를 소유한다.

↑ 목차로 돌아가기

13장 플랫폼 자체의 신뢰성과 보안을 운영한다

platform이 repository, cloud, cluster를 만들 수 있다면 강한 권한을 가진다. portal frontend가 직접 credential을 다루지 않게 하고 backend action별 service identity를 분리한다.

• template parameter server-side validation
• action allowlist와 최소 권한
• production resource는 별도 approval
• task audit와 secret redaction
• tenant·team authorization
• plugin·action dependency 공급망 검증
• platform outage 시 manual break-glass path

Backstage plugin은 편리하지만 application code와 같은 dependency다. maintainer, permission, data access, update policy를 검토한다. catalog metadata에 secret을 넣지 않는다.

↑ 목차로 돌아가기

14장 adoption을 강제 설치율 대신 행동으로 측정한다

계정 생성 수나 portal page view는 가치가 아니다. 개발자가 중요한 journey를 끝냈는지 본다.

Golden Path start → successful dev deployment conversion
median time to first healthy endpoint
template failure and abandonment stage
공식 경로 밖 repository 비율
platform support ticket per service
upgrade PR merge rate

adoption이 낮으면 교육만 추가하기 전에 공식 경로의 실패 log를 본다. parameter가 너무 많거나, template가 오래 걸리거나, 생성 뒤 첫 CI가 깨질 수 있다. shadow script는 사용자의 실제 요구를 알려 주는 research 자료다.

platform NPS 하나로 결정하지 않는다. 만족도, task success, lead time, change failure, recovery를 함께 본다.

↑ 목차로 돌아가기

15장 팀 구조와 지원 model, 비용을 설계한다

platform team이 모든 application ticket을 대신 처리하면 다시 중앙 병목이 된다. support를 세 층으로 나눈다.

1. 제품 안의 validation·error·runbook
2. office hour와 community champion
3. incident·새 capability를 위한 platform engineer 지원

capability마다 product owner, technical owner, support SLO, 비용 driver를 둔다. showback으로 team별 cluster·build·observability 비용을 보여 주되 초기에 정확하지 않은 chargeback을 강제하지 않는다.

platform backlog 우선순위:

reach × time saved × risk reduced × confidence / effort

목소리 큰 한 팀의 특수 요구보다 여러 팀이 반복하는 기다림을 먼저 줄인다. 하지만 compliance나 critical incident risk는 빈도가 낮아도 높은 우선순위를 가질 수 있다.

↑ 목차로 돌아가기

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만 우선 적용

장별 산출물 지도

↑ 목차로 돌아가기