StackPack Reference

StackPacks package custom integration configuration for SUSE® Observability. A StackPack can define how telemetry is mapped to topology, how components are presented in the UI, which monitors are installed, and which resources are shown on the StackPack page.

For a tutorial that creates a StackPack from a template, see Create a Custom Integration. For community examples, see contrib-stackpacks.

StackPack project structure

A StackPack 2.0 project contains a manifest, settings files, and resource directories:

my-stackpack/
├── README.md
├── stackpack.yaml
├── settings/
│   ├── main-menu.sty
│   ├── component-mappings/
│   │   └── services.sty
│   ├── relation-mappings/
│   │   └── service-relations.sty
│   ├── presentations/
│   │   └── service.sty
│   └── monitors.sty
├── icons/
│   └── service.svg
├── includes/
│   └── remediation-hints/
│       └── latency.md.hbs
└── resources/
    ├── overview.md
    ├── installed.md
    ├── notinstalled.md
    ├── provisioning.md
    ├── waitingfordata.md
    ├── deprovisioning.md
    ├── error.md
    └── logo.png
stackpack.yaml

The StackPack manifest. It defines metadata such as schemaVersion (effective StackPack framework version), version (StackPack semantic version), name, displayName, version, categories, logo, lifecycle text resources, and companion StackPacks.

settings/

