튜토리얼: Getter 플러그인 만들기

helm system-info 명령을 만들어 시스템 정보를 표시해 봐요.

출처: 문서

본문

Subprocess 런타임

Subprocess 런타임으로 Getter 플러그인을 만들어 볼게요.

사전 준비

최신 Helm 4 릴리스인 v4.3.0 을 설치해요.
터미널 세션에서 내려 받은 릴리스로 helm을 alias 처리해요. helm version --short가 지금 터미널 세션에서 올바른 Helm 버전을 표시하면 돼요.

1. 플러그인 디렉터리 만들기

파일 시스템 어디에든 만들 수 있어요. 예를 들면:

mkdir -p $HOME/code/helm/plugins/demo-getter
cd $HOME/code/helm/plugins/demo-getter

2. 플러그인 매니페스트 만들기

plugin.yaml

apiVersion: v1
type: getter/v1
name: demo-getter
version: 0.1.0
runtime: subprocess
config:
  protocols: ["demo"]
runtimeConfig:
  protocolCommands:
    - protocols:
        - demo
      platformCommand:
        - command: get-demo.sh

3. 스크립트 만들기

Getter 플러그인은 패키징된 아티팩트(이 경우엔 차트)를 받아 와서 내려 받은 패키지의 경로를 반환하는 일을 담당해요. 데모 목적으로 시스템 유틸리티로 임시 디렉터리를 만들고(시간이 지나면 자동으로 정리돼요), helm create와 helm package 명령으로 임시 디렉터리에 데모 차트 패키지를 만든 뒤 그 패키지 경로를 반환해 볼게요:

get-demo.sh

#!/usr/bin/env sh
set -e

URI=$@
TMPDIR="$(mktemp -d)"

# make a fake chart for testing with the passed URL basename
FILENAME=$(basename -- $URI)
helm create $TMPDIR/$FILENAME 1>/dev/null
helm package $TMPDIR/$FILENAME -d $TMPDIR 1>/dev/null
# cat $FILENAME-0.1.0.tgz
# just to not need to know the chart version
rm -r $TMPDIR/$FILENAME 1>/dev/null
cat $TMPDIR/$FILENAME-*

실행 가능하게 만들어요:

chmod +x get-demo.sh

4. 개발 모드로 설치하고 테스트하기

파일 시스템에서 플러그인을 설치하면 로컬 개발 모드로 설치되며, 이 방식은 프러비넌스를 확인하지 않아요:

% helm plugin install $HOME/code/helm/plugins/demo-getter
Installing plugin from local directory (development mode)
Installed plugin: demo-getter

CLI 플러그인 튜토리얼에서 봤듯이, 로컬 개발 모드 설치는 플러그인 소스 디렉터리에서 플러그인 디렉터리로 심링크를 만들어 줘요. 이제 두 개의 플러그인이 설치돼 있어요:

% ls -lah $(helm env HELM_PLUGINS)
total 0
drwxr-xr-x@ 4 r6by  staff   160B Nov 10 04:04 .
drwxr-xr-x@ 3 r6by  staff    96B Jan 21  2025 ..
lrwxr-xr-x  1 r6by  staff    41B Nov 10 04:04 demo-getter -> /Users/r6by/code/helm/plugins/demo-getter
lrwxr-xr-x  1 r6by  staff    41B Nov 10 02:18 system-info -> /Users/r6by/code/helm/plugins/system-info

CLI 플러그인 튜토리얼과 달리, 이 플러그인은 helm help의 사용 가능한 명령 목록에는 나타나지 않아요. helm CLI 하위 명령 목록에는 cli/v1 타입만 보이기 때문이에요.

하지만 모든 플러그인 타입처럼, 설치된 Getter 플러그인 상세 정보는 helm plugin list로 확인할 수 있어요:

% helm plugin list
NAME          \tVERSION\tTYPE           \tAPIVERSION\tPROVENANCE\tSOURCE
demo-getter   \t0.1.0  \tgetter/v1      \tv1        \tlocal dev \tunknown
system-info   \t0.1.0  \tcli/v1         \tv1        \tlocal dev \tunknown

실행해 볼게요. "example"이라는 이름의 차트에 대한 템플릿 YAML을 반환해야 해요:

% helm template example demo://does-not-matter/example
LOTS OF YAML, INCLUDING:
---
# Source: example/templates/tests/test-connection.yaml

만든 것: Subprocess 런타임을 쓰는 데모 Getter 플러그인!

이번에는 Wasm 런타임 버전을 만들어 볼게요…

Wasm 런타임

사전 준비

Subprocess 런타임의 사전 준비 사항
Go 1.25 설치

demo:// URL을 https://로 변환하는 커스텀 프로토콜 getter를 만들어 봐요.

1. 저장소 준비

템플릿에서 새 저장소를 스캐폴드해요 (아니면 그냥 clone 해도 돼요): https://github.com/gjenkins8/helm-extism-plugin-template

2. 플러그인 매니페스트 갱신

Subprocess Getter의 동일한 단계와 비슷한데, 직접 clone한 Git 저장소 안에서 진행해요.

Wasm에서는 runtime과 runtimeConfig 필드 값이 달라진다는 점을 주의해요:

plugin.yaml

apiVersion: v1
type: getter/v1
name: demo-getter
version: 0.1.0
runtime: extism/v1
config:
  protocols: ["demo"]
runtimeConfig:
  memory:
    maxPages: 16
  timeout: 30000

3. `main.go` 갱신

플러그인의 입력/출력 메시지를 지정해요:

main.go

package main

...

type InputMessage struct {
	URL      string `json:"url"`
	Protocol string `json:"protocol"`
}

type OutputMessage struct {
	Data []byte `json:"data"`
}

replaceMeImplementationGoesHere 함수를 실제 로직으로 교체해요:

...

// Delete the `replaceMeImplementationGoesHere` function

func demoDownloader(input InputMessage) (*OutputMessage, error) {

	// Convert demo:// to https://
	downloadURL := strings.Replace(input.URL, "demo://", "https://", 1)
	pdk.Log(pdk.LogLevelInfo, fmt.Sprintf("Converted %s to %s", input.URL, downloadURL))

	// Download content
	resp, err := http.Get(downloadURL)
	if err != nil {
		return nil, fmt.Errorf("failed to download: %w", err)
	}
	defer resp.Body.Close()

	// Read and output content
	data, _ := io.ReadAll(resp.Body)
	output := OutputMessage{Data: data}
	return &output, nil
}

대신 demoDownloader를 호출하도록 runPlugin 함수를 갱신해요:

func runPlugin() error {
	...
	// Remove: output, err := replaceMeImplementationGoesHere(input)
	output, err := demoDownloader(input)

4. WebAssembly 빌드

$ make build
$ ls -la plugin.wasm

5. 개발 모드로 설치하고 테스트하기

Subprocess CLI 플러그인 단계와 동일해요.

만든 것: Extism PDK로 샌드박스 실행과 구조화된 통신을 제공하는 WebAssembly 플러그인!

튜토리얼: Getter 플러그인 만들기