`operator raft` — 통합 래프트 스토리지 관리하기

이 명령어는 운영자(operator)가 통합 스토리지 래프트(Integrated Storage Raft) 백엔드를 관리하기 위한 하위 명령어들을 그룹으로 묶은 명령어예요.

Usage: vault operator raft <subcommand> [options] [args]

 This command groups subcommands for operators interacting with the Vault
 integrated Raft storage backend. Most users will not need to interact with these
 commands. Here are a few examples of the Raft operator commands:

Subcommands:
    join           Joins a node to the Raft cluster
    list-peers     Returns the Raft peer set
    remove-peer    Removes a node from the Raft cluster
    snapshot       Restores and saves snapshots from the Raft cluster

출처: 문서

본문

join

이 명령어는 새 노드를 래프트 클러스터의 피어(peer)로 조인시키는 데 사용해요. 조인하려면 클러스터에 기존 멤버가 최소한 하나 있어야 해요. 샤미르(shamir) 실을 사용 중이라면, HA에만 전용으로 쓰는지에 따라 조인 과정 전후에 언실 키를 제공해야 해요.

래프트를 스토리지로 사용하면 조인 전에 노드를 언실해야 하고 leader-api-addr 인자를 제공해야 해요. 래프트를 ha_storage로 사용하면 조인 전에 노드를 먼저 언실해야 하고 leader-api-addr을 제공해선 안 돼요.

Usage: vault operator raft join [options] <leader-api-addr>

  Join the current node as a peer to the Raft cluster by providing the address
  of the Raft leader node.

      $ vault operator raft join "http://127.0.0.2:8200"

join 명령어는 정적 IP 주소나 호스트네임 대신 클라우드 자동 조인(auto-join) 구성을 지정할 수도 있게 해줘요. 제공하면 Vault는 제공된 자동 조인 구성을 기반으로 잠재적 리더 주소를 자동으로 발견·해석하려 시도해요.

Vault는 자동 조인 기능을 지원하기 위해 go-discover를 사용해요. 형식에 대한 자세한 내용은 go-discover README를 참고하세요.

기본적으로 Vault는 발견된 피어에 HTTPS와 포트 8200으로 연결하려 시도해요. 운영자는 각각 --auto-join-scheme과 --auto-join-port CLI 플래그로 이를 덮어쓸 수 있어요.

Usage: vault operator raft join [options] <auto-join-configuration>
  Join the current node as a peer to the Raft cluster by providing cloud auto-join
  metadata configuration.
    $ vault operator raft join "provider=aws region=eu-west-1 ..."

파라미터 (Parameters)

operator raft join 명령어에 다음 플래그를 사용할 수 있어요.

-leader-ca-cert (string: "") — 래프트 리더와 통신하기 위한 CA 인증서.
-leader-client-cert (string: "") — 래프트 리더에 인증하기 위한 클라이언트 인증서.
-leader-client-key (string: "") — 래프트 리더에 인증하기 위한 클라이언트 키.
-non-voter (bool: false) (enterprise) — 서버가 래프트 쿼럼에 참여하지 않고 데이터 복제 스트림만 받도록 만드는 플래그. 서버에 대한 읽기 요청이 많은 경우 클러스터에 읽기 확장성을 추가하는 데 쓸 수 있어요. 기본값은 false예요. retry_join 스탠자를 사용할 때의 동등한 구성 옵션은 retry_join_as_non_voter를 참고하세요.
-retry (bool: false) — 실패 시 래프트 클러스터 조인을 계속 재시도해요. 기본값은 false예요.

참고: 이 파라미터들(-leader-ca-cert, -leader-client-cert, -leader-client-key)에는 파일 경로가 아니라 인증서 또는 키의 내용(content)이 필요하다는 점을 유의하세요.

list-peers

이 명령어는 래프트 클러스터의 전체 피어 집합을 나열하는 데 사용해요.

Usage: vault operator raft list-peers

  Provides the details of all the peers in the Raft cluster.

      $ vault operator raft list-peers

파라미터 (Parameters)

