Starlark Dev

Kurtosis Starlark パッケージを作成、デバッグ、テストします。

パッケージ構造

最小限の Kurtosis パッケージには 2 つのファイルが必要です:

my-package/
  kurtosis.yml    # Package metadata
  main.star       # Entry point

kurtosis.yml

name: github.com/your-org/my-package

main.star

def run(plan, args):
    plan.add_service(
        name="my-service",
        config=ServiceConfig(
            image="nginx:latest",
            ports={
                "http": PortSpec(number=80, transport_protocol="TCP"),
            },
        ),
    )

パッケージの実行

# ローカルパッケージを実行
kurtosis run ./my-package

# パラメータを指定して実行
kurtosis run ./my-package '{"param1": "value1"}'

# GitHub からリモートパッケージを実行
kurtosis run github.com/ethpandaops/ethereum-package

# カスタムコンフィグファイルを指定して実行
kurtosis run github.com/ethpandaops/ethereum-package --args-file config.yaml

# ドライラン(プランのみ、実行なし)
kurtosis run ./my-package --dry-run

実行モデル

Kurtosis Starlark は 2 つのフェーズで実行されます:

1. 計画フェーズ — コードが実行され、アクションの計画が構築されます。add_service()、exec() などはすぐには実行されず、フューチャーリファレンスを返します。
2. 実行フェーズ — 計画が順序に従って実行されます。フューチャーリファレンスは実際の値に解決されます。

つまり、計画フェーズ中に plan.exec() の戻り値を Python レベルのロジック(if/else など)で使用することはできません。代わりに plan.verify() または plan.assert() を使用してください。

# 間違い: result は計画フェーズ中のフューチャーリファレンスで、実際の値ではない
result = plan.exec(service_name="my-service", recipe=ExecRecipe(command=["echo", "hello"]))
if result["output"] == "hello":  # これは期待通りに動作しません
    plan.print("matched")

# 正しい: 条件チェックに plan.verify を使用
result = plan.exec(service_name="my-service", recipe=ExecRecipe(command=["echo", "hello"]))
plan.verify(result["exit_code"], "==", 0)

print でのデバッグ

def run(plan, args):
    plan.print("Args received: {}".format(args))

    service = plan.add_service(
        name="my-service",
        config=ServiceConfig(image="nginx:latest"),
    )
    plan.print("Service IP: {}".format(service.ip_address))
    plan.print("Service hostname: {}".format(service.hostname))

よく使われるパターン

サービスの準備状況を待機

plan.wait(
    service_name="my-service",
    recipe=GetHttpRequestRecipe(port_id="http", endpoint="/health"),
    field="code",
    assertion="==",
    target_value=200,
    timeout="60s",
)

サービス内でコマンドを実行

result = plan.exec(
    service_name="my-service",
    recipe=ExecRecipe(command=["cat", "/etc/hostname"]),
)
plan.verify(result["exit_code"], "==", 0)
plan.print("Hostname: {}".format(result["output"]))

ファイルをアップロード

config_template = read_file("./templates/config.toml")
artifact = plan.render_templates(
    name="my-config",
    config={
        "config.toml": struct(
            template=config_template,
            data={"key": "value"},
        ),
    },
)

plan.add_service(
    name="my-service",
    config=ServiceConfig(
        image="my-image:latest",
        files={"/etc/myapp": artifact},
    ),
)

他のパッケージからインポート

dependency = import_module("github.com/org/other-package/lib.star")

def run(plan, args):
    dependency.some_function(plan)

テスト

ドライラン → 実行 → 検証のワークフローを使用します:

# 1. 実行せずにプランを検証
kurtosis run --dry-run ./my-package

# 2. 実行して出力を確認
kurtosis run ./my-package

# 3. 作成されたエンクレーブを検査
kurtosis enclave inspect <enclave-name>

# 4. サービスログを確認
kurtosis service logs <enclave-name> <service-name>

# 5. サービスにシェルで接続して状態を検証
kurtosis service shell <enclave-name> <service-name>

# 6. テスト後にクリーンアップ
kurtosis clean -a

よくあるエラー

エラー	原因	対処方法
cannot use future reference in if	Python ロジックでプランの結果を使用	plan.verify() または plan.assert() を使用
service not found	サービス名のタイプミスまたは未作成	plan.add_service() の名前が一致しているか確認
port not found	ポート ID の不一致	レシピ内の port_id が ports ディクショナリのキーと一致しているか確認
image pull failed	イメージが存在しないか認証なし	イメージタグを確認し、docker pull を手動で確認
kurtosis.yml not found	間違ったディレクトリから実行	kurtosis.yml を含むパッケージルートから実行