Vault 프록시(Vault Proxy)

Vault 프록시는 클라이언트와 Vault 서버 사이에 위치하는 클라이언트 쪽 프록시로, 애플리케이션이 Vault 프록시를 통해 토큰 기반 요청을 보내면 프록시가 실제 Vault 작업을 대신 수행합니다. 이는 애플리케이션이 Vault Agent의 구성 파일을 그대로 사용하되, Vault 프록시를 실행하게 하는 방식을 권장합니다.

참고: Vault Agent는 시크릿 캐싱(secret caching) 기능을 포함하며, 더 광범위한 사용 사례(시크릿과 인증을 직접 제공)를 다룹니다. Vault 프록시는 클라이언트와 Vault 간의 네트워크 프록시 역할에 초점을 맞추며, 자체적으로 시크릿을 주입하지는 않습니다.

Vault 프록시란 무엇인가요?

Vault 프록시는 클라이언트와 Vault 서버 사이에 배치되는 경량 클라이언트 쪽 프록시입니다. Vault 프록시가 제공하는 주요 기능은 다음과 같습니다.

캐싱 — Vault 프록시가 Vault로부터 받은 응답을 캐시합니다. 허용된 캐싱은 애플리케이션 요청의 호출 횟수와 대기 시간을 크게 줄여 줍니다.
자동 인증(auto-auth) — Vault 프록시에게 서비스별 인증 방법을 구성할 수 있습니다. 이 기능을 켜면 Vault 프록시가 인증 방법으로 이미 인증된 새 토큰을 자동으로 가져오는 태스크를 시작합니다.
임대 갱신(lease renewal) — Vault 프록시가 구성된 임대를 자동으로 갱신합니다.

설치하기

설치 문서에서 최신 버전을 다운로드할 수 있고, 공개 문서를 따라 설치할 수 있습니다.

Vault은 바이너리 하나로 패키징되어 있으며, 설치 후 실행 파일 이름 몇 개가 자동으로 만들어집니다. 다음은 그중에서 Vault 프록시와 관련된 것입니다.

vault — Vault 서버 및 기타 Vault 명령어
vault-proxy — Vault 프록시 실행 파일

참고: Vault 프록시 실행 파일은 배포판에 포함되어 있지만, 기본 실행 파일 이름 vault에서는 별도로 노출되지 않습니다. vault-proxy 실행 파일은 Vault 바이너리에서 직접 사용할 수 있습니다.

Vault 프록시 사용하기

Vault 프록시를 사용하려면 다음이 필요합니다.

디스크나 환경에 Vault 프록시 구성 파일, 그리고 (자동 인증을 사용하는 경우) 구성에 필요한 인증 방법 자격 증명이 있어야 합니다. 구성 파일의 예시는 Agent 구성 예시에서 찾을 수 있습니다.

Vault 프록시 구성하기

Vault 프록시는 구성 파일을 받아 들이고, 여러 가지 구성 방법을 지원합니다.

Vault 프록시는 -config 플래그를 통해 구성 파일(또는 구성 파일이 있는 폴더) 경로를 받습니다. 이 플래그는 여러 번 사용할 수 있으며, 같은 프로세스에서 여러 구성 파일을 병합할 수 있습니다.

$ vault-proxy -config=/etc/vault-proxy.d/

환경 변수를 통한 구성도 지원합니다. 자세한 내용은 Agent 환경 변수 문서를 참고하세요.

구성 파일의 위치와 병합

Vault 프록시는 구성 파일을 JSON 또는 HCL 형식으로 받아 들입니다. 구성 파일 경로가 디렉터리라면, 디렉터리 안의 모든 일반 파일(*.json, *.hcl 접미사)이 알파벳순으로 병합됩니다. 하위 디렉터리는 읽지 않습니다.

-config를 여러 번 지정해 여러 구성 파일을 병합할 수도 있습니다. 병합하는 동안 특정 키에 대한 중복 정의가 있으면 어떻게 될까요? 서로 다른 구성 파일에서 같은 키가 두 번 정의되면, 나중에 지정한 파일의 값이 앞선 값에 병합됩니다. 예를 들어 -config=foo.hcl -config=bar.hcl로 실행하면 foo.hcl의 값이 bar.hcl의 값으로 덮어써집니다. 같은 키를 수정하는 동안 병합은 한 번 더 일어납니다.

API 프록시 구성 시 주의할 점

