Vault Agent란 무엇인가?

Vault Agent란 무엇인가? (What is Vault Agent?)

Vault Agent는 애플리케이션이 Vault와 통합하는 더 확장 가능하고 간단한 방법을 제공함으로써, Vault 도입의 초기 장벽을 없애는 것을 목표로 합니다. 애플리케이션을 변경할 필요 없이, 애플리케이션이 필요한 시크릿을 담은 템플릿을 렌더링할 수 있게 해 줍니다.

Vault Agent workflow

Vault Agent는 다음 기능을 제공하는 클라이언트 데몬입니다.

Auto-auth — Vault에 자동으로 인증하고, 로컬에서 가져온 동적 시크릿의 토큰 갱신 과정을 관리합니다.
API 프록시(deprecated) — Vault Agent가 Vault의 API를 위한 프록시 역할을 하게 해 줍니다. 이 기능은 Vault Agent에서 폐기되었습니다. Vault API 프록시로는 Vault Proxy를 사용하세요.
캐싱 — 새로 생성된 토큰을 담은 응답과, 이 새 토큰에서 파생된 임대 시크릿을 담은 응답의 클라이언트 측 캐싱을 지원합니다. 에이전트는 캐시된 토큰과 임대의 갱신도 관리합니다.
Windows 서비스 — Vault Agent를 Windows 서비스로 실행할 수 있게 해 줍니다.
템플릿 — Auto-auth 단계에서 생성된 토큰을 사용해 Vault Agent가 사용자 제공 템플릿을 렌더링할 수 있게 해 줍니다.
프로세스 슈퍼바이저 모드 — Vault 시크릿을 환경 변수로 주입해 하위 프로세스를 실행합니다.

출처: 문서

본문

Auto-auth

Vault Agent는 다양한 환경에서 Vault에 쉽게 인증할 수 있게 해 줍니다. 자세한 내용은 Auto-auth 문서를 참조하세요.

Auto-auth 기능은 auto_auth 구성 스탠자(stanza) 안에서 동작합니다.

캐싱

Vault Agent는 새로 생성된 토큰을 담은 응답과, 이 새 토큰에서 파생된 임대 시크릿을 담은 응답의 클라이언트 측 캐싱을 지원합니다. 자세한 내용은 캐싱 문서를 참조하세요.

API

Quit

이 엔드포인트는 에이전트의 종료를 트리거합니다. 기본적으로 비활성화되어 있으며, 리스너별로 agent_api 스탠자로 활성화할 수 있습니다. 이 엔드포인트는 사용에 어떤 권한도 요구하지 않으므로 신뢰할 수 있는 인터페이스에서만 활성화할 것을 권합니다.

Method	Path
`POST`	`/agent/v1/quit`

Cache

캐시 API에 대한 자세한 내용은 캐싱 페이지를 참조하세요.

구성 (Configuration)

커맨드 옵션

-log-level (string: "info") — 로그 상세 수준입니다. 지원되는 값(상세도 내림차순)은 trace, debug, info, warn, error입니다. VAULT_LOG_LEVEL 환경 변수로도 지정할 수 있습니다.
-log-format (string: "standard") — 로그 형식입니다. 지원되는 값은 standard와 json입니다. VAULT_LOG_FORMAT 환경 변수로도 지정할 수 있습니다.

-log-file — Vault Agent가 로그 메시지를 저장해야 하는 절대 경로입니다. 경로 구분자로 끝나는 경로는 기본 파일 이름인 agent.log를 사용합니다. 파일 확장자로 끝나지 않는 경로는 기본 .log 확장자를 사용합니다. 로그 파일이 회전(rotate)하면 Vault Agent는 회전 시점의 타임스탬프를 파일 이름에 추가합니다. 예:

`log-file`	Full log file	Rotated log file
`/var/log`	`/var/log/agent.log`	`/var/log/agent-{timestamp}.log`
`/var/log/my-diary`	`/var/log/my-diary.log`	`/var/log/my-diary-{timestamp}.log`
`/var/log/my-diary.txt`	`/var/log/my-diary.txt`	`/var/log/my-diary-{timestamp}.txt`

