플러그인 개발

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

출처: 문서

본문

Vault는 RPC 인터페이스를 통해 플러그인과 통신하므로 Vault 자체를 다시 빌드하지 않고도 Vault용 플러그인을 빌드하고 배포할 수 있어요. 이를 통해 조직의 내부 용도로, 오픈소스로 공개하고 싶지 않은 독점 API용으로, 또는 메인 프로젝트에 기여하기 전에 모조(mockup)를 만들어보기 위해 Vault 플러그인을 쉽게 빌드할 수 있어요.

이론적으로 플러그인 인터페이스가 HTTP이므로 완전히 다른 프로그래밍 언어로도 플러그인을 개발할 수 있어요! (단, 플러그인 API를 다시 구현해야 하며 이는 사소한 작업이 아닙니다.)

플러그인 개발은 간단해요. 플러그인을 작성하는 데 필요한 지식은 기본적인 명령줄 기술과 Go 프로그래밍 언어의 기본 지식뿐이에요.

플러그인 구현은 빌드하려는 플러그인 유형의 인터페이스를 충족해야 해요. 이러한 정의는 플러그인을 실행하는 백엔드의 문서에서 찾을 수 있어요.

참고: 플러그인은 Vault의 여러 동시 요청을 처리할 준비가 되어 있어야 해요.

플러그인 서빙

멀티플렉싱으로 플러그인 서빙

멀티플렉싱 플러그인은 공식 Vault 플러그인 또는 dbplugin SDK 패키지의 ServeMultiplex 함수 호출을 사용해야 해요. 현재 멀티플렉싱을 구현하는 플러그인에는 옵트아웃 기능이 없어요. 멀티플렉싱되지 않은 플러그인을 사용하려면 플러그인의 이전 버전, 즉 플러그인이 Serve 함수를 호출하는 버전을 실행하세요.

플러그인 멀티플렉싱에는 github.com/hashicorp/vault/sdk v0.5.4 이상이 필요해요.

다음 코드는 시크릿 엔진 또는 인증 메서드용 Vault SDK를 사용하는 Vault 플러그인의 예시 main 패키지를 보여줘요.

package main

import (
    "os"

    myPlugin "your/plugin/import/path"
    "github.com/hashicorp/vault/api"
    "github.com/hashicorp/vault/sdk/plugin"
)

func main() {
    apiClientMeta := &api.PluginAPIClientMeta{}
    flags := apiClientMeta.FlagSet()
    flags.Parse(os.Args[1:])

    tlsConfig := apiClientMeta.GetTLSConfig()
    tlsProviderFunc := api.VaultPluginTLSProvider(tlsConfig)

    err := plugin.ServeMultiplex(&plugin.ServeOpts{
        BackendFactoryFunc: myPlugin.Factory,
        TLSProviderFunc:    tlsProviderFunc,
    })
    if err != nil {
        logger := hclog.New(&hclog.LoggerOptions{})

        logger.Error("plugin shutting down", "error", err)
        os.Exit(1)
    }
}

그리고 그게 기본적으로 전부예요! myPlugin을 실제 플러그인으로 바꾸기만 하면 돼요.

Vault와의 플러그인 하위 호환성

위 main 패키지의 스니펫을 자세히 살펴봐요.

    err := plugin.ServeMultiplex(&plugin.ServeOpts{
        BackendFactoryFunc: myPlugin.Factory,
        TLSProviderFunc:    tlsProviderFunc,
    })

plugin.ServeMultiplex 호출은 플러그인이 Vault의 플러그인 멀티플렉싱 기능을 사용하도록 보장해요. 그러나 이 플러그인이 멀티플렉싱을 지원하지 않는 Vault 버전으로 실행되면 멀티플렉싱되지 않아요. Vault는 단순히 실행할 수 있는 플러그인 버전으로 폴백해요. 또한 TLSProviderFunc를 설정해 보안 플러그인 통신을 위한 자동 상호 TLS를 지원하지 않는 Vault 버전과 플러그인이 하위 호환되도록 보장해요. 하위 호환성이 필요하지 않다고 확신한다면 이 필드는 생략할 수 있어요.

플러그인 버저닝 활용

플러그인은 선택적으로 자신의 시맨틱 버전을 자체 보고할 수 있어요. 그렇게 하는 플러그인의 경우 Vault는 사용자가 버전을 제공할 필요 없이 카탈로그에 플러그인 버전을 자동으로 채워요. 등록 중에 사용자가 버전을 제공하면, 제공된 버전이 플러그인이 보고하는 버전과 일치하지 않으면 Vault는 오류를 반환해요. 비어 있지 않은 버전을 보고하는 플러그인은 선행 'v'가 추가된 유효한 시맨틱 버전을 보고해야 해요. 그렇지 않으면 등록이 실패해요. 예: v1.0.0 또는 v2.3.2-beta.

이 동작을 선택하려는 플러그인은 version 인터페이스를 구현할 수 있어요. 그러나 필수는 아니며, 플러그인이 version 인터페이스를 구현하지 않아도 등록 중에 버전을 제공할 수 있어요.

version 인터페이스를 구현하려면 플러그인이 먼저 Vault SDK 패키지를 최소 v0.6.0으로 업그레이드해야 해요.

SDK의 framework.Backend 기반 auth 및 secrets 플러그인은 RunningVersion 변수를 설정해야 하며, 프레임워크가 version 인터페이스를 구현해요.

데이터베이스 플러그인은 framework.Backend가 노출하는 API보다 작으므로 대신 PluginVersioner 인터페이스를 직접 구현해야 해요.

플러그인 로깅

SDK의 framework.Backend 기반 auth 및 secrets 플러그인은 SDK의 기본 로거를 활용할 수 있어요. 추가 설정이 필요 없어요. 로거는 다음과 같이 사용할 수 있어요.

func (b *backend) example() {
    b.Logger().Trace("Trace level log")
    b.Logger().Debug("Debug level log")
    b.Logger().Info("Info level log")
    b.Logger().Warn("Warn level log")
    b.Logger().Error("Error level log")
}

로깅을 사용하는 플러그인의 더 완전한 예시는 vault-auth-plugin-example의 소스 코드를 참조하세요.

소스에서 플러그인 빌드

소스에서 플러그인을 빌드하려면 먼저 원하는 플러그인 버전이 있는 위치로 이동하세요. 다음으로 go build를 실행해 플러그인의 새 바이너리를 얻으세요. 마지막으로 플러그인을 등록하고 활성화하세요.