チュートリアル:カスタムインテグレーション（StackPack）を開発する
|
この機能はプレプロダクションであり、未リリースです。環境変数`STS_EXPERIMENTAL_STACKPACK`が設定されている場合のみ利用可能です。破壊的変更が発生する可能性があります。 |
目的
開発者として、カスタムStackPackを構築することで、あなたの技術をSUSE® Observabilityと統合したいと考えています。このチュートリアルでは、StackPack CLIを使用してプロセスを案内します。
前提条件
-
StackPack CLIへのアクセス
-
機能フラグが有効:
export STS_EXPERIMENTAL_STACKPACK=true
カスタムインテグレーション（StackPack）を開発する方法
新しいStackPackをスキャフォールドする
`scaffold`サブコマンドは、設定可能なテンプレートから新しいStackPackプロジェクト構造を作成し、StackPack開発の初期設定プロセスを簡素化します。このコマンドは、ローカルディレクトリテンプレートとGitHubホストのテンプレートの両方をサポートしています。
-
CLIを使用して新しいStackPackプロジェクトを作成します:
sts stackpack scaffold --name my-stackpack -
特定のGitHubテンプレートを使用するには（デフォルト: stackvista/stackpack-templates）:
sts stackpack scaffold --name my-stackpack --template-github-repo stackvista/stackpack-templates --template-name microservice --destination-dir stackpack ✓ Validating arguments... ✓ Checking destination directory... ✓ Fetching template from github:stackvista/stackpack-templates@main:templates ✓ Rendering templates... ✓ Validating rendered templates... ✓ Copying files to destination... Files copied: README.md provisioning/dashboard.sty provisioning/metricbindings.sty provisioning/monitors.sty provisioning/remediation-hints/node-memory-pressure.md.hbs provisioning/stackpack.sty resources/deprovisioning.md resources/error.md resources/installed.md resources/logo.png resources/notinstalled.md resources/overview.md resources/provisioning.md resources/waitingfordata.md stackpack.yaml ✅ ✓ Scaffold complete! Next steps: 1. Review the generated files in: ./my-stackpack 2. Check the ./my-stackpack/README.md for instructions on what to do next. ... -
ローカルテンプレートを使用するには:
sts stackpack scaffold --name my-stackpack --template-local-dir ./templates --template-name webapp
レビューとカスタマイズ
-
ターゲットディレクトリ内の生成されたファイルをレビューします。
-
`stackpack.yaml`および他のファイルを編集して、統合ロジックを定義します。
-
データを統合しています。コンポーネントをマッピングし、メトリクスを取り込むには、Otelテレメトリーマッピングの追加を参照してください。
-
|
デフォルトのhttps://github.com/StackVista/stackpack-templates[stackvista/stackpack-templates]テンプレートは、モニターやメトリックバインディングなどの拡張ポイントのほとんどの例を含んでいるため、素晴らしい出発点です。 |
スタックパックをテストする
`test`サブコマンドは、パッケージ→アップロード→インストール/アップグレードのシーケンスを自動化し、テストの反復のための自動バージョン管理を行うことで、StackPack開発ワークフローを効率化します。
-
プレプロダクション環境でStackPackを迅速にテストします（稼働中のSUSE Observabilityインスタンスが必要です）：
sts stackpack test -d ./my-stackpack --yes ✅ Starting stackpack test sequence... Stackpack: my-stackpack (current version: 0.0.1) Step 1/5: Checking installed version... Step 2/5: Creating temporary copy for testing... ✅ ✓ Temporary copy created Step 3/5: Bumping version for testing... ✅ ✓ Version bumped to: 0.0.1-cli-test.10000 Step 4/5: Packaging stackpack... ✅ ✓ Stackpack packaged successfully! Stackpack: my-stackpack (v0.0.1-cli-test.10000) Zip file: /Users/viliakov/Workspace/src/github/stackstate-cli/my-stackpack/my-stackpack-0.0.1-cli-test.10000.zip ✅ ✓ Stackpack packaged successfully Step 5/5: Uploading and installing/upgrading stackpack... ✅ Uploaded StackPack: /Users/viliakov/Workspace/src/github/stackstate-cli/my-stackpack/my-stackpack-0.0.1-cli-test.10000.zip NAME | DISPLAY NAME | VERSION my-stackpack | my-stackpack | 0.0.1-cli-test.10000 ✅ ✓ Stackpack uploaded successfully ✅ StackPack instance installed ID | NAME | STATUS | VERSION | LAST UPDATED 274027256960772 | - | PROVISIONING | 0.0.1-cli-test.1 | Fri Aug 29 09:10 | | | 0000 | :26 2025 CEST ✅ ✓ Stackpack installed successfully ✅ 🎉 Test sequence completed successfully! -
`test`サブコマンドは、テストバージョンのサフィックスを付けてスタックパックをパッケージ化、アップロード、インストールします。
-
StackPackを改善しながら、迅速なフィードバックを得るために`test`コマンドを使用し、変更を加え、インストール/アップグレードプロセスが正常に実行されることを確認します。SUSE Observability UIで取り込まれたトポロジーとテレメトリを確認します。
完成したStackPackバージョンをパッケージ化する
`package`サブコマンドは、StackPackディレクトリからzipファイルを作成します。このコマンドは、配布とデプロイメントのために適切に名前付けされたzipアーカイブに、すべての必要なStackPackファイルとディレクトリをパッケージ化します。
-
StackPackを配布可能なzipにパッケージ化します：
sts stackpack package -d ./my-stackpack ✅ ✓ Stackpack packaged successfully! Stackpack: stackpack (v0.0.1) Zip file: /Users/viliakov/Workspace/src/github/stackstate-cli/my-stackpack/my-stackpack-0.0.1-cli-test.zip -
出力ファイルを指定するには：
sts stackpack package -d ./my-stackpack -f my-custom-archive.zip
StackPackを検証する
StackPackをアップロードおよびインストールする前に、適切に構成されていることを確認するために検証できます（より密なフィードバックループのため）。ワークフローに応じて2つのアプローチがあります：
ライブバックエンドによるローカル検証
`validate`サブコマンドは、稼働中のSUSE® Observabilityインスタンスに対してスタックパックを検証します。これは、開発中にあなたのStackPackを検証するのに役立ちます。
-
StackPackディレクトリを検証します（自動的にパッケージ化され、アップロードされます）：
sts stackpack validate -d ./my-stackpack ✅ Stackpack validation successful! -
事前にパッケージ化された`.sts`ファイルを検証します：
sts stackpack validate -f ./my-stackpack-0.0.1.sts ✅ Stackpack validation successful!
|
`sts stackpack validate`コマンドは、あなたのCLIコンテキストに設定された実行中のSUSE® Observabilityインスタンスを必要とします。利用可能な実行中のインスタンスがない場合は、代わりにCI検証を使用してください。 |
CI/CDパイプラインでの検証
実行中のSUSE® ObservabilityインスタンスがないCI/CDパイプラインでは、StackState Server Dockerイメージから`stack-pack-validator`ツールを使用してください。これにより、ライブバックエンド接続を必要とせずに検証が行われます。
GitLab CIの例
GitLab CIパイプラインでStackState Server Dockerイメージを直接使用します：
.validate-stackpack: &validate-stackpack
stage: validate
image: registry.rancher.com/stackstate/stackstate-server:<latest-tag>
script:
- |
echo "Validating stackpack source: stackpacks/$STACKPACK"
/opt/docker/bin/stack-pack-validator -directory "$CI_PROJECT_DIR/stackpacks/$STACKPACK" || {
echo "ERROR: Stackpack validation failed for stackpacks/$STACKPACK"
exit 1
}
echo "Stackpack validation passed for stackpacks/$STACKPACK"
dependencies: []
validate-my-stackpack:
<<: *validate-stackpack
variables:
STACKPACK: my-stackpackDockerコマンドライン
ローカルまたは他のCI/CDシステムで検証を実行する場合は、`docker run`コマンドを使用してください：
-
パッケージ化された`.sts`ファイルを検証します：
docker run --rm --entrypoint="/opt/docker/bin/stack-pack-validator" \ -v /path/to/my-stackpack-0.0.1.sts:/stackpack.sts \ registry.rancher.com/stackstate/stackstate-server:<latest-tag> \ -file /stackpack.sts -
StackPackディレクトリを検証します：
docker run --rm --entrypoint="/opt/docker/bin/stack-pack-validator" \ -v /path/to/my-stackpack:/stackpack \ registry.rancher.com/stackstate/stackstate-server:<latest-tag> \ -directory /stackpack
|
CI/CDパイプラインで`stackstate-server`イメージの`stack-pack-validator`スクリプトを使用して、StackPackを公開する前に検証します。これにより、実行中のSUSE® Observabilityインスタンスを必要とせずに、あなたのStackPackがすべての要件を満たしていることが保証されます。 |
StackPackをアップロードします。
`upload`サブコマンドは、zipアーカイブを実行中のSUSE® Observabilityインスタンスにプッシュします。
-
アーカイブをSUSE® Observabilityにアップロードします：
sts stackpack upload -f ./my-stackpack-0.0.1.zip ✅ ✓ Stackpack uploaded successfully!
StackPackをインストールします。
StackPackをインストールまたはアップグレードする SUSE® Observability stackpacksのUIを通じて。