-log-rotate-bytes — 로그가 회전되기 전에 로그 파일에 기록되어야 하는 바이트 수를 지정합니다. 지정하지 않으면 로그 파일에 쓸 수 있는 바이트 수에 제한이 없습니다.
-log-rotate-duration — 로그가 회전되기 전에 기록되어야 하는 최대 기간을 지정합니다. 30s 같은 기간(duration) 값이어야 합니다. 기본값은 24h입니다.
-log-rotate-max-files — 보관할 이전 로그 파일 아카이브의 최대 수를 지정합니다. 기본값은 0(파일이 삭제되지 않음)입니다. -1로 설정하면 새 로그 파일이 만들어질 때 이전 로그 파일을 버립니다.

구성 파일 옵션

현재 사용 가능한 일반 구성 옵션은 다음과 같습니다.

vault (vault: <optional>) — 에이전트가 연결하는 원격 Vault 서버를 지정합니다.
auto_auth (auto_auth: <optional>) — auto-auth 기능에 사용되는 방법과 기타 옵션을 지정합니다.
api_proxy (api_proxy: <optional>) — API 프록시 기능에 사용되는 옵션을 지정합니다.
cache (cache: <optional>) — 캐싱 기능에 사용되는 옵션을 지정합니다.
listener (listener: <optional>) — 에이전트가 요청에 응답할 주소와 포트를 지정합니다.

팁

SIGHUP(kill -SIGHUP $(pidof vault)) 신호 시 Vault Agent는 리스너 TLS 구성을 다시 로드하려고 시도합니다. 이 방법을 사용하면 프로세스를 재시작하지 않고 Vault Agent가 사용하는 인증서를 새로고침할 수 있습니다.
pid_file (string: "") — 에이전트의 프로세스 ID(PID)를 저장해야 하는 파일 경로입니다.
exit_after_auth (bool: false) — true로 설정하면 에이전트는 한 번의 성공적인 인증 후 코드 0으로 종료합니다. 여기서 성공은 토큰이 검색되고 모든 싱크(sink)가 이를 성공적으로 기록했음을 의미합니다. 에이전트 구성에 template 스탠자가 있으면 에이전트는 구성된 템플릿이 성공적으로 렌더링될 때까지 기다렸다가 종료합니다. 환경 템플릿(env_template)을 사용하면서 exit_after_auth를 true로 설정하면 Vault agent는 exec 스탠자에 정의된 하위 프로세스를 실행하지 않습니다.
disable_idle_connections (string array: []) — Vault Agent의 다양한 기능에 대해 유휴 연결(idle connection)을 비활성화하는 문자열 목록입니다. 유효한 값은 auto-auth, caching, proxying, templating입니다. proxying은 API 프록시에 대해 이를 구성하며, 역사적 이유로 caching과 기능이 동일합니다. VAULT_AGENT_DISABLE_IDLE_CONNECTIONS 환경 변수를 쉼표로 구분된 문자열로 설정해 구성할 수도 있습니다. 이 환경 변수는 구성 파일의 어떤 값보다 우선합니다.
disable_keep_alives (string array: []) — Vault Agent의 다양한 기능에 대해 keep-alive를 비활성화하는 문자열 목록입니다. 유효한 값은 auto-auth, caching, proxying, templating입니다. proxying은 API 프록시에 대해 이를 구성하며, 역사적 이유로 caching과 기능이 동일합니다. VAULT_AGENT_DISABLE_KEEP_ALIVES 환경 변수를 쉼표로 구분된 문자열로 설정해 구성할 수도 있습니다. 이 환경 변수는 구성 파일의 어떤 값보다 우선합니다.
template (template: <optional>) — Vault 시크릿을 파일로 템플릿화하는 데 사용되는 옵션을 지정합니다.
template_config (template_config: <optional>) — 템플릿 엔진 동작을 지정합니다.
pki_external_ca (pki_external_ca: <optional>) — 여러 블록을 받습니다. 각 블록은 ACME 프로토콜을 사용해 PKI 외부 CA 마운트의 인증서 수명주기를 자동화합니다.
exec (exec: <optional>) — env_template 스탠자를 통해 시크릿을 환경 변수로 주입하는 하위 프로세스를 실행하기 위한 옵션을 지정합니다.
env_template (env_template: <optional>) — 여러 블록을 받습니다. 각 블록은 프로세스 슈퍼바이저 모드를 통해 Vault 시크릿을 환경 변수로 템플릿화하는 옵션을 담습니다.
telemetry (telemetry: <optional>) — 텔레메트리 보고 시스템을 지정합니다. Agent 특유의 메트릭 목록은 아래 telemetry 스탠자 섹션을 참조하세요.
log_level — -log-level 커맨드라인 플래그와 동일합니다.

