Vault Agent 캐싱 개요

Vault Agent 캐싱은 새로 생성된 토큰을 담은 응답과, 이 새로 생성된 토큰에서 파생된 임대 시크릿을 담은 응답의 클라이언트 측 캐싱을 지원합니다. 캐시된 토큰과 임대의 갱신도 에이전트가 관리합니다.

정적 시크릿 캐싱에는 Vault Proxy 사용하기

정적 시크릿 캐싱(KVv1 및 KVv2)과 API 프록시를 함께 쓰면 Vault로 전달되는 요청 수를 최소화할 수 있습니다. Vault Agent는 API 프록시와 함께 정적 시크릿 캐싱을 지원하지 않습니다. API 프록시 관련 워크플로우에는 Vault Proxy를 사용하시길 권합니다.

출처: 문서

본문

캐싱과 갱신

응답 캐싱과 갱신은 다음 특정 시나리오에서만 에이전트가 관리합니다.

토큰 생성 요청이 에이전트를 통해 이루어집니다. 즉 다양한 인증 방법을 사용해 수행된 로그인 작업과, 에이전트를 통한 토큰 인증 방법의 토큰 생성 엔드포인트 호출은 응답이 에이전트에 캐시됩니다. 새 토큰을 담은 응답은 부모 토큰이 이미 에이전트에 의해 관리되고 있거나, 새 토큰이 고아(orphan) 토큰인 경우에만 캐시됩니다.
이미 에이전트가 관리하는 토큰을 사용해 에이전트를 통해 임대 시크릿 생성 요청이 이루어집니다. 즉 에이전트가 관리하는 토큰으로 발급된 모든 동적 자격 증명은 캐시되고 그 갱신도 처리됩니다.

영구 캐시 (Persistent cache)

Vault Agent는 이전 Vault Agent 프로세스가 만든 영구 캐시 파일에서 토큰과 임대를 복원할 수 있습니다.

이 기능에 대한 자세한 내용은 Vault Agent 영구 캐싱 페이지를 참조하세요.

캐시 퇴출 (Cache evictions)

시크릿과 관련된 캐시 엔트리의 퇴출은 에이전트가 더 이상 이를 갱신할 수 없을 때 발생합니다. 이는 시크릿이 최대 TTL에 도달했거나 갱신이 오류를 일으킬 때 일어날 수 있습니다.

에이전트는 특정 요청 유형과 응답 코드를 관찰해 최선 노력(best-effort)으로 캐시를 퇴출합니다. 예를 들어 토큰 폐기 요청이 에이전트를 통해 이루어지고 Vault 서버로의 전달 요청이 성공하면, 에이전트는 폐기된 토큰과 연결된 모든 캐시 엔트리를 퇴출합니다. 마찬가지로 임대 폐기 작업도 에이전트가 가로채며 해당 캐시 엔트리가 퇴출됩니다.

에이전트가 시크릿 만료와 폐기 요청 가로채기에 따라 캐시 엔트리를 퇴출하지만, 클라이언트가 Vault 서버와 직접 상호작용해 발생하는 폐기를 에이전트가 완전히 인지하지 못할 수 있습니다. 이는 오래된(stale) 캐시 엔트리로 이어질 수 있습니다. 캐시의 오래된 엔트리를 관리하기 위해 /agent/v1/cache-clear(아래 참조) 엔드포인트가 제공되며, 이를 사용해 캐시 엔트리를 색인하는 데 쓰이는 일부 쿼리 기준에 따라 캐시 엔트리를 수동으로 퇴출할 수 있습니다.

요청 고유성 (Request uniqueness)

