app-config 계층과 병합 결과 예측

목표

Backstage 설정을 여러 장으로 나누어 쓰고, 그 장들이 겹쳤을 때 무엇이 남는지를 손으로 예측해 봅니다. 마지막에는 운영 설정을 쿠버네티스 오브젝트로 옮겨 실제 배포에서 값이 어디서 오는지를 확인합니다.

왜 중요한가

설정 계층은 CBA 에서 가장 자주 틀리는 자리입니다. 규칙 자체는 두 줄인데 결과가 직관과 어긋나기 때문입니다. 매핑은 키 단위로 깊게 합쳐지지만 리스트는 합쳐지지 않고 통째로 교체됩니다. 기본 파일에 카탈로그 진입점을 세 건 적어 두고 오버라이드에 한 건만 적으면, 결과는 네 건이 아니라 한 건이고 아무 경고도 나오지 않습니다. 값의 종류가 바뀔 때도 마찬가지입니다. 문자열이던 자리에 매핑이 오면 문자열은 사라집니다. 그리고 자격증명은 어느 파일에도 값으로 적으면 안 됩니다. 설정 파일은 저장소에 커밋되고 이미지에 구워지기 때문입니다. Backstage 자체는 이 환경에 없으므로 채점은 파일과 클러스터 오브젝트를 읽어서 합니다.

단계

1. /root/cba-config/app-config.yaml 에 기본 설정을 쓰세요 — app.title 아무 값, app.baseUrl: http://localhost:3000, organization.name 아무 값, backend.baseUrl: http://localhost:7007, backend.listen.port: 7007, backend.cors.origin: http://localhost:3000, backend.database.client: better-sqlite3, backend.database.connection: /tmp/portal.sqlite.
2. 같은 파일에 통합과 프록시를 이어 쓰세요 — integrations.github 첫 항목의 host: github.com 과 token (GITHUB 이 들어간 환경변수 치환 형식), proxy.endpoints 아래 /argocd/api 키에 target (https 로 시작하는 주소), changeOrigin: true, headers.Cookie (환경변수 치환 형식).
3. 같은 파일에 카탈로그 설정을 이어 쓰세요 — catalog.import.entityFilename: catalog-info.yaml, catalog.rules 첫 항목의 allow 에 Component, API, Resource, System, Domain, Group, User, Location, Template 아홉 종류, catalog.locations 두 건(첫째는 type: file 이고 target 이 entities.yaml 로 끝남, 둘째는 type: url 이고 target 이 github.com 주소), catalog.providers.github.labhubOrg 에 organization: labhub, catalogPath: /catalog-info.yaml, schedule.frequency.minutes: 30, schedule.timeout.minutes: 3.
4. /root/cba-config/app-config.local.yaml 에 오버라이드를 쓰세요 — app.baseUrl: http://portal.labhub.test, backend.baseUrl: http://portal.labhub.test:7007, backend.database.client: pg, backend.database.connection 아래 host·port·user·database 를 전부 환경변수 치환 형식으로, catalog.locations 는 type: url 한 건만. backend.listen.port 는 적지 마세요.
5. /root/cba-config/merged.yaml 에 1~3 단계의 파일 위에 4 단계 파일을 겹쳤을 때 남는 값을 그대로 쓰세요. 매핑은 깊게 합쳐지고 리스트는 통째로 교체됩니다.
6. /root/cba-config/app-config.production.yaml 에 운영 설정을 쓰세요 — app.baseUrl 과 backend.baseUrl 둘 다 https://portal.labhub.io, backend.listen.host: 0.0.0.0, backend.database.client: pg, auth.environment: production, auth.providers.github.production 의 clientId 와 clientSecret 은 환경변수 치환 형식, 같은 자리의 signIn.resolvers 첫 항목 resolver 는 카탈로그 User 엔티티에 맞추는 리졸버 이름, techdocs.builder: external, techdocs.publisher.type 은 local 이 아닌 외부 저장소 종류.
7. /root/cba-config/env-names.txt 에 세 설정 파일이 참조하는 환경변수 이름을 중괄호 없이 한 줄에 하나씩, 중복 없이 정렬해 적으세요.
8. 운영 설정을 클러스터에 올리세요. 네임스페이스 cba-config 를 만들고, 그 안에 ConfigMap portal-app-config 를 6 단계 파일에서 만드세요(키 이름이 app-config.production.yaml 이 되어야 합니다). 그리고 Deployment portal 을 만드세요 — 이미지 node:22-alpine, containerPort: 7007, 그 ConfigMap 을 볼륨으로 물리고, 환경변수 APP_CONFIG_app_baseUrl 의 값이 6 단계 파일의 app.baseUrl 과 정확히 같아야 합니다.

참고

• 병합 규칙은 두 줄입니다. 매핑은 키 단위로 깊게, 리스트는 통째로 교체입니다.
• 환경변수 치환은 ${NAME} 형식이고, 이 형식으로 쓰면 값이 파일에 남지 않습니다.
• 흔한 실수 1: 오버라이드에 바꾸지 않을 값까지 복사해 두는 것. 기본 파일이 움직여도 이쪽만 옛 값으로 남습니다.
• 흔한 실수 2: 리스트가 합쳐질 것이라 기대하는 것. 기본 파일의 나머지 항목은 조용히 사라집니다.
• 흔한 실수 3: backend.listen.host 를 기본값으로 두고 컨테이너에 올리는 것. 루프백에만 리슨하면 서비스가 파드에 닿지 못합니다.

단계 8개

1. 기본 app-config
2. 통합과 프록시
3. 카탈로그 규칙과 디스커버리
4. 로컬 오버라이드
5. 병합 결과 예측
6. 운영 설정
7. 환경변수 참조 목록
8. 설정을 클러스터로