팁

SIGHUP(kill -SIGHUP $(pidof vault)) 신호 시 Vault Agent는 로그 레벨을 구성 파일이 지정한 값으로 갱신합니다(CLI 또는 환경 변수로 설정된 값까지 덮어씁니다).
log_format — -log-format 커맨드라인 플래그와 동일합니다.
log_file — -log-file 커맨드라인 플래그와 동일합니다.
log_rotate_duration — -log-rotate-duration 커맨드라인 플래그와 동일합니다.
log_rotate_bytes — -log-rotate-bytes 커맨드라인 플래그와 동일합니다.
log_rotate_max_files — -log-rotate-max-files 커맨드라인 플래그와 동일합니다.

vault 스탠자

최상위 vault 블록은 많아야 하나이며, 다음 구성 항목을 가집니다.

address (string: <optional>) — 연결할 Vault 서버의 주소입니다. FQDN(정규화된 도메인 이름) 또는 IP여야 하며, 예를 들어 https://vault-fqdn:8200 또는 https://172.16.9.8:8200입니다. 이 값은 VAULT_ADDR 환경 변수를 설정해 덮어쓸 수 있습니다.
ca_cert (string: <optional>) — Vault 서버의 SSL 인증서를 검증할 단일 PEM 인코딩 CA 인증서의 로컬 디스크 경로입니다. 이 값은 VAULT_CACERT 환경 변수를 설정해 덮어쓸 수 있습니다.
ca_path (string: <optional>) — Vault 서버의 SSL 인증서를 검증할 PEM 인코딩 CA 인증서 디렉토리의 로컬 디스크 경로입니다. 이 값은 VAULT_CAPATH 환경 변수를 설정해 덮어쓸 수 있습니다.
client_cert (string: <optional>) — Vault 서버에 대한 TLS 인증에 사용할 단일 PEM 인코딩 CA 인증서의 로컬 디스크 경로입니다. 이 값은 VAULT_CLIENT_CERT 환경 변수를 설정해 덮어쓸 수 있습니다.
client_key (string: <optional>) — client_cert의 클라이언트 인증서와 일치하는 단일 PEM 인코딩 개인 키의 로컬 디스크 경로입니다. 이 값은 VAULT_CLIENT_KEY 환경 변수를 설정해 덮어쓸 수 있습니다.
tls_skip_verify (string: <optional>) — TLS 인증서 검증을 비활성화합니다. 이 옵션은 Vault 서버와 주고받는 데이터 전송의 보안을 낮추므로 사용을 강력히 권장하지 않습니다. 이 값은 VAULT_SKIP_VERIFY 환경 변수를 설정해 덮어쓸 수 있습니다.
tls_server_name (string: <optional>) — TLS로 연결할 때 SNI 호스트로 사용할 이름입니다. 이 값은 VAULT_TLS_SERVER_NAME 환경 변수를 설정해 덮어쓸 수 있습니다.
namespace (string: <optional>) — Vault Agent가 Vault에 보내는 모든 요청에 사용할 네임스페이스입니다. 커맨드라인이나 환경 변수로도 지정할 수 있습니다. 우선 순위는 낮은 것부터: 이 설정, 그 다음 환경 변수 VAULT_NAMESPACE, 마지막으로 가장 높은 우선 순위의 커맨드라인 옵션 -namespace입니다. 이 중 아무것도 지정하지 않으면 루트 네임스페이스로 기본 설정됩니다.

