Agent Injector 어노테이션

Agent Injector 어노테이션 (Injector annotations)

Vault Agent Injector가 사용하는 사용 가능한 어노테이션들을 "agent"와 "vault" 두 섹션으로 정리합니다.

출처: 문서

본문

다음은 injector에 사용할 수 있는 어노테이션이에요. 이 어노테이션들은 agent와 vault 두 섹션으로 구성됩니다. 아래 모든 어노테이션은 파드에 주입된 Vault Agent 컨테이너의 구성을 변경합니다.

Agent 어노테이션

Agent 어노테이션은 Vault Agent 컨테이너의 템플릿 구성을 변경해요. 예를 들어 agent 어노테이션으로 원하는 시크릿, 렌더링 방식, 선택적 실행 명령 등을 정의할 수 있습니다.

  • vault.hashicorp.com/agent-inject — 파드에 대해 주입이 명시적으로 활성화·비활성화되는지 구성. true 또는 false 값이어야 해요. 기본값 false.
  • vault.hashicorp.com/agent-inject-status — 성공적인 변경 후 파드에 injected 값을 추가해 추가 변경을 차단.
  • vault.hashicorp.com/agent-configmap — Vault Agent 구성 파일과 템플릿을 찾을 수 있는 설정 맵의 이름.
  • vault.hashicorp.com/agent-image — 사용할 Vault docker 이미지 이름. 이 값은 injector에 구성된 기본 이미지를 오버라이드하며 보통 필요하지 않아요. 기본값 hashicorp/vault:1.21.4.
  • vault.hashicorp.com/agent-init-first — true이면 Vault Agent init 컨테이너를 먼저 실행하도록 구성(false이면 마지막). 다른 init 컨테이너가 미리 채워진 시크릿이 필요할 때 유용해요. true 또는 false 값이어야 함. 기본값 false.
  • vault.hashicorp.com/agent-inject-command — 템플릿이 렌더링된 후 Vault Agent가 명령을 실행하도록 구성. 명령을 특정 시크릿에 매핑하려면 같은 고유 시크릿 이름을 사용: vault.hashicorp.com/agent-inject-command-SECRET-NAME. 예를 들어 시크릿 어노테이션 vault.hashicorp.com/agent-inject-secret-foobar를 구성했다면 vault.hashicorp.com/agent-inject-command-foobar가 그 시크릿에 명령을 매핑합니다.
  • vault.hashicorp.com/agent-inject-secret — 컨테이너가 필요로 하는 시크릿을 Vault Agent가 Vault에서 가져오도록 구성. 시크릿 이름은 vault.hashicorp.com/agent-inject-secret- 뒤의 고유 문자열(예: vault.hashicorp.com/agent-inject-secret-foobar)이에요. 값은 시크릿이 있는 Vault의 경로입니다.
  • vault.hashicorp.com/agent-inject-template — 시크릿 렌더링에 Vault Agent가 사용해야 하는 템플릿 구성. 템플릿 이름은 vault.hashicorp.com/agent-inject-template- 뒤의 고유 문자열(예: vault.hashicorp.com/agent-inject-template-foobar)이에요. vault.hashicorp.com/agent-inject-secret-에 제공된 것과 같은 고유 값에 매핑해야 합니다. 제공하지 않으면 기본 일반 템플릿이 사용돼요.
  • vault.hashicorp.com/agent-template-left-delim — 시크릿 템플릿 렌더링 시 Vault Agent가 사용할 왼쪽 구분자(delimiter) 구성. 템플릿 이름은 vault.hashicorp.com/agent-template-left-delim- 뒤의 고유 문자열이에요. vault.hashicorp.com/agent-inject-template-에 제공된 것과 같은 고유 값에 매핑합니다. 제공하지 않으면 Vault Agent Template Config가 정의한 기본 왼쪽 구분자가 사용돼요.
  • vault.hashicorp.com/agent-template-right-delim — 시크릿 템플릿 렌더링 시 Vault Agent가 사용할 오른쪽 구분자 구성. vault.hashicorp.com/agent-inject-template-에 제공된 것과 같은 고유 값에 매핑합니다. 제공하지 않으면 기본 오른쪽 구분자가 사용돼요.
  • vault.hashicorp.com/error-on-missing-key — 존재하지 않는 struct/map 필드·키에 접근할 때 Vault Agent가 오류와 함께 종료할지 구성. 시크릿 이름은 vault.hashicorp.com/error-on-missing-key- 뒤의 문자열이며 vault.hashicorp.com/agent-inject-secret-에 제공된 것과 같은 고유 값에 매핑합니다. 기본값 false. 자세한 내용은 Vault Agent Template Config 참고.
  • vault.hashicorp.com/agent-inject-containers — 시크릿 볼륨을 마운트할 컨테이너를 지정하는 쉼표 구분 목록. 제공하지 않으면 시크릿 볼륨이 파드의 모든 컨테이너에 마운트됩니다.
  • vault.hashicorp.com/secret-volume-path — 시크릿이 렌더링될 파일시스템 위치 구성. 특정 시크릿에 경로를 매핑하려면 같은 고유 시크릿 이름을 사용: vault.hashicorp.com/secret-volume-path-SECRET-NAME. 시크릿 이름이 없으면 파드에서 렌더링되는 모든 시크릿의 기본값을 설정합니다.
  • vault.hashicorp.com/agent-inject-file — Vault 시크릿이 기록될 시크릿 볼륨의 파일명·경로 구성. 지정된 경로에 메모리 볼륨을 마운트하는 vault.hashicorp.com/secret-volume-path와 함께 사용해야 해요. secret-volume-path를 사용하면 이 값에서 경로를 생략할 수 있습니다. 특정 시크릿에 파일명을 매핑하려면 같은 고유 시크릿 이름을 사용하세요.
  • vault.hashicorp.com/agent-inject-perms — 시크릿 볼륨에 만들 파일의 권한 구성. vault.hashicorp.com/agent-inject-perms- 뒤의 문자열이 시크릿 이름이며 vault.hashicorp.com/agent-inject-secret-의 고유 값과 일치해야 합니다. 값은 8진수 권한(예: 0644)입니다.
  • vault.hashicorp.com/agent-inject-template-file — 사용할 커스텀 템플릿의 경로·파일명 구성. 쿠버네티스 시크릿을 /vault/custom에 마운트하는 vault.hashicorp.com/extra-secret와 함께 사용해야 해요. 특정 시크릿에 템플릿 파일을 매핑하려면 같은 고유 시크릿 이름을 사용하세요.
  • vault.hashicorp.com/agent-inject-default-template — 커스텀 템플릿이 정의되지 않았을 때 시크릿 렌더링용 기본 템플릿 타입 구성. 가능한 값은 map과 json. 기본값 map.
  • vault.hashicorp.com/template-config-exit-on-retry-failure — 실패로 인해 템플릿 재시도 횟수를 모두 소진한 후 Vault Agent가 종료할지 제어. 기본값 true. 자세한 내용은 Vault Agent Template Config 참고.
  • vault.hashicorp.com/template-static-secret-render-interval — 지정 시 Vault Agent Template이 KV v2 같은 비리스(leased) 시크릿을 얼마나 자주 렌더링할지 구성. Vault Agent Template Config 참고.
  • vault.hashicorp.com/template-max-connections-per-host — 지정 시 특정 Vault 호스트에 대해 Vault Agent 템플릿 엔진이 사용할 수 있는 총 연결 수를 제한. 다이얼링·활성·유휴 상태의 모든 연결을 포함. Vault Agent Template Config 참고.
  • vault.hashicorp.com/template-lease-renewal-threshold — 지정 시 Vault Agent의 템플릿 엔진이 갱신할 수 없는 동적 리스를 새로 고칠 때까지 기다려야 하는 시간을 리스 기간의 분율(예: 0.9)로 구성. Vault Agent Template Config 참고.
  • vault.hashicorp.com/agent-extra-secret — 쿠버네티스 시크릿을 sidecar/init 컨테이너의 /vault/custom에 볼륨으로 마운트. approle 같은 auto-auth 방식으로 시크릿 경로가 필요해도 커스텀 Agent 구성을 만드는 데 유용.
  • vault.hashicorp.com/agent-inject-token — Vault Agent가 시크릿 볼륨 루트의 token이라는 파일(즉 /vault/secrets/token)로 Vault 토큰을 파드의 다른 컨테이너와 공유하도록 구성. 다른 컨테이너가 Vault와 직접 통신하지만 Vault Agent가 제공하는 자동 인증이 필요할 때 유용. true 또는 false 값. 기본값 false.
  • vault.hashicorp.com/agent-limits-cpu — Vault Agent 컨테이너의 CPU limit 구성. 기본값 500m. 빈 문자열로 설정하면 CPU limit 비활성화.
  • vault.hashicorp.com/agent-limits-mem — Vault Agent 컨테이너의 메모리 limit 구성. 기본값 128Mi. 빈 문자열이면 메모리 limit 비활성화.
  • vault.hashicorp.com/agent-limits-ephemeral — Vault Agent 컨테이너의 임시 스토리지 limit 구성. 기본값은 설정되지 않음(임시 스토리지 limit 비활성화). 모든 주입 Agent 컨테이너의 기본값을 설정하는 명령줄 옵션(-ephemeral-storage-limit)이나 환경 변수(AGENT_INJECT_EPHEMERAL_LIMIT)로도 사용 가능. 참고: 파드 limit은 모든 컨테이너 limit의 합계예요. 이 limit을 다른 컨테이너에 설정하지 않고 설정하면 파드의 다른 컨테이너 limit에도 영향을 줍니다. Kubernetes resources 문서 참고.
  • vault.hashicorp.com/agent-requests-cpu — Vault Agent 컨테이너의 CPU request 구성. 기본값 250m. 빈 문자열이면 CPU request 비활성화.
  • vault.hashicorp.com/agent-requests-mem — Vault Agent 컨테이너의 메모리 request 구성. 기본값 64Mi. 빈 문자열이면 메모리 request 비활성화.
  • vault.hashicorp.com/agent-requests-ephemeral — Vault Agent 컨테이너의 임시 스토리지 request 구성. 기본값은 설정되지 않음(임시 스토리지 request 비활성화, 설정되면 임시 limit으로 기본). 명령줄 옵션(-ephemeral-storage-request)이나 환경 변수(AGENT_INJECT_EPHEMERAL_REQUEST)로도 사용 가능. 참고: 파드 request은 모든 컨테이너 request의 합계예요.
  • vault.hashicorp.com/agent-revoke-on-shutdown — sidecar가 종료 전에 자신의 토큰을 폐기할지 구성. 이 설정은 Vault Agent sidecar 컨테이너에만 적용됩니다. true 또는 false 값. 기본값 false.
  • vault.hashicorp.com/agent-revoke-grace — 종료 전에 자신의 토큰을 폐기할 때의 유예 기간(초) 구성. 이 설정은 Vault Agent sidecar 컨테이너에만 적용됩니다. 기본값 5s.
  • vault.hashicorp.com/agent-pre-populate — 컨테이너 시작 전에 시크릿으로 공유 메모리 볼륨을 미리 채우는 init 컨테이너를 포함할지 구성. true 또는 false 값. 기본값 true.
  • vault.hashicorp.com/agent-pre-populate-only — init 컨테이너가 유일한 주입 컨테이너인지 구성. true이면 파드 런타임에 sidecar 컨테이너가 주입되지 않습니다. CronJob이나 Job 워크로드에 이 옵션을 활성화하는 것을 권장해 깨끗한 파드 종료를 보장합니다.
  • vault.hashicorp.com/preserve-secret-case — 시크릿 파일을 만들 때 Vault Agent가 시크릿 이름 대소문자를 보존하도록 구성. true 또는 false 값. 기본값 false.
  • vault.hashicorp.com/agent-run-as-user — Vault agent를 실행할 사용자(uid) 설정. injector용 명령줄 옵션(-run-as-user)이나 환경 변수(AGENT_INJECT_RUN_AS_USER)로도 사용 가능. 기본값 100.
  • vault.hashicorp.com/agent-run-as-group — Vault agent를 실행할 그룹(gid) 설정. 명령줄 옵션(-run-as-group)이나 환경 변수(AGENT_INJECT_RUN_AS_GROUP)로도 사용 가능. 기본값 1000.
  • vault.hashicorp.com/agent-set-security-context — 주입 컨테이너에 SecurityContext를 설정할지 제어. 명령줄 옵션(-set-security-context)이나 환경 변수(AGENT_INJECT_SET_SECURITY_CONTEXT)로도 사용 가능. 기본값 true.
  • vault.hashicorp.com/agent-run-as-same-user — 주입된 Vault agent 컨테이너를 파드의 첫 번째 애플리케이션 컨테이너의 User(uid)로 실행. 파드 스펙에 Spec.Containers[0].SecurityContext.RunAsUser가 설정되어 있어야 해요. 명령줄 옵션(-run-as-same-user)이나 환경 변수(AGENT_INJECT_RUN_AS_SAME_USER)로도 사용 가능. 기본값 false.

