`operator diagnose` — Vault 상태 진단하기

vault operator diagnose 명령어는 주로 Vault가 다운되었거나 부분적으로 운영 불능일 때 사용해야 해요. 이 명령어는 Vault의 어떤 상태에서든 안전하게 사용할 수 있지만, Vault 서버가 이미 실행 중이면 일부 테스트 사례에서 의미 없는 결과를 반환할 수 있어요.

참고: 서버 시작 전이나 서버가 운영 중일 때처럼 진단 명령어를 사전에 실행한다면, 아래 개별 검사들 중 어떤 검사가 잘못된 오류 메시지나 경고를 반환하는지 확인하려면 각 검사에 대한 문서를 참고하세요.

출처: 문서

본문

사용법 (Usage)

모든 명령어에 기본으로 포함된 표준 플래그 외에 다음 플래그들을 추가로 사용할 수 있어요.

출력 옵션 (Output options)

-format (string: "table") — 출력 형식을 지정해요. 유효한 값은 "table", "json", "yaml"이에요. VAULT_FORMAT 환경 변수로도 지정할 수 있어요.

출력 구성 (Output layout)

operator diagnose 명령어는 CLI에 일련의 줄을 출력해요. 각 줄은 괄호 안의 접두사로 시작해요. 그것들은 다음과 같아요:

[ success ] — 검사가 성공했음을 나타내요.
[ warning ] — 검사는 통과했지만, Vault가 겪는 문제와 관련될 수 있는 잠재적 이슈를 살펴봐야 할 수 있음을 나타내요. Diagnose는 자주 경고해요. 이 경고들은 디버깅 과정의 출발점 역할을 하기 위한 것이에요.
[ failure ] — 검사가 실패했음을 나타내요. 실패는 diagnose 명령어가 보기에 치명적인 문제예요.

이 접두사 줄들 외에도, 접두사가 없지만 보라색으로 색상 표시된 출력 줄이 있을 수 있어요. 이것들은 Diagnose의 조언 줄이며, 발생할 수 있는 잠재적 경고나 실패를 고치는 방법에 대한 일반적인 지침을 제공하기 위한 것이에요.

중첩된 검사의 경고(warn)나 실패(fail) 접두사는 접두사가 부모를 능가(supercede)하면 부모로 올라가요. Fail은 warn을 능가하고, warn은 ok를 능가해요. 예를 들어 Storage 검사 아래의 TLS 검사가 실패하면 [ failure ] 접두사가 Storage 검사로 올라가요.

커맨드 옵션 (Command options)

-config (string: "") — 시작 시 Vault 서버가 사용하는 vault 구성 파일 경로.

진단 검사 (Diagnose checks)

다음 섹션은 Diagnose가 실행하는 다양한 검사를 자세히 설명해요. 문서의 검사 이름은 중첩을 나타내기 위해 해당할 때 슬래시로 구분돼요. 예를 들어 A / B로 문서화된 검사는 operator diagnose 출력에서 B로 표시되고, A 아래에 중첩(들여쓰기)돼요.

Vault diagnose

Vault Diagnose는 나머지 검사를 포함하는 최상위 검사예요. 검사 상태를 보고해요.

운영 체제 / 열린 파일 한도 검사 (Check open file limit)

Check Open File Limit은 열린 파일 한도 값이 vault가 효과적으로 실행되기에 충분히 높게 설정되었는지 확인해요. 이 한도를 최소 1024768로 설정할 것을 권장해요. 이 검사는 openbsd, arm, windows에서 건너뛰어져요.

운영 체제 / 디스크 사용량 검사 (Check disk usage)

Check Disk Usage는 각 파티션의 디스크 사용량을 보고해요. 운영 호스트의 각 파티션은 파티션의 최소 5%가 비어 있고, 최소 1GB의 공간이 있기를 권장해요. 이 검사는 openbsd와 arm에서 건너뛰어져요.

구성 파싱 (Parse configuration)

