프로젝트의 환경변수는 민감한 정보일 수 있는 데이터들입니다.

그렇기에, 보안상의 목적으로 환경변수 관리방식은 매우 중요한 포인트입니다.

GitHub Private Repository를 사용하더라도 코드베이스에 .env 파일을 직접 포함시키는 것은 잠재적인 보안 위협이 있을 수 있기 때문에 환경변수를 안전하게 등록하고 관리할 수 있는 AWS SSM ParameterStore를 알게되었습니다.

AWS SSM Parameter Store란?

환경 변수, 데이터베이스 연결 문자열, 비밀번호, 외부 API 키 등의 구성 데이터와 비밀값(Secrets)을 안전하게 저장하고 관리할 수 있도록 해주는 AWS의 관리형 서비스입니다.

기존에는 이러한 설정값들을 코드 내부에 하드코딩하거나 EC2, 컨테이너 환경의 로컬 파일에 직접 주입했다면, Parameter Store를 사용함으로써 애플리케이션 코드와 설정 데이터를 완벽하게 분리할 수 있습니다.

주요 특징 및 장점

강력한 보안 및 암호화

일반적인 평문(String) 저장뿐만 아니라, 민감한 데이터는 SecureString 타입을 사용하여 AWS KMS(Key Management Service)를 통해 안전하게 암호화하여 저장합니다.

계층적 구조 관리

파일 시스템의 디렉터리처럼 슬래시(/)를 이용해 환경 변수를 논리적인 그룹으로 묶어서 관리할 수 있습니다. 예시: /my-app/dev/DB_PASSWORD, /my-app/prod/API_KEY

세밀한 접근 제어 (IAM 연동)

AWS IAM(Identity and Access Management)과 완벽하게 통합되어 있습니다. 특정 서버(EC2, ECS)나 람다(Lambda) 함수, 혹은 특정 개발자만 /my-app/prod/ 경로의 파라미터에 접근할 수 있도록 세밀하게 권한을 통제할 수 있습니다.

버전 관리

파라미터의 값이 업데이트될 때마다 자동으로 버전을 기록합니다. 만약 설정값을 잘못 변경해서 장애가 발생하더라도, 즉시 이전 버전의 값을 확인하고 롤백할 수 있습니다.

뛰어난 비용 효율성

일반적인 Standard 파라미터의 경우 한 계정당 최대 10,000개까지 무료로 제공되므로, 초기 스타트업이나 개인 프로젝트에서도 비용 부담 없이 도입하기 아주 좋은 서비스입니다.

AWS CLI로 Parameter Store에 업로드하는 방법

기존에 AWS CLI가 설치되어있어야하고, IAM이 설정되어있어야합니다.

aws ssm put-parameter \
  --name "/my-app/dev/DB_PASSWORD" \
  --value "mySuperSecretPassword123!" \
  --type "SecureString" \
  --overwrite

주요 옵션 설명:

--name: 저장할 파라미터의 이름(키)입니다. 위 예시처럼 /프로젝트명/환경/키 형태의 계층적 구조를 사용하는 것이 일반적입니다.
--value: 저장할 실제 값입니다.
--type: 값의 타입을 지정합니다. (String, StringList, SecureString 중 택 1)
--overwrite: 동일한 이름의 키가 이미 존재할 경우, 새로운 값으로 덮어씁니다. 이 옵션이 없으면 이미 존재하는 키를 업로드할 때 에러가 발생합니다.

이처럼 AWS CLI를 사용하면 터미널에서도 파라미터를 등록할 수 있습니다.

하지만 .env 파일에 여러개의 환경변수가 있다면 어떨까요? 위 명령어를 값만 바꿔가며 n번 실행하거나, 복잡한 쉘 스크립트를 직접 짜야 합니다. 또한 업로드 과정에 오타같은 휴먼오류가 발생할 수 있습니다.

이런 단순 반복 작업과 휴먼 에러를 없애기 위해, .env 파일을 통째로 읽어 한 번에 SecureString으로 업로드해 주는 @inhanbyeol/ssm-env-uploader를 개발하게 되었습니다.

@inhanbyeol/ssm-env-uploader 시작하기

NodeJS가 설치되어있어야 합니다.

설치

# npm을 사용하는 경우
npm install -g @inhanbyeol/ssm-env-uploader

# pnpm을 사용하는 경우
pnpm add -g @inhanbyeol/ssm-env-uploader

사용 방법

환경변수 업로드

1. 초기화

프로젝트 루트 디렉토리에서 아래 명령어를 실행하면, 기본 설정 파일인 seu-cli.json이 자동으로 생성됩니다.

seu --init

2. 설정 파일 작성

생성된 seu-cli.json 파일을 열고 프로젝트 아키텍처에 맞게 값을 입력합니다.

{
  "basePath": "your-app-name",
  "region": "ap-northeast-2",
  "cliProfile": "default",
  "concurrency": 1,
  "envFile": {
    "dev": ".env.dev",
    "prod": ".env.prod"
  }
}

basePath: SSM 파라미터 경로의 앞부분 접두사 (예: /your-app-name)
region: AWS 리전 (예: 서울 리전의 경우 ap-northeast-2)
cliProfile (선택): 업로드에 사용할 AWS CLI 프로필 이름
concurrency (선택): 병렬로 처리할 업로드 개수 (기본값: 1)
envFile: 명령어 실행 시 사용할 환경(env) 키워드와 실제 .env 파일 경로의 매핑 정보

3. 업로드 실행

설정이 완료되면 터미널에 seu 명령어와 함께 매핑해둔 환경 이름을 입력합니다.

seu dev

실행 결과: /your-app-name/dev 경로로 .env.dev 파일 내부의 값들이 Parameter Store에 성공적으로 일괄 업로드됩니다.

환경변수 다운로드

개발 환경이 변경되었거나, 로컬에 특정 환경의 환경변수 파일이 필요한 경우 스토어에 등록된 값들을 다운받을수 있습니다.

사전에 seu값이 설정되어있어야 합니다.

1. 다운로드 실행

seu dev --get

파라미터 스토어에 등록 완료된 환경변수들은 애플리케이션 배포 시점에 AWS CLI 명령어를 통해 간편하게 서버로 내려받을 수 있습니다. 또한, 배포 단계를 넘어 서버 인스턴스화 과정 자체에 AWS SSM 연동을 구성하여, 서버가 실행될 때 런타임 환경변수로 자동 등록 및 주입되도록 아키텍처를 유연하게 설계할 수도 있습니다.

AWS 파라미터 스토어에 환경변수를 등록하여 관리하기