컨테이너에 생명 불어넣기: 환경별 Backstage 설정 주입의 모든 것

안녕하세요! 오늘은 Backstage를 컨테이너 환경(Docker, Kubernetes 등)에서 운영할 때 가장 중요한 주제 중 하나인 '환경별 설정(Environment-specific Configuration) 주입 방법'에 대해 상세히 알아보겠습니다. 🚀

서비스를 개발 환경에서 운영 환경으로 배포할 때, 소스 코드는 그대로 두되 데이터베이스 주소나 API 키만 싹 바꾸고 싶으셨죠? Backstage 컨테이너에서 이를 실현하는 스마트한 방법들을 정리해 드립니다! 💡

---

🏗️ Backstage 설정의 핵심 원리

Backstage는 실행 시점에 여러 설정 파일을 읽어 들이는 계층적 설정(Hierarchical Configuration) 구조를 가지고 있습니다. 컨테이너가 가동될 때 특정 환경에 맞는 옷을 입혀주는 과정이라고 이해하시면 쉽습니다.

---

🌟 1. 여러 개의 설정 파일 활용하기 (--config 플래그)

컨테이너를 실행할 때 어떤 설정 파일을 사용할지 직접 지정하는 방법입니다.

• 동작 방식: backstage-cli 명령어나 컨테이너의 진입점(Entrypoint)에서 --config 인자를 사용합니다.
• 실전 예시:
  

  # 기본 설정에 운영 환경 설정을 덮어씌우기
  node packages/backend --config app-config.yaml --config app-config.production.yaml

  
  

 

• 장점: 환경별로 명확하게 구분된 파일을 사용할 수 있어 관리가 직관적입니다.

---

🔐 2. 환경 변수(Environment Variables) 사용 (강력 추천!)

컨테이너 환경에서 가장 표준적이고 권장되는 방식입니다. app-config.yaml 안에 비밀 값을 직접 적는 대신 변수명을 적어두고, 컨테이너 실행 시 실제 값을 주입합니다.

• YAML

  YAML 작성법: ${ } 문법을 사용합니다.

  backend:
    baseUrl: ${BACKEND_URL}
    database:
      connection:
        password: ${POSTGRES_PASSWORD}

• 컨테이너 주입:
  • Docker: -e 플래그 사용 (docker run -e BACKEND_URL=...)
  • Kubernetes: env 섹션이나 ConfigMap, Secret을 통해 주입

---

📁 3. 설정 파일 마운트 (Volume Mount)

이미지 안에 설정 파일을 구워 넣는 대신, 실행 시점에 외부 파일을 컨테이너 내부로 넣어주는 방식입니다.

• 방법: Kubernetes의 ConfigMap을 생성하고 이를 컨테이너의 /app/app-config.production.yaml 경로로 마운트합니다.
• 활용: 환경마다 완전히 다른 복잡한 설정을 적용해야 할 때 유용합니다.

---

🔍 4. APP_CONFIG_ 환경 변수 접두사 활용

Backstage는 특정 규칙을 가진 환경 변수를 자동으로 설정값으로 인식하는 영리한 기능을 제공합니다.

• 규칙: APP_CONFIG_로 시작하는 환경 변수를 만들면, 하이픈(-)을 언더바(_)로 바꾼 경로를 찾아 값을 넣어줍니다.
• 예시: APP_CONFIG_app_baseUrl=https://backstage.example.com이라는 환경 변수는 자동으로 app.baseUrl 설정값이 됩니다.

---

💡 어떤 방법을 선택해야 할까요?

방법	추천 상황	특징
환경 변수 주입	API 키, 비밀번호 등 민감 정보	가장 안전하고 표준적인 방식
파일 재정의	개발/운영 등 환경 자체가 다를 때	구조적인 설정 변경에 유리
볼륨 마운트	인프라 팀에서 설정을 관리할 때	이미지 수정 없이 설정 교체 가능

---

🏁 결론: 유연한 배포를 위한 첫걸음

컨테이너 기반의 Backstage 운영에서 핵심은 "이미지는 한 번만 빌드하고, 설정은 실행할 때 결정한다"는 것입니다. --config 플래그로 뼈대를 잡고, 환경 변수로 세부 근육(비밀 정보 등)을 채워 넣는 조합이 가장 이상적입니다. 🚀

지금 여러분의 파이프라인에 이 방식들을 적용하여, 환경 변화에도 끄떡없는 견고한 Backstage 시스템을 구축해 보세요! ✨

---