Helm 3 플러그인을 Helm 4로 마이그레이션하기

Helm 3 플러그인을 Helm 4로 마이그레이션하기

Helm 4는 재설계된 플러그인 시스템을 도입했어요. 버전 관리된 API 지원, 명시적 플러그인 타입, 선택적 Wasm 런타임이 포함돼요. 기존 Helm 3 플러그인은 subprocess 런타임을 쓰는 플러그인을 포함해 Helm 4에서도 계속 동작해요. 허용되지 않는 것은 버전 관리되지 않는 Helm 3 plugin.yaml 스키마예요. 이 가이드는 Helm 3 플러그인을 버전 관리된 apiVersion: v1 스키마로 갱신하는 절차를 안내해요.

출처: 문서

본문

시작하기 전에

필요한 것:

  • Helm 4 설치 (helm version이 v4.x를 표시해야 해요)

  • 마이그레이션할 기존 Helm 3 플러그인

  • 플러그인의 plugin.yaml 파일에 대한 이해

플러그인이 어떤 범주에 속하는지 파악해요:

플러그인이 하는 일... Helm 4 타입
helm CLI 하위 명령을 추가함 cli/v1
커스텀 프로토콜(s3, git 등)로 차트를 내려 받음 getter/v1
설치 전에 렌더링된 매니페스트를 수정함 postrenderer/v1

:::warning Post-renderer의 변경점 Helm 3에서 helm install --post-renderer는 실행 파일 경로를 받아들였어요. Helm 4에서는 플러그인 이름을 요구해요. 실행 파일 경로를 직접 전달하는 post-renderer 워크플로우를 유지한다면, 그것을 postrenderer/v1 플러그인으로 패키징하고 --post-renderer에 플러그인 이름을 전달해야 해요. 자세한 내용은 Helm 4 개요를 참고하세요. :::

plugin.yaml에서 바뀐 것

아래 표는 레거시 필드를 v4 대응 필드로 매핑한 것이에요.

레거시 필드 v4 대응 설명
(없음) apiVersion: v1 새 필수 필드
(없음) type: cli/v1 새 필수 필드. cli/v1, getter/v1, postrenderer/v1 중 하나 사용
(없음) runtime: subprocess 새 필수 필드. subprocess 또는 extism/v1 사용
name name 동일
version version 동일
usage config.usage CLI 플러그인의 경우 config 아래로 이동
description config.shortHelp 이름이 바뀌고 config 아래로 이동. 선택적으로 shortHelp(간단, helm help에 표시)와 longHelp(상세, helm help <plugin>에 표시)로 나눌 수 있음
(없음) config.longHelp CLI 플러그인의 새 선택 필드. helm help <plugin>에 표시되는 상세 도움말 텍스트에 사용
ignoreFlags config.ignoreFlags CLI 플러그인의 경우 config 아래로 이동
platformCommand runtimeConfig.platformCommand runtimeConfig 아래로 이동
platformHooks runtimeConfig.platformHooks runtimeConfig 아래로 이동
command (deprecated) 대신 runtimeConfig.platformCommand 사용
hooks (deprecated) 대신 runtimeConfig.platformHooks 사용
downloaders config.protocols + runtimeConfig.protocolCommands getter 플러그인의 경우 config와 runtimeConfig로 분리. protocolCommands는 deprecated지만 현재 subprocess getter의 문서화된 패턴

경로 1: Subprocess 마이그레이션 (가장 빠름)

플러그인을 subprocess로 계속 실행하고 싶다면(컴파일 불필요), plugin.yaml만 재구성하면 돼요. 실행 파일 자체는 바뀌지 않아요.

예시: CLI 플러그인

변경 전 (Helm 3):

name: myplugin
version: 0.2.0
usage: "do something useful"
description: "A plugin that does something useful"
ignoreFlags: false
platformCommand:
  - command: ${HELM_PLUGIN_DIR}/bin/myplugin
  - os: windows
    command: ${HELM_PLUGIN_DIR}\bin\myplugin.exe
platformHooks:
  install:
    - command: ${HELM_PLUGIN_DIR}/scripts/install.sh
    - os: windows
      command: pwsh
      args:
        - -c
        - ${HELM_PLUGIN_DIR}\scripts\install.ps1

변경 후 (Helm 4, subprocess):

apiVersion: v1
type: cli/v1
name: myplugin
version: 0.2.0
runtime: subprocess
sourceURL: https://github.com/example/helm-myplugin
config:
  usage: "do something useful"
  shortHelp: "A plugin that does something useful"
  ignoreFlags: false
runtimeConfig:
  platformCommand:
    - command: ${HELM_PLUGIN_DIR}/bin/myplugin
    - os: windows
      command: ${HELM_PLUGIN_DIR}\bin\myplugin.exe
  platformHooks:
    install:
      - command: ${HELM_PLUGIN_DIR}/scripts/install.sh
      - os: windows
        command: pwsh
        args:
          - -c
          - ${HELM_PLUGIN_DIR}\scripts\install.ps1