Contains StackPack 2.0 setting files. SUSE® Observability traverses settings/*/.sty, concatenates the files as YAML documents, and imports the supported nodes during provisioning. The directory layout under settings/ is for author convenience; you can organize files by setting type, component type, domain, or any other structure.

icons/

Contains icon files referenced from settings with !icon, for example icon: !icon "service.svg".

includes/

Contains reusable content referenced from settings with !include, for example a long remediation hint body.

resources/

Contains files referenced from stackpack.yaml with !resource, such as the StackPack logo and lifecycle state Markdown files.

Settings files

Settings files are YAML documents stored as .sty files. A file can contain one node or multiple nodes. Multiple files are merged during import, so these layouts are equivalent from the importer’s perspective:

  • one large .sty file with all nodes

  • one file per setting type

  • one directory per component type or integration area

Each settings document uses a top-level nodes array:

nodes:
  - _type: ComponentPresentation
    identifier: urn:stackpack:my-stackpack:presentation:service
    name: Service
    # ...

Supported StackPack 2.0 setting node types are:

  • ComponentPresentation

  • Dashboard

  • ExternalMonitor

  • MainMenuGroup

  • Monitor

  • OtelComponentMapping

  • OtelRelationMapping

Custom tags

StackPack 2.0 supports custom YAML tags for files packaged with the StackPack:

!icon

Resolves a file from icons/ to a URL that can be used by UI configuration.

!include

Inserts the contents of a file from includes/ into the setting. Use this for large string values, such as remediation hints.

!resource

Resolves a file from resources/ to a URL. Use this in stackpack.yaml for logo and lifecycle documentation resources.

Example:

nodes:
  - _type: Monitor
    identifier: urn:stackpack:my-stackpack:monitor:latency
    name: High latency
    remediationHint: !include "remediation-hints/latency.md.hbs"

Handlebars support

StackPack 2.0 settings files do not support Handlebars templating. Keep .sty files as plain YAML; expressions such as {{ variable }} are rejected during StackPack validation.

Included remediation hint content is different: monitor remediation hints are rendered at runtime, so an included remediation hint file can contain Handlebars expressions that use the remediation hint data produced by the monitor.

If a remediation hint needs Handlebars variables, store it in a separate file under includes/ and reference it with !include. Putting {{ …​ }} directly in a .sty settings file fails StackPack 2.0 validation.

Manifest example

schemaVersion: "2.0"
name: "my-stackpack"
displayName: "My StackPack"
version: "0.0.1"
logoUrl: !resource "logo.png"
categories: [ "Custom" ]
overviewUrl: !resource "overview.md"
configurationUrls:
  INSTALLED: !resource "installed.md"
  NOT_INSTALLED: !resource "notinstalled.md"
  PROVISIONING: !resource "provisioning.md"
  WAITING_FOR_DATA: !resource "waitingfordata.md"
  DEPROVISIONING: !resource "deprovisioning.md"
  ERROR: !resource "error.md"
provision:
  companionStackPacks: []

Versioning strategy

StackPacks use semantic versioning. Choose the version bump based on the impact for users of the StackPack:

  • Patch version: bug fixes or small improvements that do not change the topology model, monitors, views, component presentation, or other user-visible output in a breaking way.

  • Minor version: backward-compatible additions or improvements, such as new metrics, monitors, component presentations, or additional topology relations.

  • Major version: a breaking user-visible change in the StackPack output. Use a major version when an existing concept, such as an overview, component type, relation, monitor, or presentation, is removed or significantly changed.

Patch and minor versions can be upgraded automatically when the StackPack is configured for automatic upgrades. This is controlled by the stackstate.stackpacks.upgradeOnStartup setting in the SUSE® Observability Helm chart. Major versions are supported as StackPack upgrades, but they are never upgraded automatically. Users must manually start the upgrade (via the UI or CLI).

If the source product goes through a major change that requires a completely different topology model, create a new StackPack that is tied to that external technology instead of publishing a major version of the existing StackPack.

StackPack CLI reference

Use sts stackpack --help and sts stackpack <command> --help for the complete options supported by your CLI version.

Scaffold

Create a StackPack project from a template:

sts stackpack scaffold --name my-stackpack --display-name "My StackPack"

Useful flags:

  • --template-name: template directory name, defaults to generic

  • --template-github-repo: GitHub repository in owner/repo format

  • --template-github-ref: branch, tag, or commit SHA

  • --template-github-path: path containing template directories

  • --template-local-dir: local directory containing template directories

  • --destination-dir: output directory

  • --force: overwrite existing files

Validate

Validate a StackPack against a running SUSE® Observability instance:

sts stackpack validate -d ./my-stackpack
sts stackpack validate -f ./my-stackpack-0.0.1.sts

Validating a directory packages it into a temporary .sts file before validation. Validating requires the CLI to be configured for the target SUSE® Observability instance.

Validation in CI/CD

For CI/CD pipelines where a running SUSE® Observability instance is not available, use the stack-pack-validator tool from a StackState Server container image. This validates the StackPack package structure and settings without uploading the StackPack to a live instance.

Pin the validator image to the StackState Server version you want to validate against. Update the image when you need to validate StackPacks for a newer server release.

Docker command

Validate a StackPack directory:

docker run --rm \
  -v "${PWD}:/workspace" \
  -w /workspace \
  quay.io/stackstate/stackstate-server:<tag> \
  /opt/docker/bin/stack-pack-validator -directory "/workspace/my-stackpack"

Validate a packaged .sts file:

docker run --rm \
  -v "${PWD}:/workspace" \
  -w /workspace \
  quay.io/stackstate/stackstate-server:<tag> \
  /opt/docker/bin/stack-pack-validator -file "/workspace/my-stackpack-0.0.1.sts"

GitHub Actions example

This example validates multiple StackPacks from a repository with a stackpacks/<stackpack-name> layout. It is adapted from the contrib-stackpacks CI workflow.

name: StackPack CI

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  validate:
    name: validate (${{ matrix.stackpack }})
    runs-on: ubuntu-24.04
    strategy:
      fail-fast: false
      matrix:
        stackpack:
          - my-stackpack
    steps:
      - name: Check out repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Validate ${{ matrix.stackpack }}
        env:
          STACKPACK: ${{ matrix.stackpack }}
          VALIDATOR_IMAGE: quay.io/stackstate/stackstate-server:<tag>
        run: |
          docker run --rm \
            -v "${PWD}:/workspace" \
            -w /workspace \
            "${VALIDATOR_IMAGE}" \
            /opt/docker/bin/stack-pack-validator -directory "/workspace/stackpacks/${STACKPACK}"

Test deploy

Run the development loop against a SUSE® Observability instance:

sts stackpack test-deploy -d ./my-stackpack --yes

The command reads stackpack.yaml, creates a temporary copy, adds a -cli-test.N version suffix, packages the StackPack, uploads it, and installs or upgrades the StackPack instance. The original directory is not changed.

Useful flags:

  • -d, --directory: StackPack directory, defaults to the current directory

  • -p, --parameter: install parameters in key=value form

  • --yes: skip the upload confirmation prompt

    1. Use sts stackpack test-deploy --help for the values supported by your CLI version.

Package

Package a StackPack into an .sts file:

sts stackpack package -d ./my-stackpack
sts stackpack package -d ./my-stackpack -f ./dist/my-stackpack-0.0.1.sts

The default archive name is <stackpack-name>-<version>.sts, based on stackpack.yaml.

Upload

Upload a packaged StackPack to SUSE® Observability:

sts stackpack upload --file ./my-stackpack-0.0.1.sts

Upload makes the StackPack version available. It does not install a StackPack instance.

Install, upgrade, and uninstall

Install an uploaded StackPack version:

sts stackpack install --name my-stackpack

Use -p or --parameter to pass install parameters in key=value form.

Upgrade an installed StackPack instance:

sts stackpack upgrade --name my-stackpack

Uninstalling requires the instance ID. Use sts stackpack list-instances --name <stackpack-name> to find it:

sts stackpack uninstall --name my-stackpack --id 123456789

The exact install parameters depend on the StackPack. Use sts stackpack list-parameters --name <stackpack-name> before installing if the StackPack requires parameters.

Inspect StackPacks

sts stackpack list
sts stackpack describe --name my-stackpack
sts stackpack list-instances --name my-stackpack
sts stackpack list-versions --name my-stackpack
sts stackpack list-parameters --name my-stackpack

Delete uploaded versions

Delete one uploaded StackPack version:

sts stackpack delete-version --name my-stackpack --stackpack-version 0.0.1

Delete multiple uploaded versions:

sts stackpack delete-versions --name my-stackpack --from 0.0.1 --to 0.0.2
sts stackpack delete-versions --name my-stackpack --all --dev-only