taeknology/notes

[Infisical] 시크릿 관리 입문: 로컬 Docker 주입과 셀프 호스팅 vs SaaS

한 줄 요약: Infisical 은 .env 파일을 backend 에 옮겨 두고 infisical run -- <command> 한 줄로 자식 프로세스에 환경변수로 주입해 주는 시크릿 관리 도구임.

로컬 Docker 컨테이너부터 운영 배포까지 같은 CLI·SDK 로 시크릿을 받아오고, MIT 라이선스 오픈소스라 셀프 호스팅과 SaaS 중 선택할 수 있음.

개요

처음 Infisical 을 찾아본 계기는 단순함. Docker 로 로컬 개발 환경을 띄우다 보면 컨테이너마다 .env 파일을 따로 두게 되고, 키 하나가 바뀔 때마다 여러 위치의 파일을 동기화하는 일이 누적됨. docker run --env-file 로 주입하는 자체는 어렵지 않지만, 누가·언제·어떤 값을 바꿨는지 추적이 끊기고 파일이 실수로 커밋되거나 슬랙으로 공유되는 사고가 같은 흐름에서 따라옴. 운영으로 가면 CI/CD 시크릿·클라우드 시크릿 매니저로 한 번 더 흩어짐.

이걸 한 backend 로 묶어주는 도구를 찾다가 Infisical 에 정착함. 시크릿을 프로젝트·환경(dev/staging/prod)·폴더 단위로 저장하고, CLI·SDK·Docker·Kubernetes 가 같은 API 로 받아감. 로컬 개발자도, 운영 컨테이너도, K8s pod 도 같은 source of truth 를 봄.

본격 활용법으로 넘어가기 전, 라이선스·핵심 CLI·셀프 호스팅 옵션 등 결정에 영향을 주는 스펙을 한 표로 요약하면 다음과 같음.

항목값
라이선스MIT (단, ee/ 디렉토리의 일부 엔터프라이즈 기능은 별도 라이선스)
핵심 CLIinfisical run [options] -- <command> — 자식 프로세스에 env 주입
인증 방식사용자 로그인 / Machine Identity (서버·CI 권장)
셀프 호스팅Docker · Docker Compose · Helm/Kubernetes · AWS ECS · GCP GKE · Linux package
외부 의존PostgreSQL · Redis (셀프 호스팅 시)
SaaSapp.infisical.com — 무료 plan 부터 시작

결론

무엇이 좋아지는가 — 한 줄 정리

영역.env 만 쓰던 흐름Infisical 도입 후
로컬 Docker.env 파일 공유·동기화 수작업infisical run -- docker compose up 한 줄로 최신 시크릿 주입
배포CI 시크릿·클라우드 KMS 별도 관리Dockerfile 에 infisical run 만 지정해 두면 환경별로 같은 이미지가 다른 값 받음
회전(rotate)변경 시 개발자·배포 파이프라인에 일일이 전파backend 에서 값만 바꾸면 다음 기동부터 자동 반영 (--watch 시 실시간)
감사·권한누가 언제 봤는지 추적 불가audit log·RBAC·환경별 access 분리

셀프 호스팅 vs SaaS — 어느 쪽을 고를 것인가

오픈소스(MIT) 라 두 형태 모두 동일한 코어를 씀.

항목셀프 호스팅 (Self-Hosting)SaaS (app.infisical.com)
데이터 위치자사 인프라 — 외부 전송 없음Infisical 클라우드
컴플라이언스SOC 2·HIPAA·내부 정책을 자체 통제로 충족Infisical 의 인증 범위에 위임
운영 부담PostgreSQL·Redis·업그레이드·백업을 직접0 — 업데이트·가용성 모두 Infisical 책임
초기 도입 속도인프라 준비 시간 필요가입 즉시 사용
적합한 상황금융·의료·공공처럼 데이터 반출이 제약된 조직스타트업·소규모 팀처럼 운영 인력이 부담인 조직