operator raft list-peers 명령어에 다음 플래그를 사용할 수 있어요.

-dr-token (string: "") — DR 세컨더리 클러스터에 인증하기 위한 DR 작업 토큰. 표준 Vault 토큰이 허용되지 않는 DR 세컨더리 클러스터에 대해 관리 명령(예: 쓰기 작업)을 실행할 때 필요해요.

DR 세컨더리 클러스터는 DR 프라이머리의 래프트 피어 구성을 미러링해요. DR 세컨더리 클러스터의 래프트 노드를 직접 관리해야 할 때(예: 실패한 노드 제거)만 -dr-token을 사용하세요. 변경 사항이 DR 프라이머리의 피어 집합과 일치하는지 확인하세요.

$ vault operator raft <subcommand> -dr-token <dr-operation-token>

예시 출력 (Example output)

{
 ...
  "data": {
    "config": {
      "index": 62,
      "servers": [
        {
          "address": "127.0.0.2:8201",
          "leader": true,
          "node_id": "node1",
          "protocol_version": "3",
          "voter": true
        },
        {
          "address": "127.0.0.4:8201",
          "leader": false,
          "node_id": "node3",
          "protocol_version": "3",
          "voter": true
        }
      ]
    }
  }
}

list-peers의 출력으로 클러스터가 예상 상태에 있는지 확인해요. remove-peer로 서버를 제거했다면 그 서버는 더 이상 list-peers 출력에 나타나지 않아야 해요. add-peer나 retry_join으로 서버를 추가했다면 list-peers 출력을 확인해 클러스터에 추가되었고(노드가 non-voter로 추가되지 않았다면) 투표자(voter)로 승격되었는지 봐요.

remove-peer

이 명령어는 노드를 래프트 클러스터의 피어에서 제거하는 데 사용해요. 서버가 더 이상 존재하지 않고 클러스터에 알려지지 않는데도 래프트 구성에 피어가 남아 있을 수 있는 경우, 이 명령어로 실패한 서버를 제거해 더 이상 래프트 쿼럼에 영향을 주지 않게 해요.

Usage: vault operator raft remove-peer <server_id>

  Removes a node from the Raft cluster.

      $ vault operator raft remove-peer node1

파라미터 (Parameters)

operator raft remove-peer 명령어에 다음 플래그를 사용할 수 있어요.

-dr-token (string: "") — DR 세컨더리 클러스터에 인증하기 위한 DR 작업 토큰. 표준 Vault 토큰이 허용되지 않는 DR 세컨더리 클러스터에 대해 관리 명령(예: 쓰기 작업)을 실행할 때 필요해요.

$ vault operator raft <subcommand> -dr-token <dr-operation-token>

참고:

snapshot

이 명령어는 통합 래프트 스토리지 백엔드의 스냅샷 기능과 상호작용하는 운영자를 위한 하위 명령어들을 그룹으로 묶은 명령어예요.

데이터 백업·복원

모든 Vault 에디션은 데이터 백업·복원을 위한 스냅샷 저장·복원 기능을 지원해요. Vault Enterprise 사용자는 로컬 또는 클라우드 저장소로의 자동 스냅샷과 개별 시크릿 복구를 활용할 수 있어요.

스냅샷에 대한 자세한 내용은 다음 리소스를 참고하세요.

Manage snapshots 가이드.
snapshot CLI command
/sys/storage/raft/snapshot-load 엔드포인트

Usage: vault operator raft snapshot <subcommand> [options] [args]

  This command groups subcommands for operators interacting with the snapshot
  functionality of the integrated Raft storage backend. Here are a few examples of
  the Raft snapshot operator commands:

  Installs the provided snapshot, returning the cluster to the state defined in it:

      $ vault operator raft snapshot restore raft.snap

  Saves a snapshot of the current state of the Raft cluster into a file:

      $ vault operator raft snapshot save raft.snap

  Inspects a snapshot based on a file:

      $ vault operator raft snapshot inspect raft.snap

  Please see the individual subcommand help for detailed usage information.