Parse Configuration은 vault 서버 구성 파일에 구문 오류가 있는지 확인해요. 구성 파일의 추가 값, 반복 스탠자, 그리고 구성 파일에 속하지 않는 스탠자(예: tcp 리스너 대신 "tcpp" 리스너)를 확인해요. 현재 storage 스탠자는 확인되지 않아요.

스토리지 / 스토리지 백엔드 생성 검사 (Create storage backend)

Create Storage Backend는 vault 서버 구성에 설정된 스토리지 스탠자가 내부적으로 스토리지 객체를 생성하기에 충분한 정보를 가지고 있는지 확인해요. 일반적인 오류는 스토리지 스탠자의 잘못 구성된 필드와 관련돼요.

스토리지 / consul TLS 검사 (Check consul TLS)

Check Consul TLS는 스토리지 타입이 consul일 때 스토리지 스탠자에 포함된 TLS 정보를 검증해요. 인증서 체인이 제공되면 Diagnose는 루트, 중간, 리프 인증서를 파싱하고 각각의 정확성을 검사해요.

스토리지 / consul 직접 스토리지 접근 검사 (Check consul direct storage access)

Check Consul Direct Storage Access는 Vault가 consul 서버에 직접 접근하는 것이 아니라 로컬 에이전트를 통해 접근하도록 보장하는 consul 전용 검사예요.

스토리지 / 래프트 폴더 권한 검사 (Check raft folder permissions)

Check Raft Folder Permissions는 래프트 폴더의 권한을 계산하고, 이전에 폴더 안에 boltDB 파일이 초기화되었는지 확인하며, 폴더가 지나치게 허용적이지 않으면서도 사용하기에 충분한 권한을 갖도록 보장해요. 래프트 폴더는 다른 권한이 없어야 하지만, 설정에 따라 그룹 rw 또는 소유자 rw 권한을 가져야 해요. 이 검사는 심볼릭 링크 사용이 감지되면 경고하기도 해요. 기존 서버 실행 없이 diagnose를 실행하면 래프트 파일이 생성되지 않았다고 경고한다는 점을 참고하세요. 이 검사는 windows에서 건너뛰어져요.

스토리지 / 래프트 폴더 소유권 검사 (Check raft folder ownership)

Check Raft Folder Ownership은 vault가 boltDB 폴더에 접근하기 위해 root로 실행될 필요가 없도록 보장해요. 기존 서버 실행 없이 diagnose를 실행하면 래프트 파일이 생성되지 않았다고 경고한다는 점을 참고하세요. 이 검사는 windows에서 건너뛰어져요.

스토리지 / 래프트 쿼럼 검사 (Check for raft quorum)

Check For Raft Quorum은 FSM을 사용해 vault가 마지막으로 실행 중일 때 래프트 쿼럼에 홀수 개의 투표자가 있었는지 확인해요. 기존 서버 실행 없이 diagnose를 실행하면 투표자가 0명이라고 경고한다는 점을 참고하세요.

스토리지 / 스토리지 접근 검사 (Check storage access)

Check Storage Access는 diagnose/latency/<uuid>라는 이름의 의미 없는(dud) 값을 스토리지에 쓰려 시도해요. 이 검사가 해당 데이터를 덮어쓰므로 diagnose를 실행하기 전에 이 위치에 중요한 데이터가 없는지 확인하세요. 이 검사는 그런 다음 자신이 쓴 값을 나열하고 읽어 이름과 값이 예상대로인지 확인해요. Check Storage Access는 어떤 작업이 100ms보다 오래 걸리면 경고하고, 전체 검사가 30초보다 오래 걸리면 오류를 내요.

서비스 검색 / consul 서비스 검색 TLS 검사 (Check consul service discovery TLS)

Check Consul Service Discovery TLS는 스토리지 타입이 consul일 때 서비스 검색 스탠자에 포함된 TLS 정보를 검증해요. 인증서 체인이 제공되면 Diagnose는 루트, 중간, 리프 인증서를 파싱하고 각각의 정확성을 검사해요.

