플러그인 개요

플러그인 개요

Helm 플러그인은 사용자가 Helm의 핵심 기능을 확장할 수 있게 해 줘요. 모든 새 기능을 Go로 작성해 Helm 코어에 추가할 필요가 없어요.

어떤 프로그래밍 언어로도 작성할 수 있고, Helm 코어 기능을 망가뜨리지 않고도 Helm 설치에서 추가/제거할 수 있어요.

출처: 문서

본문

플러그인 타입

Helm에는 현재 3가지 타입의 플러그인이 있어요:

  • CLI 플러그인: 사용자가 추가적인 helm CLI 하위 명령을 만들 수 있어요

  • Getter 플러그인: Helm 코어가 기본 지원하지 않는 위치에 있는 차트나 다른 플러그인을 사용할 수 있게 해 줘요

  • Postrenderer 플러그인: 차트가 렌더링한 매니페스트를 Kubernetes API로 보내기 전에 수정할 수 있어요

Helm 4부터 플러그인 시스템은 추가 플러그인 타입을 더 쉽게 추가할 수 있도록 설계됐어요. 이를 통해 사용자가 Helm 기능의 다른 영역도 수정할 수 있어요.

CLI 플러그인

별도의 스크립트나 독립 명령을 가진 도구 대신 플러그인으로 helm CLI 하위 명령을 만드는 것의 장점은 무엇일까요?

주된 이유는 helm CLI 하위 명령을 추가하는 플러그인이 Helm 특유의 설정·컨텍스트·기능을 활용할 수 있기 때문이에요. 독립 스크립트나 도구는 이런 것들을 직접 개발해야 해요. 플러그인은 helm CLI 사용자 워크플로우를 더 매끄럽게 확장할 수 있게 해 줘요.

Getter 플러그인

Helm은 차트와 플러그인을 로컬 파일 시스템이나 OCI 레지스트리의 아티팩트로 다루는 것을 기본 지원해요. 차트는 HTTP 저장소에도, 플러그인은 Git 같은 VCS 저장소에도 추가로 저장할 수 있어요.

Helm Getter 플러그인은 이런 저장·다운로드 동작을 다른 저장 위치까지 확장할 수 있게 해 줘요. 커뮤니티에서 차트와 플러그인을 s3 버킷 등에 저장하는 Getter 플러그인을 제공하고 있어요. Helm 워크플로우에 추가 저장 옵션이 필요하다면 Getter 플러그인을 쓰면 돼요.

PostRenderer 플러그인

Helm은 사용자가 커스텀 값을 제공해 차트를 구성할 수 있게 해 줘요. 이 사용자 제공 값은 차트가 매니페스트를 렌더링하는 데 사용하며, Helm이 Kubernetes에서 애플리케이션을 관리하도록 해 줘요.

자신의 차트를 작성한다면 렌더링된 매니페스트에 추가 설정이 필요할 때마다 템플릿을 갱신하면 돼요. 하지만 소유하지 않은 커뮤니티 차트를 사용한다면, post-rendering을 통해 차트가 매니페스트를 렌더링한 뒤 Helm이 Kubernetes 리소스를 관리하는 데 사용하기 전에 매니페스트를 수정할 수 있어요. Helm 4부터는 postrenderer 플러그인이 이 방법이에요.

플러그인 API 버전

Helm 4부터 모든 플러그인에 포함되는 plugin.yaml 파일에는 apiVersion 필드가 있으며, 현재 v1이에요.

API 버전링 이전의 레거시 플러그인은 Helm 4 생애 동안 계속 지원돼요. 그래서 Helm 3의 기존 플러그인은 Helm 5까지 계속 동작해요. 하지만 즐겨 쓰는 플러그인의 작성자에게 새 버전 시스템으로 갱신해 달라고 요청해야 해요.

플러그인 개발자라면 플러그인 개발자 가이드에서 더 자세히 읽어 보세요.

플러그인 런타임

Helm은 현재 2가지 플러그인 런타임을 지원해요:

  • Subprocess 런타임

  • Wasm 런타임

각 런타임에 대한 자세한 정보는 플러그인 사용자 가이드나 플러그인 개발자 가이드에서 확인할 수 있어요.

파일 구조

플러그인의 모든 파일은 단일 디렉터리에 모여 있어요. 개발·패키징·설치에 사용돼요.

플러그인 디렉터리 안에서 Helm은 다음 구조를 기대해요:

example-plugin
├── plugin.yaml # REQUIRED
├── plugin.sh   # OPTIONAL for Subprocess runtime
└── plugin.wasm # REQUIRED for Wasm runtime

  • 필수 파일은 plugin.yaml뿐이에요.

  • Subprocess 런타임은 플러그인 코드를 담은 실행 파일을 하나 이상 선택적으로 포함할 수 있어요 (Node, Python, Go 등). 이 런타임에서는 사용자의 PATH에 이미 있는 실행 파일을 plugin.yaml 런타임 설정의 platformCommand 필드에서 직접 호출할 수도 있어요.

  • Wasm 런타임에서는 .wasm 파일을 포함해야 해요. 이것이 플러그인 코드(Node, Python, Go 등)를 Wasm으로 컴파일한 것이에요.

Plugin.yaml

플러그인에 plugin.yaml 파일은 필수예요. 플러그인의 메타데이터와 설정을 담은 YAML 파일이에요.

메타데이터 정보