새로운 기능이나 구성을 더하면서도 이전에 구성한 값이 유지되는 방식을 원한다면 기본 구성을 여러 파일로 나누고, 특정 배포 환경의 차이를 -config로 재정의하는 것이 좋습니다. -config는 프로세스 시작 시에만 읽기 때문에, 이후 -config 값을 바꾸려면 프로세스를 재시작해야 합니다.

캐싱과 임대 갱신

Vault 프록시는 캐싱과 임대 갱신을 기본적으로 지원합니다. 프록시의 기본 구성 파일 안에서 cache 설정을 켜면 됩니다.

cache {
  use_auto_auth_token = true
}

위 구성에서 use_auto_auth_token은 프록시가 자동 인증을 통해 얻은 토큰을 캐시(및 갱신)에 사용하도록 만들 수도 있고, 애플리케이션이 직접 제공하는 토큰을 사용하도록 만들 수도 있습니다. 두 방식 모두 기본 cache 신택스로 동작합니다. 자동 인증을 사용하지 않고도 캐싱과 임대 갱신을 쓸 수 있습니다. 프록시가 캐시 역할을 하려면 클라이언트 요청에 Vault 토큰이 포함되어 있어야 합니다. Vault 프록시는 클라이언트가 X-Vault-Token 헤더로 토큰을 제공할 때 처음 요청부터 그 토큰을 캐시하고 갱신합니다.

참고: Vault 프록시가 자동 인증을 사용할 때는 상태(예: 캐시에 넣은 시크릿)가 디스크 저장소에 쓰이지 않습니다. 대신 Bearer 토큰, 임대 갱신, 캐시된 응답이 모두 메모리에 보관됩니다. 프록시를 재시작하면 모든 캐시가 비워집니다.

인증

Vault 프록시는 인증에 자동 인증을 지원합니다. 자동 인증을 켜면 Vault 프록시는 구성된 인증 방법을 사용해 Vault에 자동으로 로그인합니다. 이렇게 인증된 토큰은 Vault 프록시 자체의 Vault 토큰으로 사용될 수 있고, Vault에 접근해야 하는 로컬 애플리케이션에도 전달될 수 있습니다.

vault {
  address = "https://127.0.0.1:8200"
}

auto_auth {
  method {
    type      = "aws"
    namespace = "my-namespace"

    config = {
      type = "iam"
      role = "foobar"
    }
  }
}

클라이언트 구성하기

Vault 프록시가 실행 중이면, 애플리케이션이 Vault 서버에 직접 접근하는 대신 프록시를 통해 요청을 보낼 수 있습니다.

VAULT_ADDR 환경 변수를 Vault 프록시 주소로 설정하면 됩니다.

$ export VAULT_ADDR="http://127.0.0.1:8000"

Vault 서버에 직접 접근하기 위한 다른 Vault 클라이언트 구성(예: VAULT_TOKEN, VAULT_NAMESPACE)은 그대로 유지할 수 있습니다. 캐싱을 사용할 때는 Vault 프록시가 요청자의 정체를 구분하기 위해 프록시가 지원하는 인증 헤더를 그대로 사용합니다.

경고: Vault 프록시는 요청을 캐시할 때 요청의 대상 경로(payload)뿐 아니라 요청 헤더와 경로 변수도 봅니다. 따라서 캐시된 응답이 잘못된 다른 요청에 노출되지 않게 하려면, 요청 시 Vault 토큰 헤더가 항상 정확한 것이어야 합니다.

Vault 프록시와 암호화

Vault 프록시는 TLS를 사용해 Vault 서버와 안전하게 통신합니다. 다음 옵션으로 프록시 자신의 TLS 동작을 구성할 수 있습니다.

-tls-skip-verify — 프록시가 서버 인증서의 검증을 건너뛰도록 합니다(권장하지 않음).
-tls-server-name — 프록시가 연결 시 사용할 TLS 서버 이름을 지정합니다.

Vault 프록시 로그 삭제

Vault 버전 1.6.0부터 Vault 프록시 로그는 더 이상 디렉터리에 저장되지 않고, 로그 설정에 따라 표준 출력(stdout)으로 출력됩니다. vault-proxy에는 자체적인 로그 삭제로테이션이 없습니다. 운영 체제나 배포 환경의 로그 로테이션 도구(예: logrotate)를 사용하는 것이 좋습니다.

더 알아보기

출처: 문서