참고: 파드의 첫 번째 애플리케이션 컨테이너가 root(uid 0)로 실행 중이라면 run-as-same-user 어노테이션은 오류와 함께 주입을 실패시킵니다.

Vault 어노테이션

Vault 어노테이션은 Vault Agent 컨테이너가 Vault와 통신하는 방식을 변경해요. 예를 들어 Vault 주소, 사용할 TLS 인증서, 타임아웃 같은 클라이언트 파라미터 등을 다룹니다.

  • vault.hashicorp.com/auth-config — 구성된 인증 방식을 위한 추가 파라미터 구성. vault.hashicorp.com/auth-config- 뒤의 고유 문자열(예: vault.hashicorp.com/auth-config-role-id-file-path)이 구성 이름이에요. 이 어노테이션은 인증 방식의 여러 설정을 구성하기 위해 여러 번 재사용할 수 있어요. 일부 인증 방식은 추가 시크릿이 필요할 수 있으며 vault.hashicorp.com/agent-extra-secret 어노테이션으로 마운트해야 해요. 유효한 인증 구성 목록은 Vault Agent auto-auth 문서 참고.
  • vault.hashicorp.com/auth-path — 쿠버네티스 인증 방식의 인증 경로 구성. 기본값 auth/kubernetes.
  • vault.hashicorp.com/auth-type — Vault Agent의 인증 타입 구성. 기본값 kubernetes. 유효한 인증 방식 목록은 Vault Agent auto-auth 문서 참고.
  • vault.hashicorp.com/auth-min-backoff — auto-auth 구성의 min_backoff 옵션 설정. Vault 1.11+ 필요.
  • vault.hashicorp.com/auth-max-backoff — auto-auth 구성의 max_backoff 옵션 설정.
  • vault.hashicorp.com/agent-auto-auth-exit-on-err — auto-auth 구성의 exit_on_err 옵션 설정.
  • vault.hashicorp.com/ca-cert — Vault의 TLS를 검증하는 데 사용하는 CA 인증서 경로. PEM 인코딩 인증서·번들을 받는 AGENT_INJECT_VAULT_CACERT_BYTES 환경 변수로 모든 주입 Agent의 기본값으로도 설정할 수 있어요.
  • vault.hashicorp.com/ca-key — Vault의 TLS를 검증하는 데 사용하는 CA 공개 키 경로.
  • vault.hashicorp.com/client-cert — mTLS로 Vault와 통신할 때 사용하는 클라이언트 인증서 경로.
  • vault.hashicorp.com/client-key — mTLS로 Vault와 통신할 때 사용하는 클라이언트 공개 키 경로.
  • vault.hashicorp.com/client-max-retries — 특정 오류가 발생했을 때 Vault Agent 재시도 횟수 구성. 기본값 2(총 3회 시도). 0 이하로 설정하면 재시도 비활성화. 재시도되는 오류 코드는 412(클라이언트 일관성 요구사항 미충족)와 501(미구현)을 제외한 모든 5xx입니다.
  • vault.hashicorp.com/client-timeout — Vault와 통신할 때 Vault Agent의 요청 타임아웃 임계값(초) 구성. 기본값 60s이며 60, 60s, 1m 같은 값을 받아들입니다.
  • vault.hashicorp.com/log-level — Vault Agent 로그 수준의 세부 정도 구성. 기본값 info.
  • vault.hashicorp.com/log-format — Vault Agent의 로그 타입 구성. 가능한 값은 standard와 json. 기본값 standard.
  • vault.hashicorp.com/namespace — Vault에서 시크릿을 요청할 때 사용할 Vault Enterprise 네임스페이스 구성. 모든 주입 Agent의 기본 네임스페이스를 설정하는 명령줄 옵션(-vault-namespace)이나 환경 변수(AGENT_INJECT_VAULT_NAMESPACE)로도 사용 가능.
  • vault.hashicorp.com/proxy-address — Vault 서버에 연결할 때 사용할 HTTP 프록시 구성.
  • vault.hashicorp.com/role — Vault Agent auto-auth 방식이 사용하는 Vault 역할 구성. vault.hashicorp.com/agent-configmap이 설정되지 않았을 때 필수.
  • vault.hashicorp.com/service — 주입된 Vault Agent가 사용할 Vault 주소 구성. 이 값은 injector에 구성된 기본 Vault 주소를 오버라이드하며, injector와 같은 쿠버네티스 클러스터 안의 Vault 서비스 주소이거나 외부 Vault URL일 수 있어요.
  • vault.hashicorp.com/tls-secret — TLS 클라이언트·CA 인증서와 키를 담은 쿠버네티스 시크릿 이름. /vault/tls에 마운트됩니다.
  • vault.hashicorp.com/tls-server-name — TLS로 Vault와 통신할 때 서버의 진위를 검증할 Vault 서버 이름.
  • vault.hashicorp.com/tls-skip-verify — true이면 Vault의 TLS 인증서 검증을 건너뛰도록 Vault Agent 구성. 프로덕션 환경에서 true로 설정하는 것은 권장하지 않아요.
  • vault.hashicorp.com/agent-disable-idle-connections — 유휴 연결을 비활성화해야 하는 Vault Agent 기능 목록을 쉼표로 구분. 모든 주입 Agent의 기본값을 설정하는 명령줄 옵션(-disable-idle-connections)이나 환경 변수(AGENT_INJECT_DISABLE_IDLE_CONNECTIONS)로도 사용 가능.
  • vault.hashicorp.com/agent-disable-keep-alives — keep-alive를 비활성화해야 하는 Vault Agent 기능 목록을 쉼표로 구분. 명령줄 옵션(-disable-keep-alives)이나 환경 변수(AGENT_INJECT_DISABLE_KEEP_ALIVES)로도 사용 가능.

더 알아보기 (Learn more)