요약하면 보안이 극도로 중요한 기업은 셀프 호스팅으로 시크릿 backend 를 사내에 두고, 관리 부담을 피하고 싶은 팀은 SaaS 로 시작하는 흐름임. 같은 CLI·SDK 라 나중에 SaaS → 셀프 호스팅으로 이전해도 클라이언트 코드는 그대로임.

실제 개인적으로도 두 형태를 분리해서 쓰고 있음 — 회사 업무는 사내 Docker 환경에 셀프 호스팅으로 띄워 쓰고, 개인 프로젝트는 SaaS 무료 plan 을 그대로 쓰는 중임. 개인 프로젝트 규모에서는 무료 plan 이 제공하는 시크릿·프로젝트 수가 충분해 별도 셀프 호스팅을 운영할 이유가 거의 없음.

로컬 활용 — Docker 주입 패턴

infisical run 의 동작은 단순함. CLI 가 backend 에서 시크릿을 받아와 자식 프로세스의 환경변수로 채운 뒤 그 명령을 exec 함. .env 파일을 만들지 않고도 같은 효과가 남.

infisical run --env=dev --projectId=<project-id> -- docker compose up

docker compose up 이 자식 프로세스로 뜨고, compose 파일이 참조하는 ${DB_PASSWORD} 같은 변수가 Infisical 에서 받아온 값으로 치환됨. 별도 .env 파일이 필요 없음.

원리는 단순함. docker compose 는 명령을 실행한 셸의 환경변수를 그대로 읽어 compose 파일의 ${VAR} 자리에 끼워 넣고, environment: 블록에 키만 적힌 변수는 그 값을 컨테이너로 전달함. infisical run 이 그 셸 환경을 시크릿으로 채워주므로 .env 파일 없이도 같은 연결이 성립함.

단일 컨테이너도 동일함.

infisical run --env=dev --projectId=<project-id> -- \
  docker run --rm \
    -e DB_HOST -e DB_USER -e DB_PASSWORD \
    myapp:latest

docker run -e VAR (값 미지정) 은 현재 셸의 동명 환경변수를 그대로 컨테이너에 전달함 — infisical run 이 그 셸 환경을 시크릿으로 채워주기 때문에 자연스럽게 연결됨.

머신 인증(Machine Identity) — CI·서버용 인증

대화형 로그인이 어려운 환경은 Machine Identity 로 토큰을 발급해 환경변수에 둠. 한 번 발급하면 그 다음부터는 CLI 가 토큰만 보고 동작함.

export INFISICAL_TOKEN=$(infisical login \
  --method=universal-auth \
  --client-id=<your-client-id> \
  --client-secret=<your-client-secret> \
  --plain --silent)
 
infisical run --projectId=<project-id> --env=dev -- node server.js

CI 러너는 client-id·client-secret 두 변수만 시크릿으로 받아두면 됨. 그 외 모든 애플리케이션 시크릿은 Infisical backend 가 들고 있음.

OIDC Auth — 시크릿 없이 인증하기

위 방식은 결국 “시크릿을 받아오기 위해 또 다른 시크릿(client-secret) 을 관리해야 하는” 구조임. 이 고리를 끊는 게 OIDC Auth 임. Infisical 은 OIDC 토큰을 발급할 수 있는 플랫폼이라면 client-secret 없이 그 플랫폼의 JWT 만 검증해 인증을 통과시킴. 공식 표현은 “platform-agnostic JWT-based authentication” 으로, GitHub Actions·Kubernetes·AWS 처럼 OIDC provider 가 내장된 환경이라면 별도 시크릿 보관 없이 워크로드 자체의 identity 로 Infisical 에 접근하는 형태가 됨.

장기 보관되는 비밀이 사라지므로 회전·유출 대응 부담이 같이 줄어듦. 처음 도입 시점에는 client-id/secret 방식으로 익히고, 운영 파이프라인이 안정되면 OIDC Auth 로 옮겨가는 흐름이 자연스러움.

배포 방식 — Dockerfile 통합과 장점

운영 배포에서는 컨테이너 이미지에 infisical CLI 를 같이 넣어 두고 CMD 자체를 infisical run 으로 감싸는 형태가 표준임. 환경변수는 빌드 시점이 아니라 런타임에 backend 에서 받아옴.