서비스 검색 / consul 직접 서비스 검색 검사 (Check consul direct service discovery)

Check Consul Direct Service Discovery는 Vault가 consul 서버에 직접 접근하는 것이 아니라 로컬 에이전트를 통해 접근하도록 보장하는 consul 전용 검사예요.

Vault 서버 구성 실 생성 (Create Vault server configuration seals)

Create Vault Server Configuration Seals는 vault 구성 스탠자에서 실(seal)을 생성하고 초기화·종료될 수 있는지 확인해요.

운송 실 TLS 검사 (Check transit seal TLS)

Check Transit Seal TLS는 운송 실(transit seal) 스탠자(존재한다면)에 제공된 TLS 클라이언트 인증서, 키, CA 인증서의 정확성을 검사해요.

코어 구성 생성 / 코어용 난수 초기화 (Initialize randomness for core)

Initialize Randomness for Core는 vault가 vault 코어가 사용하는 randReader에 접근할 수 있도록 보장해요.

HA 스토리지

이 검사와 중첩 검사들은 Check Storage 검사와 동일해요. 유일한 차이는 여기의 검사들이 storage 섹션이 아니라 vault 구성의 ha_storage 섹션에 지정된 것에 실행된다는 점이에요.

리다이렉트 주소 결정 (Determine redirect address)

VAULT_API_ADDR, VAULT_REDIRECT_ADDR, VAULT_ADVERTISE_ADDR 환경 변수 중 하나가 설정되었거나, 리다이렉트 주소가 vault 구성에 지정되었는지 확인해요.

클러스터 주소 검사 (Check cluster address)

VAULT_CLUSTER_ADDR 환경 변수에서, 또는 vault 구성에 지정된 리다이렉트 주소나 클러스터 주소에서 클러스터 주소를 파싱하고, 주소가 host:port 형식인지 확인해요.

코어 생성 검사 (Check core creation)

Check Core Creation은 vault가 코어 객체를 생성할 때 수행하는 논리적 구성 검사를 검증해요. 이들은 런타임 검사이며, 이 진단 테스트가 던지는 오류는 vault 서버 자체가 실행될 때도 던져져요.

자동 적재 라이선스 검사 (Check for autoloaded license)

Check For Autoloaded License는 엔터프라이즈 진단 검사로, vault가 30일 이내에 만료되지 않는 유효한 자동 적재 라이선스에 접근할 수 있는지 확인해요.

리스너 시작 / 리스너 TLS 검사 (Check listener TLS)

Check Listener TLS는 서버 인증서 파일과 키가 유효하고 일치하는지 검증해요. 클라이언트 CA 파일이 제공되면 유효한 인증서인지 확인하고, 리스너 구성 스탠자에 대해 표준 런타임 리스너 검사(예: 최소·최대 TLS 버전이 vault가 지원하는 범위 내인지)를 수행해요. 다른 모든 Diagnose TLS 검사처럼, 제공된 인증서 중 다음 달 안에 만료되도록 설정된 것이 있으면 경고해요.

리스너 시작 / 리스너 생성 (Create listeners)

Create Listeners는 리스너 구성을 사용해 리스너를 초기화하며, 문제가 생기면 서버 오류로 나요.

자동언실 암호화 검사 (Check autounseal encryption)

Check Autounseal Encryption은 실 타입이 샤미르(shamir) 실이 아니면 실 스탠자를 사용해 배리어(barrier)를 초기화하고, 그것으로 의미 없는 값을 암호화·해독해요.

런타임 전 서버 검사 (Check server before runtime)

Check Server Before Runtime은 서버 실행 명령어와 동등해, 서버가 초기화되기 전에 런타임 코드 검사를 거쳐 아무것도 실패하지 않도록 해요. 이 검사는 다른 진단 검사가 실패하지 않으면 절대 실패하지 않아요.

더 알아보기 (Learn more)

vault operator raft — 래프트 클러스터 관리
vault status — 서버 상태 확인
Seal/Unseal 문서

`operator diagnose` — Vault 상태 진단하기