Tutorial: Develop a Custom Integration (StackPack)

This feature is pre-production and unreleased. It is only available if the environment variable STS_EXPERIMENTAL_STACKPACKS is set. Breaking changes may occur.

Goal

As a developer, you want to integrate your technology with SUSE® Observability by building a custom StackPack. This tutorial guides you through the process using the StackPack CLI.

Prerequisites

Access to the StackPack CLI
Feature flag enabled:
```
export STS_EXPERIMENTAL_STACKPACKS=true
```

How to Develop a Custom Integration (StackPack)

Scaffold a New StackPack

The scaffold subcommand creates a new StackPack project structure from configurable templates, streamlining the initial setup process for StackPack development. The command supports both local directory templates and GitHub-hosted templates.

Create a new StackPack project using the CLI:
```
sts stackpack scaffold --name my-stackpack
```

To use a specific GitHub template (default: 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.
...

To use a local template:

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

Review and Customize

Review the generated files in the target directory.
Edit stackpack.yaml and other files to define your integration logic.
- Integrating data. To map components and ingest metrics see Adding Otel Telemetry Mappings
- Adding monitors using the CLI
- Adding Metric Bindings

The default: stackvista/stackpack-templates template is a great starting point as it contains examples for most of the extension points such as Monitors and Metric Bindings.

Test Your StackPack

The test subcommand command that streamlines the stackpack development workflow by automating the package → upload → install/upgrade sequence with automatic version management for testing iterations.

Rapidly test your StackPack in a pre-production environment (requires a running Suse Observability instance):

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!

The test subcommand packages, uploads, and installs your StackPack with a test version suffix.
Iterate on your StackPack, using the test command for rapid feedback, make changes and observe the install/upgrade process to be successfully executed. Review the ingested topology and telemetry in the Suse Observability UI.

Package Your finished StackPack version

The package subcommand creates a zip file from stackpack directories. This command packages all required stackpack files and directories into a properly named zip archive for distribution and deployment.

Package your StackPack into a distributable 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

To specify the output file:

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

Validate Your StackPack

Before uploading and installing your StackPack, you can validate it to ensure it’s properly configured (for a tighter feedback loop). There are two approaches depending on your workflow:

Local Validation with Live Backend

The validate subcommand validates a StackPack against a running SUSE® Observability instance. This is useful for validating your StackPack during development.

Validate a StackPack directory (automatically packaged and uploaded):

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

Validate a pre-packaged .sts file:

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

The sts stackpack validate command requires a running SUSE® Observability instance configured in your CLI context. If you don’t have a live instance available, use CI validation instead.

Validation in CI/CD Pipelines

For CI/CD pipelines where you may not have a running SUSE® Observability instance, use the stack-pack-validator tool from the StackState Server Docker image. This performs validation without requiring a live backend connection.

GitLab CI Example

Use the StackState Server Docker image directly in your 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 Command Line

If running validation locally or in other CI/CD systems, use the docker run command:

Validate a packaged .sts file:

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

Validate a stackpack directory:

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

Use the stack-pack-validator script in the stackstate-server image in your CI/CD pipeline to validate StackPacks before publishing them. This ensures your StackPack meets all requirements without needing a running SUSE® Observability instance.

Upload your StackPack

The upload subcommand pushes the zip archive to a running SUSE® Observability instance.

Upload the archive to SUSE® Observability:

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

Install the StackPack

Install or Upgrade your StackPack via the SUSE® Observability stackpacks UI.