Backstage 운영 꿀팁: 런타임에 설정 값을 즉시 변경하는 마법 (환경 변수 편)

안녕하세요! 오늘은 Backstage를 운영 환경에 배포할 때, 이미 빌드된 결과물을 수정하지 않고 실시간(Runtime)으로 설정을 변경하는 가장 직접적인 방법에 대해 깊이 있게 알아보겠습니다. 🚀

개발 환경에서는 app-config.yaml 파일을 직접 수정하면 되지만, Docker 컨테이너로 배포된 운영 환경에서는 파일을 매번 수정하고 다시 빌드하는 것이 불가능에 가깝죠. 이때 우리가 사용할 수 있는 '가장 강력하고 직접적인 무기'는 무엇일까요? 💡

---

🏗️ 정답은 바로 '환경 변수(Environment Variables)' 입니다! 🌡️

Backstage에서 런타임에 단일 설정 값을 덮어쓰는 가장 직접적이고 표준적인 방법은 바로 환경 변수를 활용하는 것입니다.

Backstage의 설정 엔진인 config-loader는 실행 시점에 특정 규칙을 가진 환경 변수를 찾아 YAML 파일에 정의된 값을 대체합니다.

---

🌟 왜 환경 변수를 사용해야 할까요?

1. 빌드와 설정의 분리: 한 번 빌드된 Docker 이미지를 개발, 스테이징, 운영 환경에서 재사용할 수 있습니다. (Build Once, Run Anywhere! 🏎️)
2. 보안: API 키, DB 비밀번호 등 민감한 정보를 YAML 파일에 하드코딩하지 않고 시스템 레벨에서 주입할 수 있습니다. 🔐
3. 유연성: Kubernetes나 Docker Compose 설정만 바꾸면 즉시 반영되므로 대응 속도가 매우 빠릅니다. ⚡

---

🛠️ 실전 활용법: 환경 변수 이름 규칙 (Naming Convention)

Backstage는 YAML 파일의 계층 구조를 환경 변수로 변환할 때 아주 명확한 규칙을 따릅니다.

📝 규칙 1: 대문자와 언더바(_)

YAML의 키 값을 모두 대문자로 바꾸고, 계층 구분은 언더바 두 개(__) 또는 언더바 한 개(_)를 사용합니다. (최근 버전은 가독성을 위해 APP_CONFIG_ 접두사와 함께 사용하는 것을 권장하지만, 가장 직접적인 방식은 아래와 같습니다.)

💡 실제 예시

만약 app-config.yaml에 다음과 같은 설정이 있다고 가정해 봅시다.

YAML

app:
  baseUrl: https://my-backstage.com
backend:
  database:
    connection:
      host: localhost

이 값을 런타임에 덮어쓰고 싶다면 다음과 같이 환경 변수를 설정합니다.

• URL 변경 시: APP_CONFIG_app_baseUrl=https://new-url.com
• DB 호스트 변경 시: APP_CONFIG_backend_database_connection_host=db.production.com

중요 포인트! 🚩

Backstage는 기본적으로 APP_CONFIG_로 시작하는 환경 변수를 자동으로 감지하여 내부 설정으로 매핑합니다.

예: APP_CONFIG_backend_auth_keys_0="my-secret-key"

---

🏗️ 다양한 환경에서의 주입 방법

1. Docker에서 사용하기 🐳

Bash

docker run -e APP_CONFIG_app_baseUrl=https://prod.com my-backstage-image

2. Kubernetes(K8s)에서 사용하기 ☸️

deployment.yaml의 env 섹션에 정의합니다.

YAML

spec:
  containers:
  - name: backstage
    env:
    - name: APP_CONFIG_app_baseUrl
      value: "https://k8s-backstage.com"

3. Docker Compose에서 사용하기 🐙

YAML

services:
  backstage:
    environment:
      - APP_CONFIG_app_baseUrl=http://localhost:3000

---

⚠️ 주의해야 할 점 (Best Practices)

1. 데이터 타입 준수: 숫자는 숫자로, 불리언(true/false)은 해당 형식에 맞게 전달되어야 합니다.
2. 배열 처리: 배열의 특정 인덱스를 바꾸고 싶을 때는 _0, _1과 같이 숫자를 접미사로 붙입니다.
   • 예: APP_CONFIG_organization_name_0="First Org"
3. 우선순위: 환경 변수는 항상 app-config.yaml 파일에 명시된 값보다 높은 우선순위를 가집니다. 즉, 환경 변수가 설정되어 있다면 파일의 내용은 무시됩니다. 🔝

---

🏁 결론: 런타임 설정의 제왕은 '환경 변수'

Backstage 배포 환경에서 단일 설정 값을 가장 빠르고 직접적으로 바꾸고 싶다면 고민하지 말고 환경 변수(APP_CONFIG_...)를 사용하세요. 이것이 클라우드 네이티브 환경에서 Backstage를 가장 똑똑하게 운영하는 방법입니다! 🚀

---