retry 스탠자

vault 스탠자는 실패한 Vault 요청을 어떻게 처리할지를 제어하는 retry 스탠자를 포함할 수 있습니다. 이 요청은 템플릿을 렌더링하기 위해 발행된 것이거나, API 프록시 하위 시스템에서 온 프록시된 요청일 수 있습니다. 반면 Auto-auth는 자체적인 재시도 개념을 가지며 이 섹션의 영향을 받지 않습니다.

템플릿 엔진의 요청에 대해 Vault Agent는 모든 재시도를 소진하면 재시도 카운터를 리셋하고 다시 재시도합니다. 즉, template_config 스탠자의 exit_on_retry_failure가 true로 설정되지 않는 한 템플릿화는 실패 시 무한히 재시도합니다.

다음은 retry 스탠자의 옵션입니다.

num_retries (int: 12) — 실패한 요청을 몇 번 재시도할지 지정합니다. 0 값은 기본값, 즉 12회 재시도를 의미합니다. -1 값은 재시도를 비활성화합니다. VAULT_MAX_RETRIES 환경 변수가 이 설정을 덮어씁니다.

여기 몇 가지 주의할 미묘한 점이 있습니다. 첫째, 프록시 캐시에서 시작된 요청은 특정 HTTP 결과 코드가 발생한 경우에만 재시도됩니다. 501("not implemented")을 제외한 모든 50x 코드와 412("precondition failed")가 여기에 해당합니다. 412는 Vault Enterprise 1.7+에서 결과적 일관성으로 인한 오래된 읽기(stale read)를 나타내는 데 사용됩니다. 템플릿 하위 시스템에서 온 요청은 실패와 관계없이 재시도됩니다.

둘째, Vault Agent 영구 캐시가 활성화되어 있으면 템플릿 재시도는 템플릿 엔진과 캐시 프록시 양쪽에서 수행될 수 있습니다. 이는 영구성이 활성화될 때 템플릿 요청이 캐시 프록시를 거치기 때문입니다.

셋째, 재시도 사이의 시간을 정하는 백오프(backoff) 알고리즘은 템플릿과 캐시 하위 시스템에서 다릅니다. 이는 향후 해결하고자 하는 기술적 제한입니다.

listener 스탠자

Vault Agent는 하나 이상의 listener 스탠자를 지원합니다. 리스너는 캐싱의 유무와 관계없이 구성할 수 있지만, 캐시가 구성되어 있으면 이를 사용하고 API 프록시를 활성화합니다. 표준 리스너 구성 외에도 Agent의 리스너 구성은 다음을 지원합니다.

require_request_header (bool: false) — 이 리스너의 모든 들어오는 HTTP 요청이 X-Vault-Request: true 헤더 항목을 가져야 합니다. 이 옵션을 사용하면 SSRF(Server Side Request Forgery) 공격으로부터 추가 보호 계층을 제공합니다. 적절한 X-Vault-Request 헤더가 없는 리스너의 요청은 HTTP 응답 상태 코드 412: Precondition Failed와 함께 실패합니다.
role (string: default) — role은 리스너가 서빙할 API를 결정합니다. 메트릭만 제공하도록 metrics_only로 구성하거나, 모든 것(메트릭 포함)을 제공하는 기본 역할인 default로 구성할 수 있습니다. require_request_header는 metrics_only 리스너에는 적용되지 않습니다.
agent_api (agent_api: <optional>) — 선택적 Agent API 엔드포인트를 관리합니다.

agent_api 스탠자

enable_quit (bool: false) — true로 설정하면 에이전트가 quit API를 활성화합니다.