주요 변경점은: 최상위에 apiVersion, type, runtime을 추가하고, 투명성을 위해 선택적으로 sourceURL도 그곳에 추가하며, usage, description(이제 shortHelp), ignoreFlags를 config 아래에 중첩하고, platformCommand와 platformHooks를 runtimeConfig 아래에 중첩하는 거예요.

예시: Getter 플러그인 (구 "downloader")

변경 전 (Helm 3):

name: s3
version: 1.2.0
usage: "fetch charts from S3"
description: "Downloader plugin for S3 chart repos"
downloaders:
  - command: "bin/s3downloader"
    protocols:
      - "s3"

변경 후 (Helm 4, subprocess):

apiVersion: v1
type: getter/v1
name: s3
version: 1.2.0
runtime: subprocess
sourceURL: https://github.com/example/helm-s3
config:
  protocols:
    - "s3"
runtimeConfig:
  protocolCommands:
    - protocols:
        - s3
      platformCommand:
        - command: ${HELM_PLUGIN_DIR}/bin/s3downloader

downloaders 블록은 config.protocols(플러그인이 처리하는 URL 스킴을 선언)와 runtimeConfig.protocolCommands(각 프로토콜을 플랫폼 명령에 매핑)로 대체돼요.

주의: infoprotocolCommands 필드는 개요 스펙에서 deprecated로 표시되며 apiVersion: v1 이후 제거될 예정이에요. 향후 버전은 runtimeConfig.platformCommand를 직접 사용하고, 플러그인 자체가 다운로드 URL을 검사해 프로토콜 로직을 결정해야 해요. 당분간 protocolCommands는 공식 튜토리얼이 subprocess getter에 가르치는 패턴이에요.

경로 2: Wasm 마이그레이션

Wasm 샌드박스를 활용하고 싶다면, 플러그인 언어의 Extism PDK를 사용해 플러그인을 .wasm 바이너리로 컴파일해야 해요. Go 플러그인의 가장 흔한 선택은 Extism Go PDK예요.

처음부터 Wasm 플러그인을 만드는 단계별 지침은 Getter 플러그인 Wasm 튜토리얼을 참고하세요. 현재 문서에서 가장 완전한 Wasm 예제예요. Extism 플러그인 템플릿에서 새 Wasm 플러그인을 스캐폴드할 수도 있어요.

주의: infoCLI와 Postrenderer Wasm 튜토리얼 섹션은 아직 진행 중이에요. 업데이트는 플러그인 개발 페이지를 확인하세요.

위의 subprocess 버전과 비교해 plugin.yaml이 어떻게 바뀌는지 보여드릴게요:

apiVersion: v1
type: cli/v1
name: myplugin
version: 0.2.0
runtime: extism/v1
sourceURL: https://github.com/example/helm-myplugin
config:
  usage: "do something useful"
  shortHelp: "A plugin that does something useful"
  ignoreFlags: false
runtimeConfig:
  memory:
    maxPages: 16
  allowedHosts:
    - "api.example.com"
  timeout: 30000

subprocess 버전과의 주요 차이:

  • runtime이 subprocess에서 extism/v1으로 바뀌어요.

  • runtimeConfig가 platformCommand 대신 Wasm 특유의 필드(memory, allowedHosts, timeout)를 사용해요.

  • platformCommand나 platformHooks가 없어요 — Helm이 플러그인 디렉터리의 plugin.wasm에서 Wasm 바이너리를 로드해요.

  • 플러그인 디렉터리가 플랫폼별 실행 파일 대신 plugin.wasm을 담아요.

마이그레이션한 플러그인 서명하기

Helm 4는 플러그인에 내장된 프러비넌스 서명·검증을 추가해요. 플러그인을 배포할 때 서명해요:

helm plugin package --sign --key "your-key-id" ./myplugin

사용자는 설치 중에 플러그인을 검증할 수 있어요:

helm plugin install https://example.com/myplugin.tgz --verify

플러그인 tarball의 경우 검증이 기본적으로 활성화돼요. 자세한 내용은 플러그인 보안을 참고하세요.

하위 호환성

apiVersion이 없는 레거시 플러그인은 Helm 4에서 계속 동작해요. Helm이 레거시 형식을 자동 감지해 레거시 subprocess 핸들러로 라우팅해요. 하지만:

  • 레거시 플러그인은 Helm 4에서 deprecated예요.

  • 레거시 플러그인 지원은 Helm 5에서 제거될 거예요.

  • 새 플러그인 기능(Wasm 런타임, 프러비넌스 서명, 새 플러그인 타입)은 apiVersion: v1에서만 사용할 수 있어요.

Helm 5를 대비하고 새 시스템의 보안 이점을 사용자에게 제공하려면 지금 플러그인을 마이그레이션하세요.

더 알아보기 (Learn more)