클라우드 설정 (CloudConfig)

개요

CloudConfig는 클라우드 서비스 프로바이더 관련 설정을 관리합니다. GCP(Google Cloud Platform)에 배포된 애플리케이션에 필요한 프로젝트 ID, 리전, 스토리지 버킷 등의 설정을 정의합니다.

구성 요소

핵심 설정 값

설정 키	환경 변수	타입	필수 여부	기본값	설명
provider	CLOUD_PROVIDER	string	선택	'GCP'	클라우드 서비스 프로바이더 (현재는 GCP만 지원)
projectId	CLOUD_PROJECT_ID	string	필수	-	GCP 프로젝트 ID
region	CLOUD_REGION	string	선택	'asia-northeast3'	GCP 리전 (서울: asia-northeast3)
bucketName	GCS_BUCKET_NAME	string	필수(cloudrun)	-	Google Cloud Storage 버킷 이름

추가 설정 값

설정 키	환경 변수	타입	필수 여부	기본값	설명
credentials	GOOGLE_APPLICATION_CREDENTIALS	string	선택	-	GCP 서비스 계정 인증 정보 파일 경로 (로컬 개발 환경용)
useManagedIdentity	CLOUD_USE_MANAGED_IDENTITY	boolean	선택	true(cloudrun)	관리형 서비스 계정을 사용할지 여부

사용 예시

구성 정의

// libs/core/config/src/lib/namespaces/cloud.config.ts
import { registerAs } from '@nestjs/config';

export const cloudConfig = registerAs('cloud', () => ({
  provider: process.env.CLOUD_PROVIDER || 'GCP',
  projectId: process.env.CLOUD_PROJECT_ID,
  region: process.env.CLOUD_REGION || 'asia-northeast3',
  bucketName: process.env.GCS_BUCKET_NAME,
  credentials: process.env.GOOGLE_APPLICATION_CREDENTIALS,
  useManagedIdentity: process.env.CLOUD_USE_MANAGED_IDENTITY === 'true',
}));

유효성 검증 스키마

// libs/core/config/src/lib/schemas/cloud.schema.ts
import * as Joi from 'joi';

export const cloudConfigSchema = {
  CLOUD_PROVIDER: Joi.string().default('GCP'),
  CLOUD_PROJECT_ID: Joi.string().required(),
  CLOUD_REGION: Joi.string().default('asia-northeast3'),
  GCS_BUCKET_NAME: Joi.string().when('RUNTIME_ENV', {
    is: 'cloudrun',
    then: Joi.string().required(),
    otherwise: Joi.string().optional(),
  }),
  GOOGLE_APPLICATION_CREDENTIALS: Joi.string().optional(),
  CLOUD_USE_MANAGED_IDENTITY: Joi.boolean().default(false),
};

서비스에서 사용

// 클라우드 설정 사용 예시
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@core/config';
import { Storage } from '@google-cloud/storage';

@Injectable()
export class StorageService {
  private storage: Storage;
  private bucketName: string;

  constructor(private readonly configService: ConfigService) {
    // 클라우드 설정 로드
    const cloudConfig = this.configService.getNamespace<{
      projectId: string;
      region: string;
      bucketName: string;
      credentials?: string;
    }>('cloud');

    // GCS 클라이언트 초기화
    this.storage = new Storage({
      projectId: cloudConfig.projectId,
      keyFilename: cloudConfig.credentials,
    });
    
    this.bucketName = cloudConfig.bucketName;
  }

  async uploadFile(fileName: string, fileBuffer: Buffer): Promise<string> {
    const bucket = this.storage.bucket(this.bucketName);
    const file = bucket.file(fileName);
    
    await file.save(fileBuffer, {
      contentType: 'application/octet-stream',
    });
    
    // 공개 URL 반환
    return `https://storage.googleapis.com/${this.bucketName}/${fileName}`;
  }
}

환경별 설정 가이드

로컬 개발 환경

로컬 개발 환경에서는 서비스별 JSON 설정 파일을 통해 클라우드 설정을 구성합니다. 서비스 계정 키 파일은 상대 경로로 지정할 수 있습니다.

// cloudrun-deploy/secret/local/dev/dta-wide-api.json
{
  "CLOUD_PROVIDER": "GCP",
  "CLOUD_PROJECT_ID": "dta-cloud-de-dev",
  "CLOUD_REGION": "europe-west3",
  "GCS_BUCKET_NAME": "dtx-llm",
  "GOOGLE_APPLICATION_CREDENTIALS": "./credentials/dta-wide-api-credentials.json",
  "CLOUD_USE_MANAGED_IDENTITY": "false"
}

클라우드 런 환경

클라우드 런 환경에서는 관리형 서비스 계정을 사용하여 GCP 서비스에 접근합니다. 설정은 서비스별 JSON 파일에 정의하며, 배포 프로세스에서 Cloud Run 서비스의 환경 변수로 자동 설정됩니다.

// cloudrun-deploy/secret/cloudrun/prod/dta-wide-api.json
{
  "CLOUD_PROVIDER": "GCP",
  "CLOUD_PROJECT_ID": "dta-cloud-de-prod",
  "CLOUD_REGION": "europe-west3",
  "GCS_BUCKET_NAME": "dtx-llm-prod",
  "CLOUD_USE_MANAGED_IDENTITY": "true"
}

주의 사항

• CLOUD_PROJECT_ID는 반드시 설정해야 하며, 실제 GCP 프로젝트 ID와 일치해야 합니다.
• 로컬 개발 환경에서는 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 설정하여 서비스 계정 키 파일을 지정해야 합니다.
• 클라우드 런 환경에서는 서비스에 적절한 IAM 권한이 부여된 서비스 계정을 연결해야 합니다.
• 민감한 데이터를 저장하는 경우, 스토리지 버킷에 적절한 액세스 제어가 설정되어 있어야 합니다.