Vault KMS 트러블슈팅

Vault KMS 트러블슈팅 (KMS troubleshooting)

vault-kube-kms 배포에서 발생하는 일반적인 문제와 해결 방법을 다룹니다.

출처: 문서

본문

베타 기능이에요. 베타 기능은 안정적이지만 아직 불완전할 수 있고 변경될 수 있어요. 프로덕션 Vault 배포에 베타 기능을 쓰는 것은 권장하지 않습니다.

프로세스가 Vault에 접근할 수 없음

vault-kube-kms 프로세스가 Vault에 연결할 수 없으면 로그에서 오류 메시지를 확인해요. vault-kube-kms를 스태틱 파드로 배포했다면 쿠버네티스 CLI에 스태틱 파드 이름과 배포한 네임스페이스를 제공해 로그를 볼 수 있어요.

$ kubectl logs -n <NAMESPACE> <POD_NAME>

잘못된 정책 구성

vault-kube-kms 로그에서 permission denied 오류가 보이면 AppRole에 연결된 Vault 정책에 필요한 권한이 포함되어 있는지 확인해요.

path "/keys/" {
    capabilities = ["read"]
}

path "/encrypt/" {
    capabilities = ["update"]
}

path "/decrypt/" {
    capabilities = ["update"]
}

path "sys/license/status" {
    capabilities = ["read"]
}

sys/license/status 경로는 Vault Enterprise 검증에 필요해요. Vault Kubernetes Key Management가 Vault Enterprise 라이선스를 검증할 수 있도록 sys/license/status에 대한 읽기 권한을 반드시 포함해야 합니다. sys/license/status 권한을 빼먹으면 vault-kube-kms 프로세스가 시작할 수 없어요.

잘못된 인증 마운트 또는 AppRole 이름

vault-kube-kms 프로세스 로그에서 인증 오류가 보이면 다음을 확인해요.

--approle-role-id 플래그가 Vault의 AppRole에 대한 역할 ID와 일치하는지.
--approle-secret-id-path 플래그가 AppRole의 유효한 시크릿 ID가 있는 유효한 파일시스템 경로를 가리키는지.
vault-kube-kms 프로세스를 실행하는 스태틱 파드가 --approle-secret-id-path가 가리키는 파일시스템 경로에 접근할 수 있는지.
Vault에서 vault-kube-kms 프로세스에 제공한 것과 같은 마운트 경로에 AppRole 인증 방식을 활성화했는지.

Vault에 연결 불가

vault-kube-kms 프로세스 로그에서 연결 오류가 보이면 다음을 확인해요.

--vault-address 플래그가 연결 가능한 Vault 서버를 가리키는지.
네트워크 정책이나 방화벽이 컨트롤 플레인 노드에서 Vault로의 트래픽을 허용하는지.
TLS를 사용한다면 다음 중 하나가 참인지 확인해요.
- --tls-ca-file 플래그가 유효한 CA 인증서를 가리킴.
- 시스템 신뢰 저장소에 Vault 서버용 유효한 CA가 포함되어 있음.

만료된 AppRole 시크릿 ID

Vault Kubernetes Key Management가 이전에는 동작했는데 인증이 실패하기 시작한다면 AppRole 시크릿 ID가 만료됐을 수 있어요.

Vault에서 새 시크릿 ID를 생성하고 --approle-secret-id-path 파일의 내용을 교체해요.

$ vault write -f auth/approle/role/<ROLE_NAME>/secret-id

새 시크릿 ID를 각 컨트롤 플레인 노드의 파일에 복사해요.
시크릿 ID 업데이트 후 vault-kube-kms 프로세스를 재시작해 업데이트된 파일을 읽는지 확인해요.

Vault Enterprise 검증 실패

Vault Kubernetes Key Management는 Vault Enterprise가 필요해요. 다음 오류 메시지는 vault-kube-kms 프로세스가 Vault Community 인스턴스에 연결됐음을 나타냅니다.

vault Community Edition detected - vault-kube-kms requires Vault Enterprise

API 서버가 Vault Kubernetes Key Management에 접근할 수 없음

