카탈로그에 올린 서비스가 조용히 사라진다

목표

VM 안에 진짜 카탈로그 백엔드를 띄우고, 엔티티가 카탈로그에 들어오지 않는 네 가지 원인을 직접 만들어
어디에 흔적이 남는지 찾습니다. 정적 location 자동 수집, API 로 등록하는 location, 고아 엔티티 정리,
location 삭제까지 실제 API 응답으로 확인합니다.

왜 중요한가

"catalog-info.yaml 을 올렸는데 포털에 안 보여요" 는 Backstage 운영에서 가장 흔한 문의입니다.
검증 라이브러리로 YAML 한 개를 확인하는 것만으로는 부족합니다. 돌아가는 카탈로그에서는 실패가
API 응답에도, 기본 로그에도 드러나지 않는 경우가 있고, 한 엔티티의 문제가 같은 파일 전체를 막기도 합니다.
등록 API 가 201 을 돌려줘도 처리 단계에서 실패할 수 있습니다. 어디를 봐야 하는지 알아야 고칠 수 있습니다.

처음 VM 이 뜨는 데 4분쯤 걸리고, 1단계 설치는 인터넷에서 약 30초 걸립니다.
GitHub 같은 외부 시스템을 훑는 탐색(discovery) 공급자는 외부 계정이 필요해 다루지 않습니다.
여기서 "자동 수집" 은 설정에 적은 location 을 카탈로그가 주기적으로 다시 읽는 것입니다.

단계

1. /usr/local/cba-ingest 에 카탈로그 백엔드 패키지를 고정 버전으로 설치합니다.
2. 설정에 적은 파일 location 이 자동으로 수집되는 것을 확인합니다.
3. owner 가 빠진 엔티티가 흔적 없이 빠지는 것을 기록합니다.
4. 로그 모듈을 붙여 처리 오류를 warn 로그로 끌어냅니다.
5. 허용되지 않은 kind 가 파일 전체를 막는 것을 보고 location 별 규칙으로 풉니다.
6. API 로 url location 을 등록하고, 읽기 허용 목록 문제를 고칩니다.
7. 파일에서 뺀 엔티티가 고아가 됐다가 지워지는 것을 봅니다.
8. location 을 지우고 수집 장애 보고서를 씁니다.

참고

• 카탈로그 API 호출: curl -s -H 'Authorization: Bearer ingest-lab-token-7f3a9c' http://127.0.0.1:7007/api/catalog/entities | jq -r '.[].metadata.name'
• 백엔드 다시 띄우기: cd /usr/local/cba-ingest && pkill -f 'node index.js'; setsid nohup node index.js >> backend.log 2>&1 < /dev/null &
• 로그는 이어 씁니다(>>). 기동할 때마다 Loading config from 줄로 시작하니, 지금 프로세스의 로그는 그 마지막 줄 뒤를 보세요.
• 준비 확인: curl -s http://127.0.0.1:7007/.backstage/health/v1/readiness
• 로그의 색 문자 벗기기: sed 's/\x1b\[[0-9;]*m//g' backend.log
• DB 가 :memory: 라서 재시작하면 API 로 등록한 location 은 사라집니다(설정 파일의 location 은 다시 읽힙니다).
• 카탈로그 설정(rules·orphanStrategy·processingInterval·오류 로그 모듈): https://backstage.io/docs/features/software-catalog/configuration
• 엔티티의 일생(처리·고아·삭제): https://backstage.io/docs/features/software-catalog/life-of-an-entity
• 카탈로그 API(locations·entities): https://backstage.io/docs/features/software-catalog/software-catalog-api
• URL Reader 와 backend.reading.allow: https://backstage.io/docs/backend-system/core-services/url-reader
• 외부 호출용 정적 토큰(externalAccess): https://backstage.io/docs/auth/service-to-service-auth
• 엔티티 형식(Component 필수 필드): https://backstage.io/docs/features/software-catalog/descriptor-format

단계 8개

1. 돌아가는 카탈로그의 재료를 고정 버전으로 받는다
2. 설정에 적은 파일이 자동으로 수집된다
3. owner 를 빠뜨린 엔티티는 흔적 없이 빠진다
4. 처리 오류를 로그로 끌어낸다
5. API 하나 때문에 파일 전체가 안 들어온다
6. 등록은 201 인데 아무것도 들어오지 않는다
7. 파일에서 뺀 엔티티는 고아가 됐다가 지워진다
8. location 을 지우고 수집 장애 보고서를 쓴다