Skip to main content

환경 변수 및 시크릿 관리 가이드

이 문서는 서비스 운영 중 새로운 환경 변수를 추가하거나 기존 변수를 수정할 때, 그리고 Kubernetes Secret을 다룰 때 발생하는 문제와 해결 방법을 다룹니다.

1. Kubernetes Secret에 새로운 민감 정보 추가하기​

백엔드나 워커에서 API Key, DB 접속 정보 등 민감한 정보를 사용해야 할 때의 절차입니다.

상황​

새로운 기능 구현을 위해 BLOCKCHAIN_RPC_URL과 같은 민감한 키가 필요함.

절차​

  1. Secret YAML 파일 수정

    • backend-vivid-ai/backend-secret-dev.yaml (또는 prod) 파일을 엽니다.
    • data 섹션에 새로운 키를 추가합니다. 이때 값은 반드시 Base64로 인코딩되어야 합니다.

  2. Base64 인코딩 (macOS 기준)

    # 줄바꿈 없이 인코딩하여 클립보드에 복사
    echo -n "실제_값_여기에_입력" | base64 | pbcopy
    • 복사된 값을 YAML 파일의 data 섹션에 붙여넣습니다.

  3. Secret 적용

    # 로컬 파일을 클러스터에 바로 적용할 때 (비권장, 임시 조치)
    kubectl apply -f backend-vivid-ai/backend-secret-dev.yaml

    # [권장] GitHub Actions Secret 업데이트
    # 위 파일을 Base64로 한 번 더 인코딩하여 GitHub Repository Secrets에 업데이트합니다.
    base64 -i backend-vivid-ai/backend-secret-dev.yaml | pbcopy
    # 복사된 값을 KUBERNETES_BACKEND_SECRET_YAML_B64_DEV 로 저장

2. Deployment에 환경 변수 연결하기 (Mapping)​

상황​

Secret에는 MY_API_KEY_DEV로 저장되어 있는데, 코드(process.env.MY_API_KEY)에서는 MY_API_KEY를 찾아서 undefined 에러가 발생함.

해결 방법​

Deployment YAML 파일(backend-deployment-dev.yaml)에서 이름 매핑을 정확히 수행해야 합니다.

env:
  - name: MY_API_KEY          # <--- 중요: 코드(Node.js/Python)에서 사용하는 변수명
    valueFrom:
      secretKeyRef:
        name: vivid-ai-secret-dev
        key: MY_API_KEY_DEV   # <--- Secret에 저장된 실제 키 이름

주의 사항​

  • name을 MY_API_KEY_DEV로 설정하면 코드는 해당 변수를 찾지 못해 에러가 발생합니다.
  • 수정 후에는 반드시 kubectl apply -f ... 명령어로 배포를 업데이트해야 합니다.

3. Frontend에 공개 환경 변수 추가하기​

상황​

프론트엔드(NEXT_PUBLIC_...)에 지갑 주소 등 공개되어도 되는 설정을 추가해야 함. Frontend는 별도의 Secret이 없는 경우가 많음.

해결 방법​

frontend-deployment-dev.yaml 파일의 env 섹션에 value를 사용하여 직접 값을 입력합니다.

env:
  - name: NEXT_PUBLIC_TREASURY_ADDRESS
    value: "0x1234..."  # <--- 직접 값 입력

4. 에러 발생 시 확인 방법​

Pod가 CrashLoopBackOff 상태이거나 동작이 이상할 때 로그를 확인합니다.

# 1. Pod 목록 및 상태 확인
kubectl get pods

# 2. 특정 Pod 로그 확인 (에러 원인 파악)
kubectl logs <pod-name>
  • "Configuration key ... does not exist": 환경 변수 매핑(name vs key)이 잘못된 경우입니다.