자동 자격 증명 회전 개요

Enterprise

적절한 Vault Enterprise 라이선스 또는 HCP Vault Dedicated 클러스터가 필요합니다.

Vault Enterprise는 일정 기반 또는 주기 기반의 자격 증명 회전을 자동화하는 중앙 집중식 시스템을 제공합니다. Vault는 주기적으로 대기 중인 회전을 평가하고 적절한 플러그인에 요청을 전달합니다.

실패 처리

회전 시도가 회전 정책(rotation policy)에 정의된 최대 재시도 한도를 초과하면 Vault는 해당 항목을 고아(orphaned) 상태로 표시합니다. 이 상태는 안전 메커니즘 역할을 합니다.

자동화 중단: 루프나 서비스 저하를 방지하기 위해 추가 자동 회전 시도가 일시 중지됩니다.
개입 필요: 근본 오류를 해결하고 자격 증명을 건강한 상태로 복원하려면 수동 문제 해결이 필요합니다.

자세한 복구 단계는 회전 고아 처리 문서를 참고하세요.

고가용성

자동 회전은 클러스터의 활성 노드에서만 실행됩니다. 리더십 변경이 발생하면 새 활성 노드가 저장소에서 회전 상태를 자동으로 복원하고 이전 노드가 중단한 지점부터 회전 처리를 재개합니다.

복제된 클러스터의 경우:

공유 마운트: 회전은 기본(primary) 클러스터의 활성 노드에서 발생합니다.
로컬 마운트: 회전은 각 클러스터의 활성 노드에서 독립적으로 발생합니다.

지수 백오프(Exponential backoff)

회전이 실패하면 Vault Enterprise는 지수 백오프 일정으로 회전 항목을 다시 대기열에 넣어, 시스템에 부담을 주는 지속적인 고빈도 재시도를 방지합니다. 백오프 일정에는 부하 분산을 더 고르게 만드는 무작위 요소(지터, jitter)도 포함됩니다. 백오프 일정은 3가지 요소로 구성됩니다.

초기 지연 — 첫 번째 재시도 시도가 짧은 최소 대기 시간 후에 예약됩니다.
배가 간격 — 이후 지연은 이전 간격을 기반으로 지수적으로 증가하며, 지터가 적용되어 재시도 시도를 더욱 분산시킵니다.
최대 상한 — Vault는 단일 재시도에 대한 지연의 상한을 적용합니다. 이 상한에 도달하면 이후 시도는 회전이 성공하거나 항목이 고아 처리될 때까지 그 고정된 간격으로 계속됩니다.

정책 중심(Policy-driven)

Vault Enterprise는 주어진 예약된 회전에 대한 재시도 동작을 정의하는 회전 정책 설정을 지원합니다. 회전 정책을 구성하는 방법과 Vault의 재시도 동작에 미치는 영향에 대한 자세한 내용은 회전 정책 문서를 읽어 보세요. API 문서에도 회전 정책 관리에 대한 세부 정보가 포함되어 있습니다.

회전 상태 확인하기

플러그인에서 역할 또는 자격 증명을 읽어 회전 상태를 확인합니다. 응답에는 이 상태와 다음 예약된 회전을 파악하는 데 도움이 되는 세 가지 주요 필드가 포함됩니다.

last_vault_rotation 필드는 Vault가 수행한 마지막 성공적인 회전의 타임스탬프입니다. 자동 회전이 성공할 때와 예약된 회전 사이에 수동 회전이 발생할 때 모두 갱신됩니다.
next_vault_rotation 필드는 다음 예약된 자동 회전의 타임스탬프입니다. 이 필드는 수동 회전이 성공해도 갱신되지 않습니다. 왜냐하면 다음 예약된 회전이 여전히 원래 예정된 시간에 발생하기 때문입니다.
ttl 필드는 다음 예약된 회전이 시작되기까지 남은 시간(초)입니다. 이 필드는 next_vault_rotation 필드와 같은 이유로 갱신되지 않습니다.

예를 들어, LDAP 정적 역할 자격 증명을 읽으면 다음 정보가 포함될 수 있습니다.

$ vault read ldap/static-cred/my-role

Key                            Value
---                            -----
last_vault_rotation    2026-04-02T23:30:00Z
next_vault_rotation    2026-04-03T11:30:00Z
ttl                    84600
...

문제 해결

Vault Enterprise는 성공적인 회전, 회전 실패, 재시도 시도, 고아 처리 같은 회전 활동을 Vault 서버 로그에 기록합니다. Vault는 로그 문에 회전되는 자격 증명을 식별하는 메타데이터와 실패 경우의 오류 정보를 포함합니다. 예를 들어:

[INFO]  rotation-job-manager: successfully rotated job: rotationID=database/config/my-database
[ERROR] rotation-job-manager: rotation failed, attempting to re-queue: rotationID=database/config/my-database error="connection refused"
[ERROR] rotation-job-manager: orphaning item, please re-register after resolving the error: rotationID=database/config/my-database

레거시 회전 시스템에서의 마이그레이션

경고 — 일부 플러그인은 원래 독립적인 회전 시스템으로 설계되었지만, Vault 업데이트가 이를 중앙 집중식 자동 회전 프레임워크로 전환할 수 있습니다. 플러그인에 대해 이 전환이 활성화되는 업그레이드 후 Vault Enterprise를 처음으로 봉인 해제(seal 해제)하면, Vault는 기존의 모든 회전 항목을 새 시스템으로 자동 마이그레이션합니다.

전체 마이그레이션 과정을 주어진 플러그인의 정적 마이그레이션 엔드포인트를 통해 모니터링하는 것을 권장합니다. 예를 들어, LDAP 시크릿 엔진 정적 역할 마이그레이션은 /static-migration 엔드포인트를 사용합니다.

마이그레이션 과정은 백그라운드에서 실행되며 플러그인의 일반적인 운영을 방해하지 않습니다. Vault는 역할이 마이그레이션될 때까지 개별 정적 역할 회전을 일시 중지합니다. 역할이 마이그레이션되면 정상 회전 일정이 재개됩니다.

지원되는 플러그인에는 전용 모니터링 엔드포인트가 있습니다. 마이그레이션 과정 관리에 대한 자세한 내용은 개별 플러그인 API 문서를 참고하세요.

출처: 문서