Subcommands:
    inspect    Inspects raft snapshot
    load       Loads the provided local or cloud storage snapshot
    restore    Installs the provided snapshot, returning the cluster to the state defined in it
    save       Saves a snapshot of the current state of the Raft cluster into a file
    unload     Unloads the snapshot with provided ID

snapshot inspect

Vault 래프트 클러스터에서 가져온 스냅샷 파일을 검사하고, 키 수와 사용된 공간을 보여주는 표를 출력해요.

Usage: vault operator raft snapshot inspect <snapshot_file>

예:

$ vault operator raft snapshot inspect raft.snap

snapshot load

적절한 Vault Enterprise 라이선스가 필요해요.

클러스터를 스냅샷 데이터로 덮어쓰지 않고 새 스냅샷을 Vault 클러스터에 로드해요.

스냅샷 로드 제한 사항

스냅샷은 같은 클러스터에서 나온 것이고 현재 클러스터와 같은 언실 키를 가져야 해요.
한 번에 한 클러스터에 하나의 스냅샷만 로드할 수 있어요.
Vault는 로드된 지 72시간 후 스냅샷을 자동으로 언로드해요.
클러스터의 활성 노드가 바뀌면 로드된 스냅샷의 상태가 오류로 업데이트되고 복구 작업에 사용할 수 없어요. 다시 사용하려면 스냅샷을 언로드하고 다시 로드해야 해요.
Vault 구성에 mlock이 활성화되어 있으면 스냅샷을 로드할 수 없어요.

Usage: vault operator raft snapshot load < SNAPSHOT_FILE | auto_snapshot_config=CONFIG_NAME url=URL >

  Loads the provided snapshot for reading or recovering data on supported paths.

  This command supports two modes of operation:

  1. Loading a local snapshot file from the filesystem.
     In this mode, the file path must be provided as the only positional argument.

         $ vault operator raft snapshot load raft.snap

  2. Loading a snapshot that was created by Vault's automated snapshot utility from cloud storage.
     In this case, the command accepts two K=V arguments: auto_snapshot_config and url.

         $ vault operator raft snapshot load auto_snapshot_config=foo url=https://foo.com/blob/snapshot

snapshot restore

vault operator raft snapshot save로 가져온 Vault 데이터의 스냅샷을 복원해요.

Usage: vault operator raft snapshot restore <snapshot_file>

  Installs the provided snapshot, returning the cluster to the state defined in it.

      $ vault operator raft snapshot restore raft.snap

반환 시 복원 완료 아님

restore 명령어는 복원 작업이 완료될 때가 아니라 Vault가 스냅샷 파일을 검증하고 수락하자마자 종료돼요. 전체 복원 작업은 백그라운드에서 실행되어 모든 하위 시스템을 해체하고 데이터베이스를 교체한 뒤 하위 시스템을 다시 시작해요. 서버 로그에서 "post-unseal setup complete"와 "vault is unsealed"가 보이기 전까지는 정상 작업을 재개하지 마세요.

snapshot save

Vault 데이터의 스냅샷을 찍어요. 통합 스토리지를 사용한다면 이 스냅샷으로 Vault를 스냅샷을 찍은 시점으로 복원할 수 있어요. Vault는 고가용성 스토리지에만 래프트를 사용하는 배포에는 스냅샷을 지원하지 않아요.

Usage: vault operator raft snapshot save <snapshot_file>

  Saves a snapshot of the current state of the Raft cluster into a file.

      $ vault operator raft snapshot save raft.snap

snapshot unload

적절한 Vault Enterprise 라이선스가 필요해요.

vault operator raft snapshot load로 이전에 로드한 스냅샷을 언로드해요.

Usage: vault operator raft snapshot unload <SNAPSHOT_ID>

  Unloads the snapshot with the provided ID.

      $ vault operator raft snapshot unload 8a4f31cc-7bb2-227a-aa18-8f140fb40f10

autopilot

이 명령어는 통합 래프트 스토리지 백엔드의 autopilot 기능과 상호작용하는 운영자를 위한 하위 명령어들을 그룹으로 묶은 명령어예요. get-config, set-config, state의 3가지 하위 명령어를 지원해요.