반복 요청을 감지하고 캐시된 응답을 반환하려면 Agent가 요청을 고유하게 식별할 방법이 필요합니다. 현재 이 계산은 HTTP 요청을 모든 헤더와 요청 본문과 함께 직렬화·해싱하는 단순한 방식(향후 변경될 수 있음)을 취합니다. 이 해시 값은 응답을 즉시 사용할 수 있는지 캐시에서 확인하기 위한 인덱스로 사용됩니다. 이 방식의 결과로 요청의 어떤 데이터가 변경되면 모든 요청의 해시 값이 달라집니다. 예를 들어 요청 파라미터의 순서가 바뀌면 오탐(false negative)이 발생하는 부작용이 있습니다. 요청이 변경 없이 들어오는 한 캐싱 동작은 일관되어야 합니다. 값의 순서가 다르게 된 동일한 요청은 중복 캐시 엔트리를 만듭니다. 클라이언트가 일관된 메커니즘으로 요청을 만들어 각 요청마다 일관된 해시 값이 나올 것이라는 휴리스틱 가정이 캐싱 기능이 구축된 바탕입니다.

갱신 관리 (Renewal management)

토큰과 임대는 Vault 서버의 Go API를 통해 제공되는 시크릿 리뉴어(renewer)를 사용해 에이전트가 갱신합니다. Agent는 모든 작업을 메모리에서 수행하고 어떤 것도 스토리지에 영속화하지 않습니다. 즉 에이전트가 종료되면 모든 갱신 작업이 즉시 종료되며, 이후 에이전트가 갱신을 재개할 방법이 없습니다. 에이전트 종료가 시크릿의 폐기를 의미하는 것은 아니며, 단지 모든 유효한 비폐기 시크릿에 대한 갱신 책임을 Vault agent가 더 이상 수행하지 않음을 의미합니다.

Agent CLI

Agent의 리스너 주소는 CLI가 VAULT_AGENT_ADDR 환경 변수를 통해 가져옵니다. 이 값은 "http://127.0.0.1:8200" 같은 완전한 URL이어야 합니다.

API

캐시 지우기 (Cache clear)

이 엔드포인트는 주어진 기준에 따라 캐시를 지웁니다. 이 API를 사용하려면 에이전트가 값을 캐시하는 방식을 사전에 알아야 합니다. 에이전트에 캐시된 각 응답은 요청 유형에 따라 일부 요인으로 색인됩니다. 그 요인은 캐시된 응답에 속한 token, 응답에 속한 토큰의 token_accessor, 캐시된 응답을 만든 request_path, 응답에 붙은 lease, 응답이 속한 namespace 등입니다. 이 API는 연결된 캐시 엔트리를 가져와 퇴출하는 몇 가지 요인을 노출합니다. 캐싱이 활성화되지 않은 리스너의 경우 이 API는 여전히 사용 가능하지만 아무 것도 하지 않으며(지울 캐시가 없음) 200 응답을 반환합니다.

Method	Path	Produces
`POST`	`/agent/v1/cache-clear`	`200 application/json`

파라미터

type (strings: required) — 퇴출할 캐시 엔트리 유형입니다. 유효한 값은 request_path, lease, token, token_accessor, all입니다. type이 all로 설정되면 전체 캐시가 지워집니다.
value (string: required) — 선택한 type에 대한 정확한 값 또는 값의 프리픽스입니다. type이 all로 설정된 경우 이 파라미터는 선택적입니다.
namespace (string: optional) — type이 request_path로 설정된 경우에만 적용됩니다. 주어진 요청 경로에 대해 퇴출할 캐시 엔트리가 속한 네임스페이스입니다.

샘플 페이로드

{
  "type": "token",
  "value": "hvs.rlNjegSKykWcplOkwsjd8bP9"
}

샘플 요청

$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:1234/agent/v1/cache-clear

구성 (`cache`)

최상위 cache 블록이 어떤 방식으로든(빈 cache 블록 포함) 존재하면 캐시가 활성화됩니다. 최상위 cache 블록에는 다음과 같은 구성 항목이 있습니다.

persist (object: optional) — 영구 캐시에 대한 구성입니다.

