시크릿 관리

ASAPJS CLI는 Infisical 과 연동하여 시크릿을 중앙에서 관리할 수 있습니다. .env 파일에 민감한 값을 직접 저장하는 대신, Infisical 프로젝트에서 시크릿을 가져와 애플리케이션에 주입합니다.

Infisical 연동의 장점:

시크릿 중앙 집중 관리 및 버전 관리
팀원 간 안전한 시크릿 공유
환경별(dev, staging, prod) 시크릿 분리
감사 로그를 통한 접근 추적

사전 준비

1. Infisical 프로젝트 설정

Infisical 에서 프로젝트를 생성합니다.
환경(dev, staging, prod 등)별로 시크릿을 등록합니다.
Machine Identity를 생성하고 Universal Auth 방식을 선택합니다.
생성된 Client ID와 Client Secret을 기록합니다.

2. SDK 설치

@infisical/sdk는 선택적 피어 의존성입니다. secrets 설정을 사용하려면 설치가 필요합니다.


yarn add @infisical/sdk

설정

.asapjs.json에 secrets 추가

프로젝트 루트의 .asapjs.json에서 환경별로 secrets 설정을 추가합니다.


{
  "environments": {
    "development": {
      "envFile": "./env/.env.dev",
      "port": 4000,
      "secrets": {
        "provider": "infisical",
        "projectId": "your-project-id",
        "environment": "dev",
        "secretPath": "/",
        "auth": {
          "method": "universal",
          "clientIdEnv": "INFISICAL_CLIENT_ID",
          "clientSecretEnv": "INFISICAL_CLIENT_SECRET"
        }
      }
    }
  }
}

secrets 필드 레퍼런스

필드	타입	필수	설명
`provider`	`'infisical'`	✓	시크릿 제공자
`siteUrl`	`string`	—	자체 호스팅 Infisical URL. 미지정 시 클라우드(`https://app.infisical.com`) 사용
`projectId`	`string`	✓	Infisical 프로젝트 ID
`environment`	`string`	✓	Infisical 환경 슬러그 (`dev`, `staging`, `prod` 등)
`secretPath`	`string`	—	시크릿 경로. 기본값 `/`
`auth.method`	`'universal'`	✓	인증 방식 (현재 Universal Auth만 지원)
`auth.clientId`	`string`	—	Machine Identity Client ID (직접 입력)
`auth.clientSecret`	`string`	—	Machine Identity Client Secret (직접 입력)
`auth.clientIdEnv`	`string`	—	Client ID를 담은 환경 변수 이름
`auth.clientSecretEnv`	`string`	—	Client Secret을 담은 환경 변수 이름

clientId/clientSecret 중 하나 이상의 방식으로 자격 증명을 제공해야 합니다.

인증 방식

직접 입력

.asapjs.json에 clientId와 clientSecret을 직접 기입합니다. 로컬 개발 환경에서 간편하게 사용할 수 있습니다.


{
  "auth": {
    "method": "universal",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret"
  }
}

주의: .asapjs.json에 시크릿을 직접 입력하는 경우, 이 파일을 .gitignore에 추가하거나 프로덕션에서는 환경 변수 참조 방식을 사용하세요.

환경 변수 참조 (권장)

clientIdEnv와 clientSecretEnv에 환경 변수 이름을 지정합니다. 프로덕션 환경에서 권장하는 방식입니다.


{
  "auth": {
    "method": "universal",
    "clientIdEnv": "INFISICAL_CLIENT_ID",
    "clientSecretEnv": "INFISICAL_CLIENT_SECRET"
  }
}

이 경우 시스템 환경 변수 또는 .env 파일에 해당 값을 설정합니다:


export INFISICAL_CLIENT_ID=your-client-id
export INFISICAL_CLIENT_SECRET=your-client-secret

직접 입력 값(clientId/clientSecret)이 환경 변수 참조(clientIdEnv/clientSecretEnv)보다 우선합니다.

환경 변수 병합 순서

asapjs dev와 asapjs start 실행 시, 환경 변수는 다음 순서로 병합됩니다:

우선순위	소스	설명
1 (최우선)	호스트 환경 변수	시스템/셸에 설정된 환경 변수
2	Infisical 시크릿	`.asapjs.json`의 `secrets` 설정으로 가져온 값
3	dotenv 파일	`.env.{env}` 파일에 정의된 값

즉, 같은 키가 여러 소스에 존재하면 호스트 환경 변수가 최종 값이 됩니다. Infisical 시크릿은 dotenv 파일의 값을 덮어쓰지만, 호스트 환경 변수보다는 낮은 우선순위를 가집니다.


최종 env = { ...dotenv, ...infisical, ...호스트 환경 변수 }

연결 확인 (env:check)

asapjs env:check 명령어로 Infisical 연결 상태와 키 병합 결과를 미리 확인할 수 있습니다.


asapjs env:check --env development

출력 예시:


Environment: development
────────────────────────────────────────
✓ Env file: ./env/.env.dev (5 keys)
  Secrets provider: infisical
  Site URL: https://app.infisical.com
  Project: your-project-id
  Environment: dev
  Path: /
✓ Credentials loaded from environment variables
✓ Authenticated (Universal Auth)
✓ Fetched 8 secrets from Infisical

Key Merge Preview:
  DB_HOST                             ← Infisical
  DB_PASSWORD                         ← Infisical
  DB_PORT                             ← dotenv
  JWT_SECRET                          ← Infisical (overrides dotenv)
  NODE_ENV                            ← dotenv

Summary: 3 from Infisical, 2 dotenv-only, 1 overlapping (Infisical wins)

프로덕션 배포

빌드 시 설정 파일 복사

asapjs build 실행 시 .asapjs.json이 출력 디렉토리(dist/)에 자동으로 복사됩니다. asapjs start는 이 파일을 읽어 Infisical 연동을 수행합니다.

Docker 환경

Docker 컨테이너에서는 clientIdEnv/clientSecretEnv 방식을 사용하고, 환경 변수를 컨테이너에 주입합니다.


# docker-compose.yml
services:
  app:
    build: .
    environment:
      INFISICAL_CLIENT_ID: ${INFISICAL_CLIENT_ID}
      INFISICAL_CLIENT_SECRET: ${INFISICAL_CLIENT_SECRET}

CI/CD 파이프라인

CI/CD 환경에서는 시크릿 저장소(GitHub Secrets, AWS Secrets Manager 등)에 Infisical 자격 증명을 저장하고 빌드/배포 시 환경 변수로 주입합니다.

트러블슈팅

에러 메시지	원인	해결
`@infisical/sdk is required when secrets config is present`	SDK 미설치	`yarn add @infisical/sdk` 실행
`Missing Infisical credentials`	`clientId` 또는 `clientSecret` 미설정	`.asapjs.json`의 auth 설정 확인, 환경 변수 설정 확인
`Infisical connection failed`	네트워크 오류 또는 잘못된 자격 증명	`siteUrl`, `projectId`, 자격 증명 값 확인

문제 진단 시 asapjs env:check 명령어를 먼저 실행하여 각 단계별 상태를 확인하세요.