autopilot 기능에 대한 더 자세한 개요는 개념 페이지를 참고하세요.

Usage: vault operator raft autopilot <subcommand> [options] [args]

This command groups subcommands for operators interacting with the autopilot
functionality of the integrated Raft storage backend.

Subcommands:
    get-config    Returns the configuration of the autopilot subsystem under integrated storage
    set-config    Modify the configuration of the autopilot subsystem under integrated storage
    state         Displays the state of the raft cluster under integrated storage as seen by autopilot

autopilot state

통합 스토리지 아래의 래프트 클러스터 상태를 autopilot이 보는 대로 표시해요. autopilot이 클러스터를 건강하다고 생각하는지 여부를 보여줘요. 상태에는 nodeID와 IP 주소별 모든 서버 목록이 포함돼요.

Usage: vault operator raft autopilot state

  Displays the state of the raft cluster under integrated storage as seen by autopilot.

    $ vault operator raft autopilot state

예시 출력 (Example output)

Healthy:                         true
Failure Tolerance:               1
Leader:                          vault_1
Voters:
   vault_1
   vault_2
   vault_3
Servers:
   vault_1
      Name:              vault_1
      Address:           127.0.0.1:8201
      Status:            leader
      Node Status:       alive
      Healthy:           true
      Last Contact:      0s
      Last Term:         3
      Last Index:        61
      Version:           1.17.3
      Node Type:         voter
   vault_2
      Name:              vault_2
      Address:           127.0.0.1:8203
      Status:            voter
      Node Status:       alive
      Healthy:           true
      Last Contact:      564.765375ms
      Last Term:         3
      Last Index:        61
      Version:           1.17.3
      Node Type:         voter
   vault_3
      Name:              vault_3
      Address:           127.0.0.1:8205
      Status:            voter
      Node Status:       alive
      Healthy:           true
      Last Contact:      3.814017875s
      Last Term:         3
      Last Index:        61
      Version:           1.17.3
      Node Type:         voter

클러스터의 "Failure Tolerance"는 중단 없이 점진적으로 실패할 수 있는 클러스터의 노드 수예요.

클러스터의 건강을 확인할 때 각 서버의 다음 필드를 확인하세요:

Healthy: Autopilot이 이 노드를 건강하다고 여기는지 여부.
Status: 노드의 투표 상태. voter, leader, non-voter 중 하나예요.
Last Index: 마지막으로 적용된 래프트 로그의 인덱스. 리더의 "Last Index" 값과 가까워야 해요.
Version: 서버에서 실행 중인 Vault 버전.
Node Type: 노드의 유형. CE에서는 항상 voter예요. Enterprise 노드 유형에 대한 설명은 아래를 참고하세요.

Vault Enterprise는 자동 업그레이드, 낙관적 실패 허용(optimistic failure tolerance), 리던던시 존(redundancy zone)과 관련된 추가 출력을 포함해요.

예시 Vault Enterprise 출력

Redundancy Zones:
   a
      Servers: vault_1, vault_2, vault_5
      Voters: vault_1
      Failure Tolerance: 2
   b
      Servers: vault_3, vault_4
      Voters: vault_3
      Failure Tolerance: 1
Upgrade Info:
   Status: await-new-voters
   Target Version: 1.17.5
   Target Version Voters:
   Target Version Non-Voters: vault_5
   Other Version Voters: vault_1, vault_3
   Other Version Non-Voters: vault_2, vault_4
   Redundancy Zones:
      a
         Target Version Voters:
         Target Version Non-Voters: vault_5
         Other Version Voters: vault_1
         Other Version Non-Voters: vault_2
      b
         Target Version Voters:
         Target Version Non-Voters:
         Other Version Voters: vault_3
         Other Version Non-Voters: vault_4

"Optimistic Failure Tolerance"는 중단 없이 점진적으로 실패할 수 있는 건강한 활성(active) 및 백업 투표 서버의 수를 설명해요.

