중복 Vault identity 찾기 및 해결하기

중복 Vault identity 찾기 및 해결하기

1.19 이전 버전의 Vault 버그 때문에 엔티티, 별칭, 그룹에 중복 identity가 생길 수 있어요. Vault 클러스터의 영구 저장소에 중복 identity가 있으면 예기치 않은 동작이 발생할 수 있어요. 중복 identity는 Vault의 일반적인 예상 시나리오와 테스트 시나리오 밖에 있기 때문이에요.

Vault 서버 로그에는 주어진 클러스터에 중복 identity가 존재하는 시점을 파악하는 데 도움이 되는 정보가 포함돼요. 클러스터를 정상·지원 동작으로 되돌리려면 중복을 가능한 한 빨리 식별하고 해결하는 것을 강력히 권장해요.

출처: 문서

본문

시작 전에(Before you start)

  • 모든 클러스터에서 Vault 1.19 이상을 실행해야 해요. 1.19+로 업그레이드해야 Vault가 deduplication 세부 사항을 로그에 남겨요.
  • Vault 클러스터에 대한 관리자 권한이 있어야 해요.

1단계: 중복 찾기(Look for duplicates)

서버 로그에서 중복을 식별하려면:

  1. 활성 노드의 시스템 로그에서 마지막 언실(unseal) 작업을 찾으려면 core: post-unseal setup starting을 찾아요. 예: [INFO] core: post-unseal setup starting ...<check here> ... [INFO] core: post-unseal setup complete
  2. 시스템 로그에서 setup starting과 setup complete 항목 사이에 DUPLICATES DETECTED가 있는지 확인해요. 예: [WARN] identity: DUPLICATES DETECTED, see following logs for details [...]

DUPLICATES DETECTED 항목이 보이지 않으면 현재 클러스터는 깨끗한 상태이므로 다음 클러스터로 넘어가면 돼요. 어떤 로그에도 중복이 없다고 확인되면 4단계로 건너뛸 수 있어요.

참고: 복제(replication)를 쓴다면 모든 primary 클러스터와 모든 성능 복제(PR) secondary 클러스터에서 중복 확인을 반복해요. PR secondary 클러스터는 클라이언트 요청을 처리하므로 로컬 중복이 추가로 있을 수 있어요. 재해 복구(DR) secondary는 클라이언트 요청을 처리하지 않으므로 별도로 확인할 필요는 없어요.

2단계: 중복 제거 대상 찾기(Find deduplication targets)

시스템 로그에서 DUPLICATES DETECTED를 찾았다면, 시스템 로그에서 동일 대소문자(same-case) 별칭과 이름 변경 대상의 목록을 만들어 중복 해결 작업을 더 쉽게 진행해요. 중복 제거 대상이 많다면 다음 스크립트로 관련 항목을 뽑아 네 개의 파일을 만들 수 있어요.

  • unseal-process.log — 언실 프로세스에 해당하는 시스템 로그 부분
  • merge-details.txt — Vault가 중복 제거 중 자동 병합할 동일 대소문자 identity
  • rename-targets.txt — Vault가 중복 제거 중 이름을 바꿀 namespace/name 형태의 엔티티·그룹 이름
  • rename-details.txt — 이름 변경 대상의 전체 이름 변경 세부 사항
declare -A identity_key=(
  ['entity_alias']="identity: entity-alias"
  ['entity_rename']="identity: entity"
  ['group_rename']="identity: group"
)
declare -A match_str=(
  ['has_rename']="would rename to"
  ['has_merge']="would merge"
  ['rename']="s/.*would rename to \(.*\)\".*/\1/"
  ['group_name']="s/.*identity: group \"\(.*\)\" with.*/\1/"
  ['entity_name']="s/.*identity: entity \"\(.*\)\" with.*/\1/"
  ['namespace']="s/.*namespace ID \"\(.*\)\" duplicates.*/\1/"
)
declare -A rename_targets

# 로그의 언실 부분만 가져옵니다
log_start="core: post-unseal setup starting"
log_stop="core: post-unseal setup complete"
sed "/${log_start}/,/${log_stop}/!d;/${log_stop}/q" ../short.log > unseal-process.log

