플러그인 이벤트 알림

고급 주제! 플러그인 개발은 Vault에서 매우 고급 주제이며, 일상적인 사용에 필요한 지식이 아니에요. 플러그인을 작성할 계획이 없다면 이 문서 섹션을 읽지 않는 것을 권장해요.

출처: 문서

본문

이벤트 알림은 Vault 클러스터의 운영자와 클라이언트에게 유용할 수 있는 정보를 플러그인에서 제공할 수 있어요. Vault Enterprise 1.16+에서 실행되는 모든 플러그인이 그러한 이벤트를 생성할 수 있어요.

이 문서는 플러그인이 Go 프로그래밍 언어로 작성되었다고 가정해요. 비-Go 플러그인도 SendEvent gRPC 호출을 직접 호출해 이벤트를 보낼 수 있어요.

플러그인에서 이벤트 알림 보내기

플러그인 내에서 이벤트 알림을 보내는 것은 다음과 같이 호출하는 것만큼 간단해요:

err := logical.SendEvent(ctx, b, eventType, metadata...)

여기서:

ctx는 현재 사용되지 않는 context.Context 인터페이스예요.
b는 logical.EventSender 인터페이스를 구현하는 플러그인 백엔드예요.
eventType은 이벤트 유형의 문자열이에요.
metadata는 이벤트 알림 메타데이터에 추가될 쌍으로 해석되는 문자열 목록이에요. 예를 들어 metadata := []string{"key1", "value1", "key2", "value2"}는 메타데이터에 key1: value1과 key2: value2 쌍이 포함됨을 의미해요.
logical은 github.com/hashicorp/vault/sdk/logical를 가리켜요.

logical.SendEvent는 비차단이며 이벤트 알림을 비동기적으로 보내요.

참고: b.SendEvent()를 직접 호출하는 것도 가능하지만 전체 protobuf 구조체를 전달해야 하므로 덜 편리해요.

모범 사례

플러그인이 생성할 수 있는 이벤트에 대한 엄격한 규칙은 없지만 따라야 할 몇 가지 모범 사례가 있어요.

이벤트 알림에 민감하거나 비밀 데이터를 포함하지 마세요. 이벤트는 기본 시크릿과 같은 정책으로 보호되지 않아요.
읽기가 아니라 쓰기와 실행 가능한 오류에 대해서만 이벤트 알림을 생성하세요. 일반적으로 읽기는 쓰기보다 더 빈번하므로 모든 읽기 작업에 대해 이벤트 알림을 생성하면 서버 성능에 부정적인 영향을 줄 수 있어요. 정보가 읽힐 때 알림을 받아야 하는 운영자는 Vault 감사 로그를 사용하는 것이 더 나아요.
다른 플러그인의 이벤트 유형과 충돌하지 않도록 이벤트 유형 앞에 플러그인 이름을 붙이세요. 예를 들어 데이터베이스 플러그인은 모든 이벤트 알림에 database/ 프리픽스를 사용해요.
data_path(이벤트 알림이 관련된 시크릿의 API 경로)와 operation(어떤 수정이 일어났는지 표시) 같은 공통 메타데이터 키를 사용하세요.
플러그인이 생성하는 이벤트 유형을 문서화하세요. 언제 생성되는지에 대한 설명도 포함하세요.
이벤트 알림을 보내려면 logical.SendEvent()를 사용하세요. framework.Backend 또는 gRPC 메서드를 직접 호출해 이벤트 알림을 보내는 것도 가능하지만, logical.SendEvent가 그 중 많은 부분을 추상화해 줘요.
메서드 끝이나 defer에서 이벤트 알림을 보내 이벤트 알림이 가장 최신 정보를 갖도록 하세요.
이벤트 알림 시스템을 사용할 수 없으면 정상적으로 실패(fail gracefully)하세요. 이는 이벤트 전송 시 오류(예: framework.ErrNoEvents)로 감지되며, 보통 이벤트 알림이 없거나 비활성화된 이전 Vault 버전에서 실행될 때 발생해요.
모든 Vault 에디션에서 이벤트를 생성하세요. Vault Community Edition에서는 이벤트 알림을 구독할 수 없지만, 플러그인은 일반적으로 연결된 Vault 에디션을 알지 못하므로 상관없이 이벤트를 생성해야 해요.

예시

Vault의 KV 및 데이터베이스 플러그인에 이벤트 알림을 추가하는 몇 가지 예시가 있어요.

더 알아보기 (Learn more)

플러그인 개발