Enterprise 노드 유형 (Enterprise Node Types)

voter — 서버가 래프트 투표자이며 쿼럼에 기여해요.
read-replica — 서버가 래프트 투표자는 아니지만 모든 데이터의 복제본을 받아요.
zone-voter — 리던던시 존의 주요 래프트 투표자.
zone-extra-voter — 리던던시 존의 추가 래프트 투표자.
zone-standby — 필요 시 투표자로 승격될 수 있는 리던던시 존의 non-voter.

autopilot get-config

통합 스토리지 아래의 autopilot 하위 시스템 구성을 반환해요.

Usage: vault operator raft autopilot get-config

  Returns the configuration of the autopilot subsystem under integrated storage.

    $ vault operator raft autopilot get-config

autopilot set-config

통합 스토리지 아래의 autopilot 하위 시스템 구성을 수정해요.

Usage: vault operator raft autopilot set-config [options]

  Modify the configuration of the autopilot subsystem under integrated storage.

      $ vault operator raft autopilot set-config -server-stabilization-time 10s

이 명령어에 적용 가능한 플래그는 다음과 같아요:

-cleanup-dead-servers (bool: false) — 죽은 서버를 주기적으로 또는 새 서버가 조인할 때 래프트 피어 목록에서 제거할지 제어해요. 이를 위해 min-quorum도 설정해야 해요.
-last-contact-threshold (string: "10s") — 리더 접촉 없이 갈 수 있는 시간 제한. 초과하면 건강하지 않은 것으로 간주돼요.
-dead-server-last-contact-threshold (string: "24h") — 리더 접촉 없이 갈 수 있는 시간 제한. 초과하면 실패한 것으로 간주돼요. cleanup_dead_servers가 설정되어 있을 때만 적용돼요. 클러스터에 새 노드를 추가할 때, dead_server_last_contact_threshold는 래프트 스냅샷을 로드하는 데 걸리는 시간보다 커야 해요. 그렇지 않으면 새로 추가된 노드는 스냅샷 로드와 시작을 마치기 전에 클러스터에서 제거돼요. HSM을 사용한다면 dead_server_last_contact_threshold가 HSM의 응답 시간보다 커야 해요.
- 경고: dead_server_last_contact_threshold를 하루 같은 긴 기간으로 유지할 것을 강력히 권장해요. 너무 낮으면 실제로는 죽지 않은 노드가 제거될 수 있으니까요.
-max-trailing-logs (int: 1000) — 건강하지 않은 것으로 간주되기 전에 서버가 뒤처질 수 있는 래프트 로그의 항목 수. 이 값이 너무 낮으면 팔로워가 뒤처질 때 클러스터가 쿼럼을 잃을 수 있어요. 이 값은 Vault에 쓰기 부하가 매우 높고 새 서버가 투표자가 되는 데 오래 걸리는 것을 볼 때만 기본값에서 늘려야 해요. 이는 드문 시나리오이며 대부분의 사용자는 이 값을 수정하면 안 돼요.
-min-quorum (int) — 클러스터에 항상 있어야 하는 최소 서버 수. Autopilot은 이 수 미만으로 서버를 정리하지 않아요. 이 값에는 기본값이 없으며, cleanup_dead_servers를 true로 설정하면 클러스터의 예상 투표자 수로 설정해야 해요. 쿼럼 크기 안내를 사용해 클러스터의 적절한 최소 쿼럼 크기를 결정하세요.
-server-stabilization-time (string: "10s") — 서버가 투표자가 될 수 있기 전에 건강한 상태로 있어야 하는 최소 시간. 그때까지는 클러스터에서 피어로 보이지만 non-voter로서 쿼럼에 기여하지 않아요.
-disable-upgrade-migration (bool: false) — 자동 업그레이드 마이그레이션(Enterprise 전용 기능)을 비활성화할지 제어해요.

더 알아보기 (Learn more)

vault operator migrate — 스토리지 마이그레이션
Manage snapshots 가이드
통합 스토리지 개념 문서

`operator raft` — 통합 래프트 스토리지 관리하기