Writing a Software Template and TechDocs

한국어 원문으로 표시합니다.

목표

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

왜 중요한가

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

단계

/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.
같은 파일에 spec.parameters 를 추가하세요 — 배열의 첫 항목에 title(아무 값), required 는 [name, owner], properties.name 은 type: string 에 pattern: '^[a-z0-9-]+$' 와 title, properties.owner 는 type: string 에 title.
같은 파일에 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).
같은 파일에 spec.output 을 추가하세요 — links 첫 항목의 title 은 Repository, url 은 publish 스텝의 remoteUrl 출력 참조, entityRef 는 register 스텝의 entityRef 출력 참조.
/root/cba-template/mkdocs.yml 을 작성하세요 — site_name 아무 값, nav 첫 항목은 Home: index.md, plugins 첫 항목은 techdocs-core. 그리고 /root/cba-template/docs/index.md 에 # 로 시작하는 제목 한 줄과 설명 문단을 쓰세요.
/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 값 치환 표현식.
템플릿이 만들어 낼 결과를 클러스터에 올리세요. 네임스페이스 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 에 고정 문자열을 쓰는 것. 템플릿이 만들어 낼 파일이므로 치환 표현식이어야 합니다.

Template 매니페스트 뼈대

/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.

Template 은 카탈로그 엔티티와 apiVersion 이 다릅니다. 스캐폴더 전용 그룹을 쓰고, 소유자는 다른 엔티티와 같은 참조 형식입니다.

parameters — 사용자 폼

같은 파일에 spec.parameters 를 추가하세요 — 배열의 첫 항목에 title(아무 값), required 는 [name, owner], properties.name 은 type: string 에 pattern: '^[a-z0-9-]+$' 와 title, properties.owner 는 type: string 에 title.

parameters 는 페이지들의 배열이고 각 페이지가 JSON Schema 입니다. 필수 항목 목록과 속성 정의가 어디에 들어가는지 확인하세요.

steps — 액션의 조합

같은 파일에 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).

각 스텝은 id, name, action, input 을 갖습니다. 뼈대 가져오기, 저장소 만들기, 카탈로그 등록이 각각 어떤 액션 이름인지 떠올려 보세요.

output — 끝나고 보여 줄 것

같은 파일에 spec.output 을 추가하세요 — links 첫 항목의 title 은 Repository, url 은 publish 스텝의 remoteUrl 출력 참조, entityRef 는 register 스텝의 entityRef 출력 참조.

앞 스텝의 결과는 스텝 id 를 통해 참조합니다. 저장소 주소와 등록된 엔티티 참조가 각각 어느 스텝의 출력인지 생각하세요.

mkdocs 설정과 문서

/root/cba-template/mkdocs.yml 을 작성하세요 — site_name 아무 값, nav 첫 항목은 Home: index.md, plugins 첫 항목은 techdocs-core. 그리고 /root/cba-template/docs/index.md 에 # 로 시작하는 제목 한 줄과 설명 문단을 쓰세요.

TechDocs 는 mkdocs 를 씁니다. 설정 파일에는 사이트 이름과 목차, 그리고 TechDocs 용 플러그인이 필요합니다.

스켈레톤의 catalog-info.yaml

/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 값 치환 표현식.

템플릿이 만들어 낼 파일이므로 이름 자리에는 값이 아니라 치환 표현식이 들어갑니다. 문서 위치를 가리키는 애너테이션도 잊지 마세요.

생성 결과를 클러스터에 적용

템플릿이 만들어 낼 결과를 클러스터에 올리세요. 네임스페이스 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 단계 스켈레톤의 애너테이션 값과 정확히 같아야 합니다)를 만드세요.

템플릿이 만들어 낼 워크로드를 직접 올려 봅니다. 스켈레톤에 적은 문서 참조 값과 클러스터에 넣는 값이 같아야 합니다.