쿠버네티스 API 서버가 vault-kube-kms 프로세스와 통신할 수 없으면 데이터를 암호화·복호화할 때 쿠버네티스가 오류를 보고해요. kube-apiserver 로그에서 KMS 관련 오류 메시지를 확인하세요.

쿠버네티스 API 서버는 0770 권한(소유자와 그룹)의 유닉스 도메인 소켓으로 vault-kube-kms 프로세스와 통신합니다. 통신하려면 API 서버 프로세스가 root로 실행되거나 vault-kube-kms 프로세스와 같은 유닉스 그룹으로 실행되어야 해요.

소켓 주소 불일치

쿠버네티스 EncryptionConfiguration의 endpoint 필드는 vault-kube-kms 프로세스에 전달한 --listen-address 플래그와 일치해야 해요.

두 값이 같은 유닉스 소켓 경로를 가리키는지 확인하세요. 예를 들어 EncryptionConfiguration이 다음을 포함한다면:

providers:
  - kms:
      apiVersion: v2
      name: vault-kms
      endpoint: unix:///var/run/kmsplugin/kms.sock

vault-kube-kms 프로세스도 같은 주소로 시작해야 해요.

--listen-address=unix:///var/run/kmsplugin/kms.sock

API 엔드포인트와 listen 주소가 일치하는데도 소켓 오류가 보이면, kube-apiserver 파드와 vault-kube-kms 파드 모두 소켓이 있는 디렉터리를 마운트했는지 확인하세요. 둘 중 하나가 디렉터리를 마운트하지 못하면 그 파드는 유닉스 소켓에 접근할 수 없어요.

누락되거나 잘못된 구성 플래그

쿠버네티스 CLI로 스태틱 파드의 vault-kube-kms 프로세스 로그를 검토해요.

$ kubectl logs -n <NAMESPACE> <POD_NAME>

로그 시작 부분에서 검증 오류를 찾으세요. 구성 플래그나 환경 변수가 제대로 파싱되거나 전달되지 않으면 vault-kube-kms 프로세스가 시작에 실패합니다.

암호화 또는 복호화 오류

호환되지 않는 Transit 키 구성은 vault-kube-kms 프로세스가 Vault에 연결된 후 암호화·복호화 작업이 실패하게 만들 수 있어요.

더 오래된 키 버전으로 암호화된 데이터의 복호화가 실패하면 Vault의 Transit 키에 대한 min_decryption_version 설정을 확인해요.

$ vault read transit/keys/<KEY_NAME>

min_decryption_version이 데이터를 암호화하는 데 사용한 키 버전보다 높으면 Vault가 복호화 요청을 거부해요. min_decryption_version을 낮추거나 새 키 버전으로 데이터를 재암호화하세요.

min_decryption_version을 변경하면 쿠버네티스가 더 오래된 키 버전으로 암호화된 데이터를 읽지 못하게 할 수 있어요. 최소 버전 컷오프를 올리기 전에 모든 암호화 데이터가 새 최소값 이상의 키 버전을 사용하는지 확인하세요.

마찬가지로 min_encryption_version이 설정되어 있다면 vault-kube-kms 프로세스가 최소값 이상의 키 버전을 사용하는지 확인해요.

기존 데이터 재암호화

Vault에서 Transit 키를 회전한 후 etcd의 기존 데이터는 여전히 이전 키 버전으로 암호화된 상태로 남습니다. 쿠버네티스는 기존 데이터를 자동으로 재암호화하지 않아요.

기존 시크릿을 새 키 버전으로 재암호화하려면 no-op 쓰기를 수행해 쿠버네티스가 재암호화하도록 강제해요.

$ kubectl get secrets --all-namespaces -o json | kubectl replace -f -

EncryptionConfiguration에 구성된 다른 모든 리소스 타입에 대해 no-op을 반복할 수 있어요.

클러스터가 크거나 복잡한 마이그레이션에는 저장 데이터 암호화에 대한 쿠버네티스 문서인 encrypting confidential data at rest를 참고해 스토리지 마이그레이션 전략에 대한 지침을 얻으세요.

Vault KMS 트러블슈팅