소프트웨어 템플릿과 TechDocs 작성

목표

Backstage 소프트웨어 템플릿의 세 층 — parameters, steps, output — 을 직접 작성하고, TechDocs 를 위한 mkdocs 설정과 스켈레톤 엔티티를 만듭니다. 마지막에는 그 템플릿이 만들어 낼 워크로드를 실제 클러스터에 올려 결과를 확인합니다.

왜 중요한가

스캐폴더의 가치는 타이핑을 줄이는 것이 아니라 검증된 경로를 기본값으로 만드는 것 입니다. 플랫폼 팀이 한 번 밟은 함정 — 특정 CRD 버전이 필요하다든가, 특정 우회 경로를 써야 한다든가 — 을 스켈레톤과 문서로 굳혀 두면 다른 사람은 다시 밟지 않습니다. 그리고 구조 자체가 중요합니다. parameters 가 JSON Schema 라서 잘못된 입력이 폼 단계에서 막히고, steps 가 재사용 가능한 액션의 조합이라 새 템플릿을 만들 때 저장소 생성과 카탈로그 등록 부분을 다시 짜지 않아도 됩니다. 또 하나 놓치기 쉬운 점 — publish:github 을 실행하는 것은 사용자의 브라우저가 아니라 Backstage 백엔드입니다. 토큰이 서버에만 있으므로, 포털을 통한 셀프서비스가 모든 개발자에게 토큰을 나눠 주는 것보다 안전합니다. Backstage 는 이 환경에 없으므로 템플릿은 파일로 작성하고 채점은 파일을 읽어서 하며, 마지막 단계만 실제 클러스터를 씁니다.

단계

1. /root/cba-template/template.yaml 을 작성하세요 — apiVersion: scaffolder.backstage.io/v1beta3, kind: Template, metadata.name: node-service, metadata.title 아무 값, metadata.tags 첫 항목 nodejs, spec.owner: group:team-platform, spec.type: service.
2. 같은 파일에 spec.parameters 를 추가하세요 — 배열의 첫 항목에 title(아무 값), required 는 [name, owner], properties.name 은 type: string 에 pattern: '^[a-z0-9-]+$' 와 title, properties.owner 는 type: string 에 title.
3. 같은 파일에 spec.steps 를 추가하세요 — 정확히 3 개이고 순서대로 id: fetch(action fetch:template, input.url: ./skeleton, input.values.name 에 name 파라미터 치환 표현식), id: publish(action publish:github), id: register(action catalog:register, input.repoContentsUrl 에 publish 스텝 출력 참조, input.catalogInfoPath: /catalog-info.yaml).
4. 같은 파일에 spec.output 을 추가하세요 — links 첫 항목의 title 은 Repository, url 은 publish 스텝의 remoteUrl 출력 참조, entityRef 는 register 스텝의 entityRef 출력 참조.
5. /root/cba-template/mkdocs.yml 을 작성하세요 — site_name 아무 값, nav 첫 항목은 Home: index.md, plugins 첫 항목은 techdocs-core. 그리고 /root/cba-template/docs/index.md 에 # 로 시작하는 제목 한 줄과 설명 문단을 쓰세요.
6. /root/cba-template/skeleton/catalog-info.yaml 을 작성하세요 — kind: Component, metadata.name 은 템플릿 값 치환 표현식(문자열 안에 values.name 이 들어가야 합니다), metadata.annotations 에 backstage.io/techdocs-ref: dir:. 와 backstage.io/kubernetes-id: node-service, spec.type: service, spec.lifecycle: experimental, spec.owner 는 owner 값 치환 표현식.
7. 템플릿이 만들어 낼 결과를 클러스터에 올리세요. 네임스페이스 cba-scaffold 를 만들고, 그 안에 Deployment node-service(라벨 backstage.io/kubernetes-id: node-service 와 app.kubernetes.io/part-of: cba-platform, 이미지 node:22-alpine, replicas 2, 파드 템플릿 라벨에도 같은 backstage.io/kubernetes-id), Service node-service(port 80, targetPort 3000), 그리고 ConfigMap node-service-techdocs(키 techdocs-ref 의 값이 6 단계 스켈레톤의 애너테이션 값과 정확히 같아야 합니다)를 만드세요.

참고

• 치환 표현식은 이중 중괄호 앞에 달러 기호가 붙는 형태입니다. 폼 입력은 parameters.<이름>, 앞 스텝 결과는 steps.<id>.output.<필드> 로 참조합니다.
• 치환 표현식은 큰따옴표로 감싸 두세요. YAML 파서가 중괄호를 흐름 매핑으로 오해할 여지를 없앱니다.
• publish:github 의 출력에는 remoteUrl 과 repoContentsUrl 이, catalog:register 의 출력에는 entityRef 가 있습니다.
• 흔한 실수 1: Template 의 apiVersion 을 backstage.io/v1alpha1 로 쓰는 것. 스캐폴더는 scaffolder.backstage.io/v1beta3 입니다.
• 흔한 실수 2: parameters 를 객체 하나로 쓰는 것. 여러 페이지를 지원하기 위해 배열입니다.
• 흔한 실수 3: 스켈레톤의 metadata.name 에 고정 문자열을 쓰는 것. 템플릿이 만들어 낼 파일이므로 치환 표현식이어야 합니다.

단계 7개

1. Template 매니페스트 뼈대
2. parameters — 사용자 폼
3. steps — 액션의 조합
4. output — 끝나고 보여 줄 것
5. mkdocs 설정과 문서
6. 스켈레톤의 catalog-info.yaml
7. 생성 결과를 클러스터에 적용