Vault Agent를 프로세스 슈퍼바이저 모드로 실행하기

Vault Agent의 프로세스 슈퍼바이저 모드(Process Supervisor Mode)를 사용하면 Consul Template 마크업을 사용해 Vault 시크릿을 환경 변수를 통해 프로세스에 주입할 수 있습니다.

애플리케이션을 Kubernetes 클러스터에서 실행 중이라면, 대신 Vault Secrets Operator와 Vault Agent Sidecar Injector를 평가해 보시길 권합니다.

출처: 문서

본문

기능 (Functionality)

Vault Agent는 env_template 구성 블록에서 참조하는 시크릿을 환경 변수로 주입해 exec 블록에 지정된 하위 프로세스에 전달합니다.

Vault Agent를 프로세스 슈퍼바이저 모드로 시작하면, 각 환경 변수 템플릿이 적어도 한 번 렌더링될 때까지 기다렸다가 프로세스를 시작합니다. restart_on_secret_changes가 always(기본값)로 설정되면, Agent는 주입된 시크릿에 대한 갱신이 감지될 때마다 프로세스를 재시작합니다. 이는 정적 시크릿 갱신(static_secret_render_interval에서 수행)이거나 만료에 가까워진 동적 시크릿일 수 있습니다.

여러 면에서 Vault Agent는 하위 프로세스를 미러링합니다. 표준 입력·출력 스트림(stdin/stdout/stderr)은 모두 하위 프로세스로 전달됩니다. 또한 Vault Agent는 하위 프로세스가 스스로 종료하면 같은 종료 코드로 함께 종료됩니다.

구성 (Configuration)

Agent의 generate-config 도구가 주어진 입력에서 유효한 에이전트 구성 파일을 생성해 시작을 도와줍니다.

프로세스 슈퍼바이저 모드는 env_template 블록이 하나 이상 있어야 하고, 최상위 exec 블록이 정확히 하나 있어야 합니다. 일반 파일 template 엔트리와는 호환되지 않습니다.

`env_template`

env_template 스탠자는 contents 필드에 지정되거나 source 필드에서 참조되는 템플릿을 스탠자 제목의 환경 변수 이름에 매핑합니다. 파일 템플릿과 같은 템플릿 언어를 사용하지만, 그 구성 파라미터의 일부만 허용합니다.

환경 변수 이름 (string: <required>) — 템플릿 내용이 매핑되어야 하는 환경 변수의 이름입니다.
contents (string: "") — 템플릿 파일의 source 경로를 제공하는 대신 템플릿의 내용을 구성 파일에 직접 포함할 수 있게 해 줍니다. 짧은 템플릿에 유용합니다. 이 옵션은 source 옵션과 상호 배타적입니다.
source (string: "") — 입력 템플릿으로 사용할 디스크 경로입니다. contents 옵션을 사용하지 않으면 이 옵션이 필요합니다.
error_on_missing_key (bool: false) — 존재하지 않는 구조체나 맵 필드/키에 접근할 때 오류와 함께 종료합니다. 기본 동작은 존재하지 않는 필드에 접근할 때 <no value>를 출력하는 것입니다. 이 값을 "true"로 설정할 것을 적극 권장합니다. 또한 전역 Vault Agent Template Config의 exit_on_retry_failure를 참조하세요.
left_delimiter (string: "{{") — 템플릿에서 사용할 구분자입니다. 기본값은 "{{"이지만, 일부 템플릿에서는 출력 파일 자체와 충돌하지 않는 다른 구분자를 사용하는 것이 더 쉬울 수 있습니다.
right_delimiter (string: "}}") — 템플릿에서 사용할 구분자입니다. 기본값은 "}}"이지만, 일부 템플릿에서는 출력 파일 자체와 충돌하지 않는 다른 구분자를 사용하는 것이 더 쉬울 수 있습니다.

`exec`

최상위 exec 블록에는 다음과 같은 구성 항목이 있습니다.

command (string array: required) — 선택적 인자와 함께 하위 프로세스의 명령을 지정합니다. 실행 파일의 경로는 절대 경로이거나 현재 작업 디렉토리에 상대적이어야 합니다.
restart_on_secret_changes (string: "always") — 시크릿 변경 시 에이전트가 하위 프로세스를 재시작할지 제어합니다. 이 구성과 관련된 시크릿 변경에는 두 가지 유형이 있습니다. 정적 시크릿 갱신(static_secret_render_interval)과 만료에 가까워진 동적 시크릿입니다. 이 구성은 always와 never 두 옵션을 지원합니다.
restart_stop_signal (string: "SIGTERM") — 시크릿이 갱신되고 프로세스를 재시작해야 할 때 하위 프로세스에 보내는 신호입니다. 이 신호가 보내진 후 30초가 지나면 하위 프로세스를 강제로 멈추기 위해 SIGKILL이 보내집니다.

구성 예시

다음 예시는 구성 도우미 도구인 vault agent generate-config로 생성된 것입니다. 이 구성이 주어지면 Vault Agent는 (./my-app arg1 arg2) 하위 프로세스를 Vault의 시크릿으로 채워진 두 개의 추가 환경 변수(FOO_USER와 FOO_PASSWORD)와 함께 실행합니다.

auto_auth {

  method {
    type = "token_file"

    config {
      token_file_path = "/Users/avean/.vault-token"
    }
  }
}

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

vault {
  address = "http://localhost:8200"
}

env_template "FOO_PASSWORD" {
  contents             = "{{ with secret \"secret/data/foo\" }}{{ .Data.data.password }}{{ end }}"
  error_on_missing_key = true
}
env_template "FOO_USER" {
  contents             = "{{ with secret \"secret/data/foo\" }}{{ .Data.data.user }}{{ end }}"
  error_on_missing_key = true
}

exec {
  command                   = ["./my-app", "arg1", "arg2"]
  restart_on_secret_changes = "always"
  restart_stop_signal       = "SIGTERM"
}

튜토리얼

엔드투엔드 예시는 Vault Agent - 환경 변수로 시크릿 처리 튜토리얼을 참조하세요.

Vault Agent를 프로세스 슈퍼바이저 모드로 실행하기