cache 블록은 또한 하위 호환성을 유지하기 위한 목적으로만 api_proxy 블록의 use_auto_auth_token, enforce_consistency, when_inconsistent 구성 값(API 프록시 문서에 설명)을 지원합니다. 이 구성은 api_proxy의 해당 값과 함께 지정할 수 없으며, api_proxy 블록에서 설정하는 것보다 선호되어서는 안 되고, api_proxy가 이 값들을 구성하는 데 선호되는 장소입니다.

참고: cache 블록이 정의되면 구성에 template 또는 listener도 하나 이상 정의되어야 합니다. 그렇지 않으면 캐시를 활용할 방법이 없습니다.

구성 (Persist)

다음은 persist 블록 안에 있는 공통 구성 값입니다.

type (string: required) — 사용할 영구 캐시의 유형입니다. 예: kubernetes. 참고: HCL을 사용할 때는 이를 블록의 키로 사용할 수 있습니다(예: persist "kubernetes" {...}). 현재는 kubernetes만 지원됩니다.
path (string: required) — 영구 캐시 파일을 만들거나 복원할 디스크 경로입니다.
keep_after_import (bool: optional) — true로 설정하면 복원된 캐시 파일이 삭제되지 않습니다. 기본값은 false입니다.
exit_on_err (bool: optional) — true로 설정하면 영구 캐시 복원 중 오류가 발생하면 Vault Agent가 오류와 함께 종료합니다. 기본값은 true입니다.
service_account_token_file (string: optional) — type이 kubernetes로 설정되면, Kubernetes 서비스 계정 토큰이 있는 디스크 경로를 구성합니다. 기본값은 /var/run/secrets/kubernetes.io/serviceaccount/token입니다.

구성 (`listener`)

listener (array of objects: required) — 리스너에 대한 구성입니다.

최상위에 하나 이상의 listener 블록이 있을 수 있습니다. 리스너를 추가하면 API 프록시가 활성화되고, 구성되어 있으면 API 프록시가 캐시를 사용할 수 있게 됩니다. 이 구성 값들은 tcp와 unix 리스너 블록 모두에 공통입니다. tcp 유형의 블록은 표준 tcp listener 옵션을 지원합니다. 또한 listener 블록의 최상위 일부로 role 문자열 옵션을 사용할 수 있으며, 메트릭만 제공하도록 metrics_only로 구성하거나 모든 것(메트릭 포함)을 제공하는 기본 역할인 default로 구성할 수 있습니다.

type (string: required) — 사용할 리스너의 유형입니다. 유효한 값은 tcp와 unix입니다. 참고: HCL을 사용할 때는 이를 블록의 키로 사용할 수 있습니다(예: listener "tcp" {...}).
address (string: required) — 리스너가 듣는 주소입니다. tcp를 사용하면 URL 경로이고 unix를 사용하면 파일 경로일 수 있습니다. 예를 들어 127.0.0.1:8200 또는 /path/to/socket입니다. 기본값은 127.0.0.1:8200입니다.
tls_disable (bool: false) — TLS를 비활성화할지 지정합니다.
tls_key_file (string: optional) — 인증서의 개인 키 경로를 지정합니다.
tls_cert_file (string: optional) — TLS용 인증서 경로를 지정합니다.

예시 구성

선택적 persist 블록, 일반 리스너, 메트릭만 제공하는 리스너가 함께 있는 캐시 구성의 예시입니다.

# Other Vault agent configuration blocks
# ...

cache {
    persist = {
        type = "kubernetes"
        path = "/vault/agent-cache/"
        keep_after_import = true
        exit_on_err = true
        service_account_token_file = "/tmp/serviceaccount/token"
    }
}

listener "tcp" {
    address = "127.0.0.1:8100"
    tls_disable = true
}

listener "tcp" {
    address = "127.0.0.1:3000"
    tls_disable = true
    role = "metrics_only"
}

튜토리얼

Vault Agent 캐싱 튜토리얼을 참조해 캐싱 기능으로 Vault Agent를 사용해 클라이언트에 토큰·시크릿의 가용성을 높이는 방법을 배워보세요.

Vault Agent 캐싱 개요