apiVersion: REQUIRED - The Plugin API version. Must be "v1"
type: REQUIRED - The versioned Plugin Type. Can be "cli/v1", "getter/v1", or "postrenderer/v1"
name: REQUIRED - The name of the plugin
version: REQUIRED - The version of the plugin
runtime: REQUIRED - The runtime for the plugin. Can be "subprocess" or "extism/v1" (Wasm)
sourceURL: OPTIONAL - A URL pointing to the source code for your plugin
config: DEPENDS ON PLUGIN TYPE
runtimeConfig: DEPENDS ON RUNTIME

  • config 필드는 플러그인 타입 설정을 위한 것이며, type 필드로 정의되는 플러그인 타입마다 구조가 달라요.

  • runtimeConfig 필드는 런타임 설정을 위한 것이며, runtime 필드로 정의되는 런타임마다 구조가 달라요.

  • 💡 sourceURL 필드는 선택 사항이지만, 플러그인 작성자는 소스 코드를 가리킬 것을 강력히 권장해요. 사용자가 코드가 무엇을 하는지 이해하고, 오픈소스 기여를 받는다면 기여하는 데 도움이 되기 때문이에요.

플러그인 타입 설정

plugin.yaml의 config 필드는 플러그인 타입마다 옵션이 달라요. 플러그인의 타입은 type 필드로 정의돼요.

CLI 플러그인 설정

type 필드가 cli/v1이면 CLI 플러그인 타입이며, 다음 플러그인 타입 설정이 허용돼요:

usage: OPTIONAL - The single-line usage text shown in help
shortHelp: The short description shown in the 'helm help' output
longHelp: The long message shown in the 'helm help <this-command>' output
ignoreFlags: Ignores any flags passed in from Helm

  • usage는 선택 사항이에요. 커스텀 usage 문자열로 덮어쓰지 않았다면 기본값은 helm PLUGIN_NAME [flags]예요. 권장 구문은 spf13/cobra.command.Command의 Use 필드 주석을 참고해요.

  • ignoreFlags 스위치는 Helm이 플래그를 플러그인에 전달하지 않도록 해 줘요. 그래서 helm myplugin --foo로 호출했을 때 ignoreFlags: true라면 --foo는 조용히 버려져요.

Getter 플러그인 설정

type 필드가 getter/v1이면 Getter 플러그인 타입이며, 다음 플러그인 타입 설정이 허용돼요:

protocols: The list of schemes from the charts URL that this plugin supports.

Postrenderer 플러그인 설정

type 필드가 postrenderer/v1이면 Postrenderer 플러그인 타입이며, 설정 옵션이 없어요.

런타임 설정

plugin.yaml의 runtimeConfig 필드는 플러그인 런타임마다 옵션이 달라요. 플러그인의 런타임은 runtime 필드로 정의돼요.

Subprocess 런타임 설정

runtime 필드가 subprocess이면 Subprocess 런타임 플러그인이며 다음 런타임 설정이 허용돼요:

runtimeconfig:
    platformCommand: # Configure command to run based on the platform
        - os: OS match, can be empty or omitted to match any OS
          arch: Architecture match, can be empty or omitted to match any architecture
          command: Plugin command to execute
          args: Plugin command arguments
    platformHooks: # Configure plugin lifecycle hooks based on the platform
        install: # Install lifecycle commands
            - os: OS match, can be empty or omitted to match any OS
              arch: Architecture match, can be empty or omitted to match any architecture
              command: Plugin install command to execute
              args: Plugin install command arguments
        update: # Update lifecycle commands
            - os: OS match, can be empty or omitted to match any OS
              arch: Architecture match, can be empty or omitted to match any architecture
              command: Plugin update command to execute
              args: Plugin update command arguments
        delete: # Delete lifecycle commands
            - os: OS match, can be empty or omitted to match any OS
              arch: Architecture match, can be empty or omitted to match any architecture
              command: Plugin delete command to execute
              args: Plugin delete command arguments
    protocolCommands: # Obsolete/deprecated
        - protocols: [] # Protocols are the list of schemes from the charts URL.
          platformCommand: [] # Same structure as "platformCommand" above
  • ⚠️ protocolCommands는 obsolete/deprecated로 표시되며, apiVersion: v1 이후 플러그인 시스템의 향후 버전에서 제거될 거예요. getter/v1 플러그인 타입에만 적용돼요. 이것은 하나의 플러그인에서 여러 프로토콜을 지원하도록 확장된 옛 플러그인 다운로더 메커니즘에서 물려받은 호환성 잔재예요. platformCommand에 제공된 명령은 다운로드 URL을 검사해 프로토콜별 로직을 구현해야 해요.

Wasm 런타임 설정

runtime 필드가 extism/v1이면 Wasm 런타임 플러그인이며 다음 런타임 설정이 허용돼요:

runtimeconfig:
    memory: # Describes the limits on the memory the plugin may be allocated
        maxPages: The max amount of pages the plugin can allocate. One page is 64Kib. e.g. 16 pages would require 1MiB. Default is 4 pages (256KiB).
        maxHttpResponseBytes: The max size of an Extism HTTP response in bytes. Default is 4096 bytes (4KiB).
        maxVarBytes: The max size of all Extism vars in bytes. Default is 4096 bytes (4KiB).
    config: {} # A free-form map that can be passed to the plugin.
    allowedHosts: [] # An optional set of hosts this plugin can communicate with. Defaults to no hosts allowed.
    fileSystem:
        createTempDir: Whether to create a temporary directory on the filesystem. Can be "true" or "false".
    timeout: The timeout in milliseconds for the plugin to execute
    hostFunctions: HostFunction names exposed in Helm the plugin may access. See https://extism.org/docs/concepts/host-functions/
    entryFuncName: The name of entry function name to call in the plugin. Defaults to "helm_plugin_main".

  • allowedHosts는 플러그인이 HTTP 요청을 하는 경우에만 효과가 있어요. 지정하지 않으면 어떤 호스트도 허용되지 않아요.

  • usage의 기본값: 커스텀으로 지정하지 않으면 helm PLUGIN_NAME [flags]로 표시돼요.

더 알아보기 (Learn more)