# (CLI 설치 단계 생략 — apt / apk / curl 중 배포에 맞게)
CMD ["infisical", "run", "--projectId", "<project-id>", "--", "npm", "run", "start"]

컨테이너를 띄울 때는 인증용 토큰만 환경변수로 주입함.

docker run -e INFISICAL_TOKEN=$INFISICAL_TOKEN myimage:latest

이 패턴이 가져오는 운영상 장점.

  • 단일 이미지, 환경별 다른 값 — 같은 이미지를 dev·staging·prod 어디에 배포해도 --env 슬러그만 바꾸면 다른 시크릿 세트를 받음. 환경별 빌드를 따로 굽지 않아도 됨.
  • rotate 가 재배포를 요구하지 않음 — backend 에서 DB 패스워드만 바꿔도 다음 컨테이너 기동부터 새 값을 받음. --watch 플래그를 쓰면 시크릿 변경 감지 시 자식 프로세스를 자동 재기동(공식 표현 “automatically be restarted with the new environment variables attached”) 함 — 코드를 핫리로드하는 게 아니라 프로세스를 끝내고 다시 띄우는 동작이라, 무중단이 중요한 운영보다는 로컬 개발의 hot reload 용도에 적합함.
  • 이미지에 시크릿이 포함되지 않음 — 빌드 아티팩트(Docker layer·CI 로그·registry) 어느 단계에도 평문 시크릿이 남지 않음. 토큰이 유출돼도 폐기·재발급으로 끝남.
  • K8s·ECS 와 패턴 동일 — Helm chart·Operator·ECS task definition 도 INFISICAL_TOKEN 만 주입하는 같은 구조라, 로컬 → CI → K8s 의 멘탈 모델이 한 줄로 이어짐.

셀프 호스팅 vs SaaS — 상세

셀프 호스팅 — 무엇을 직접 운영하는가

기본 구성은 Infisical 컨테이너 + PostgreSQL + Redis 세 가지임. 공식 standalone Docker 예시는 다음 형태로, 5개 환경변수(ENCRYPTION_KEY·AUTH_SECRET·DB_CONNECTION_URI·REDIS_URL·SITE_URL) 가 필수임.

docker run -p 80:8080 \
  -e ENCRYPTION_KEY=<value> \
  -e AUTH_SECRET=<value> \
  -e DB_CONNECTION_URI=<value> \
  -e REDIS_URL=<value> \
  -e SITE_URL=<value> \
  infisical/infisical:<version>

운영 규모로 가면 PostgreSQL·Redis 는 클라우드 PaaS(RDS·ElastiCache 등) 에 위임하고, Infisical 자체는 Kubernetes(Helm chart) · AWS ECS Fargate · GCP GKE 중 익숙한 곳에 올리는 방식이 공식 권장임. Docker Compose 템플릿·Linux 패키지 설치도 지원함.

직접 운영해야 하는 항목은 백업(Postgres 덤프)·업그레이드(이미지 태그 교체)·HTTPS 인증서·접근 IP 제어 정도임.

SaaS — 무엇이 빠지는가

app.infisical.com 에 가입하면 위의 PostgreSQL·Redis·업그레이드·백업 모두 Infisical 이 담당함. 사용자는 프로젝트·환경·시크릿만 등록하고 CLI/SDK 로 받아쓰면 됨. 무료 plan 으로 시작 가능하고, 사용량이 늘면 유료 plan 으로 옮겨감.

데이터가 외부 SaaS 에 저장된다는 점이 의사 결정의 핵심임. 사내 정책상 시크릿을 외부에 두기 어려우면 셀프 호스팅으로 가고, 그 제약이 없으면 SaaS 가 훨씬 빠른 도입 경로임.

이전(migration) 비용은 낮은 편

코어가 동일해 infisical login 의 backend URL 만 SaaS → 셀프 호스팅 도메인으로 바꾸면 클라이언트 동작은 그대로임. 처음 SaaS 로 검증한 뒤 운영 부담을 받아들이고 셀프 호스팅으로 이관하는 흐름이 자연스러움.

참고

관련 글