while read line; do
  # 로그 줄이 이름이 변경된 identity에 관련된 경우
  if [[ "${line}" == *"${match_str['has_rename']}"* ]]; then
    if [[ "${line}" == *"${identity_key['entity_rename']}"* ]]; then
      type="${identity_key['entity_rename']}"
      name_match="${match_str['entity_name']}"
    fi
    if [[ "${line}" == *"${identity_key['group_rename']}"* ]]; then
      type="${identity_key['group_rename']}"
      name_match="${match_str['group_name']}"
    fi
    new=$(echo $line | sed -e "${match_str['rename']}")
    old=$(echo $line | sed -e "${name_match}")
    space=$(echo $line | sed -e "${match_str['namespace']}")
    rename_targets["${space}/${old}"]="[${type}] ${space}/${old} --> ${space}/${new}"
  fi

  # 로그 줄이 same-case 병합 작업을 나타내는 경우
  if [[ "${line}" == *"${match_str['has_merge']}"* ]]; then
    merge_details=$(echo $line | sed -e "${identity_key['entity_alias']}")
    echo ${merge_details} >> merge-details.txt
  fi
done < unseal-process.log

# 이름 변경 대상 정보를 더 처리하기 위해 파일에 저장합니다
root_ns="root/"
for name in "${!rename_targets[@]}"; do
  echo ${name//"${root_ns}"/""} >> rename-targets.txt
  echo ${rename_targets["${name}"]} >> rename-details.txt
done

3단계: 중복 해결하기(Resolve any duplicates)

로그에서 중복을 찾지 못했다면 5단계로 건너뛸 수 있어요. 로그에서 중복을 찾았다면:

  1. 서버 로그의 각 항목에 대해 중복 유형을 식별해요.
    • PR/DR 배포에서: primary 클러스터에서 중복 유형을 식별해요.
    • PR 배포에서: 성능 secondary의 로컬 별칭에 대해 중복 유형을 식별해요. 로컬 중복은 secondary 클러스터에 독립적으로 존재하며 명시적 해결이 필요하지만, 비로컬 different-case 엔티티 별칭 중복 해결과 같은 과정을 따르면 돼요.
  2. 중복 유형에 따라 적절한 중복 제거 단계를 따르세요.
    • different-case 엔티티 별칭 중복 수정
    • 엔티티 및 그룹 중복 수정

4단계: (가능한) 지연 영향 준비하기(Prepare for latency impacts)

클러스터에 대한 중복 제거를 활성화하면 클러스터가 모든 엔티티·별칭·그룹의 인메모리 캐시를 다시 로드해요. 중복 제거가 성능 복제 secondary와 성능 대기(standby) 노드로 복제되면 그 노드들도 identity 시스템 캐시를 일시 중지하고 다시 로드해요.

Vault는 중복 제거 중에도 언실 상태를 유지하지만, 노드는 중복 제거가 완료될 때까지 다른 요청 처리를 일시 중지할 수 있어요. 중간 크기 클러스터에서는 중복 제거가 요청 지연에 영향을 줄 만큼 오래 걸릴 수 있어요. 큰 클러스터에서는 중복 제거가 30초보다 오래 걸려 일부 요청이 타임아웃될 수 있어요.

일반적으로 중복 제거는 Vault를 seal·unseal하는 것보다 시간이 덜 걸리고 일반 페일오버보다 덜 방해돼요. 그리고 중복이 있던 클러스터는 이후 언실 시간이 줄어들 거예요.

5단계: identity 중복 제거 강제하기(Enforce identity de-duplication)

기존 중복을 해결한 뒤에는 activation flag API 경로를 사용해 primary 클러스터에서 force-identity-deduplication 활성화 플래그를 켤 수 있어요.

기능 플래그 활성화는 일회성, 단방향 작업이에요. 기능 플래그로 게이트된 기능을 일단 활성화하면 비활성화할 수 없어요.

vault write -f sys/activation-flags/force-identity-deduplication/activate

$ curl                                      \
  --request PUT                             \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  ${VAULT_ADDR}/v1/sys/activation-flags/force-identity-deduplication/activate

각 노드의 중복 제거 시작과 끝은 시스템 로그에서 force-identity-deduplication activated 항목을 찾아 추적할 수 있어요.

INFO  core: force-identity-deduplication activated, reloading identity store
...
INFO  core: force-identity-deduplication activated, reloading identity store complete

앞으로 Vault는 고유 identity를 요구하고 언실 프로세스의 일부로 중복 제거 검사를 다시 실행해요. 시스템 로그 타임스탬프를 검토해 언실 시간에 미치는 영향을 확인할 수 있어요. core: post-unseal setup starting과 core: post-unseal setup complete 로그 줄 사이의 차이가 클러스터에 필요한 총 언실 시간을 나타내요.

더 알아보기 (Learn more)

  • different-case 엔티티 별칭 중복 수정 방법을 살펴보세요.
  • 엔티티·그룹 중복 수정 방법을 살펴보세요.
  • activation flag API 경로를 확인해 보세요.