Anleitung: Entwickeln Sie eine benutzerdefinierte Integration (StackPack)

Dieses Feature befindet sich in der Vorproduktion und ist nicht veröffentlicht. Es ist nur verfügbar, wenn die Umgebungsvariable STS_EXPERIMENTAL_STACKPACK gesetzt ist. Es können Breaking Changes auftreten.

Zielwert

Als Entwickler möchten Sie Ihre Technologie mit SUSE® Observability integrieren, indem Sie ein benutzerdefiniertes StackPack erstellen. Dieses Tutorial führt Sie durch den Prozess mit der StackPack CLI.

Voraussetzungen

Zugriff auf die StackPack CLI
Feature-Flag aktiviert:
```
export STS_EXPERIMENTAL_STACKPACK=true
```

So entwickeln Sie eine benutzerdefinierte Integration (StackPack)

Erstellen Sie ein neues StackPack

Der scaffold Unterbefehl erstellt eine neue StackPack-Projektstruktur aus konfigurierbaren Vorlagen und optimiert den anfänglichen Einrichtungsprozess für die StackPack-Entwicklung. Der Befehl unterstützt sowohl lokale Verzeichnisvorlagen als auch auf GitHub gehostete Vorlagen.

Erstellen Sie ein neues StackPack-Projekt mit der CLI:
```
sts stackpack scaffold --name my-stackpack
```

Um eine spezifische GitHub-Vorlage zu verwenden (Standard: 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.
...

Um eine lokale Vorlage zu verwenden:

sts stackpack scaffold --name my-stackpack --template-local-dir ./templates --template-name webapp

Überprüfen und Anpassen

Überprüfen Sie die generierten Dateien im Zielverzeichnis.
Bearbeiten Sie stackpack.yaml und andere Dateien, um Ihre Integrationslogik zu definieren.
- Daten integrieren. Um Komponenten zuzuordnen und Metriken zu erfassen, siehe Hinzufügen von Otel Telemetrie-Zuordnungen
- Monitore über die CLI hinzufügen
- Metric-Bindings hinzufügen

Das Standardtemplate stackvista/stackpack-templates ist ein großartiger Ausgangspunkt, da es Beispiele für die meisten Erweiterungspunkte wie Monitore und Metric-Bindings enthält.

Testen Sie Ihr StackPack

Der test Unterbefehl, der den Entwicklungsworkflow für StackPack optimiert, indem er die Sequenz Paket → Hochladen → Installieren/Upgrade mit automatischer Versionsverwaltung für Testiterationen automatisiert.

Testen Sie Ihr StackPack schnell in einer Vorproduktionsumgebung (erfordert eine laufende SUSE Observability-Instanz):

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!

Der test Unterbefehl paketiert, lädt hoch und installiert Ihr StackPack mit einem Testversionssuffix.
Iterieren Sie über Ihr StackPack, verwenden Sie den test Befehl für schnelles Feedback, nehmen Sie Änderungen vor und beobachten Sie den Installations-/Upgrade-Prozess, um sicherzustellen, dass er erfolgreich ausgeführt wird. Überprüfen Sie die erfasste Topologie und Telemetrie in der SUSE Observability-Benutzeroberfläche.

Paketieren Sie Ihre fertige StackPack-Version

Der package Unterbefehl erstellt eine Zip-Datei aus StackPack-Verzeichnissen. Dieser Befehl paketiert alle erforderlichen StackPack-Dateien und -Verzeichnisse in ein ordnungsgemäß benanntes Zip-Archiv für die Verteilung und Bereitstellung.

Paketieren Sie Ihr StackPack in ein verteilbares Zip-Archiv:

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

Um die Ausgabedatei anzugeben:

sts stackpack package -d ./my-stackpack -f my-custom-archive.zip

Validieren Sie Ihr StackPack

Bevor Sie Ihr StackPack hochladen und installieren, können Sie es validieren, um sicherzustellen, dass es richtig konfiguriert ist (für einen engeren Feedback-Zyklus). Es gibt zwei Ansätze, abhängig von Ihrem Workflow:

Lokale Validierung mit Live-Backend

Der validate Unterbefehl validiert ein StackPack gegen eine laufende SUSE® Observability Instanz. Dies ist nützlich, um Ihr StackPack während der Entwicklung zu validieren.

Validieren Sie ein StackPack-Verzeichnis (automatisch verpackt und hochgeladen):
```
sts stackpack validate -d ./my-stackpack
✅ Stackpack validation successful!
```

Validieren Sie eine vorverpackte .sts-Datei:

sts stackpack validate -f ./my-stackpack-0.0.1.sts
✅ Stackpack validation successful!

Der sts stackpack validate-Befehl erfordert eine laufende SUSE® Observability-Instanz, die in Ihrem CLI-Kontext konfiguriert ist. Wenn Sie keine aktive Instanz zur Verfügung haben, verwenden Sie stattdessen die CI-Validierung.

Validierung in CI/CD-Pipelines

Für CI/CD-Pipelines, in denen Sie möglicherweise keine laufende SUSE® Observability-Instanz haben, verwenden Sie das stack-pack-validator-Tool aus dem StackState Server Docker-Image. Dies führt die Validierung durch, ohne eine aktive Backend-Verbindung zu benötigen.

GitLab CI Beispiel

Verwenden Sie das StackState Server Docker-Image direkt in Ihrer GitLab CI-Pipeline:

.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-stackpack

Docker-Befehlszeile

Wenn Sie die Validierung lokal oder in anderen CI/CD-Systemen ausführen, verwenden Sie den docker run-Befehl:

Validieren Sie eine verpackte .sts-Datei:

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

Validieren Sie ein StackPack-Verzeichnis:

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

Verwenden Sie das stack-pack-validator-Skript im stackstate-server-Image in Ihrer CI/CD-Pipeline, um StackPacks vor der Veröffentlichung zu validieren. Dies stellt sicher, dass Ihr StackPack alle Anforderungen erfüllt, ohne dass eine laufende SUSE® Observability-Instanz benötigt wird.

Laden Sie Ihr StackPack hoch

Der upload-Unterbefehl schiebt das Zip-Archiv zu einer laufenden SUSE® Observability-Instanz.

Laden Sie das Archiv zu SUSE® Observability hoch:

sts stackpack upload -f ./my-stackpack-0.0.1.zip
✅ ✓ Stackpack uploaded successfully!

Installieren Sie das StackPack

Installieren oder upgraden Sie Ihr StackPack über die SUSE® Observability Stackpacks-Benutzeroberfläche.