telemetry 스탠자

Vault Agent는 telemetry 스탠자를 지원하며 성능, auto-auth 및 캐시 상태에 대한 다양한 런타임 메트릭을 수집합니다.

Metric	Description	Type
`vault.agent.authenticated`	현재 인증 상태(1 - 유효한 토큰 보유, 0 - 유효한 토큰 없음)	gauge
`vault.agent.auth.failure`	인증 실패 횟수	counter
`vault.agent.auth.success`	인증 성공 횟수	counter
`vault.agent.proxy.success`	성공적으로 프록시된 요청 수	counter
`vault.agent.proxy.client_error`	Vault가 오류를 반환한 요청 수	counter
`vault.agent.proxy.error`	에이전트가 프록시하지 못한 요청 수	counter
`vault.agent.cache.hit`	캐시 히트 수	counter
`vault.agent.cache.miss`	캐시 미스 수	counter

중요: `VAULT_ADDR` 사용

Vault Agent 인스턴스에서 VAULT_ADDR 환경 변수를 export하면 그 값이 구성 파일의 값보다 우선합니다. Vault Agent는 그 값을 사용해 Vault에 연결하는데, 이로 인해 VAULT_ADDR 값이 연결에 사용되고 Vault Agent가 서버 대신 자신에게 연결하려고 하는 무한 루프가 생길 수 있습니다.

연결이 실패하면 Vault Agent는 포트를 늘려 다시 시도합니다. 에이전트는 이 시도를 반복해 포트 고갈(port exhaustion)로 이어집니다.

이 문제는 Vault 주소를 구성하는 3가지 방식의 우선 순위 때문입니다. 우선 순위가 낮은 순서대로:

구성 파일
환경 변수
CLI 플래그

Vault Agent 시작하기

Vault Agent를 실행하려면:

클라이언트 애플리케이션이 실행되는 곳(가상 머신, Kubernetes 팟 등)에 Vault 바이너리를 다운로드합니다.
Vault Agent 구성 파일을 만듭니다.(예시 구성 섹션 참조)
구성 파일로 Vault Agent를 시작합니다.

예시:
```
$ vault agent -config=/etc/vault/agent-config.hcl
```
도움말을 보려면 다음을 실행하세요.
```
$ vault agent -h
```

Vault와 마찬가지로 -config 플래그는 세 가지 방식으로 사용할 수 있습니다.

플래그를 한 번 사용해 단일 특정 구성 파일의 경로를 지정합니다.
플래그를 여러 번 사용해 여러 구성 파일을 지정하며, 런타임에 합성됩니다.
플래그를 사용해 구성 파일 디렉토리를 지정하며, 그 내용이 런타임에 합성됩니다.

예시 구성

아주 극단적으로 인위적인 값이 든 예시 구성은 다음과 같습니다.

pid_file = "./pidfile"

log_file = "/var/log/vault-agent.log"

vault {
  address = "https://vault-fqdn:8200"
  retry {
    num_retries = 5
  }
}

auto_auth {
  method "aws" {
    mount_path = "auth/aws-subaccount"
    config = {
      type = "iam"
      role = "foobar"
    }
  }

  sink "file" {
    config = {
      path = "/tmp/file-foo"
    }
  }

  sink "file" {
    wrap_ttl = "5m"
    aad_env_var = "TEST_AAD_ENV"
    dh_type = "curve25519"
    dh_path = "/tmp/file-foo-dhpath2"
    config = {
      path = "/tmp/file-bar"
    }
  }
}

cache {
  // An empty cache stanza still enables caching
}

template_config {
  static_secret_render_interval = "10m"
  exit_on_retry_failure = true
  max_connections_per_host = 20
}

template {
  source = "/etc/vault/server.key.ctmpl"
  destination = "/etc/vault/server.key"
}

template {
  source = "/etc/vault/server.crt.ctmpl"
  destination = "/etc/vault/server.crt"
}

Vault Agent란 무엇인가?