Demo Environment for the Generic StackPack

This tutorial creates a small environment for trying the generic StackPack template from Create a Custom Integration. The goal is to send OpenTelemetry Demo telemetry to SUSE® Observability, then use the scaffolded StackPack to customize how that telemetry is mapped and presented.

How the pieces fit together

The demo setup has three parts:

  • The SUSE® Observability platform stores topology, metrics, traces, health states, and StackPack configuration.

  • The SUSE® Observability Agent runs in the Kubernetes cluster where the demo application runs. The Agent includes process, node, and cluster components that collect infrastructure metrics and network topology. With the telemetry gateway enabled, it also accepts OTLP metrics and traces from workloads in the cluster and forwards them to the platform.

  • The OpenTelemetry Demo runs as the example application. Its services export telemetry directly to the Agent telemetry gateway service.

The data path is:

OpenTelemetry Demo services
  -> {stackstate-product-name} Agent telemetry gateway
  -> {stackstate-product-name} platform

Prerequisites

  • A Kubernetes cluster with kubectl access

  • Helm CLI installed

  • A running SUSE® Observability instance

  • The SUSE® Observability CLI configured for that instance

For a small self-hosted setup, follow Installing SUSE® Observability and use a non-HA sizing profile such as trial or 10-nonha if that fits your environment.

Install the Agent with the telemetry gateway

Install the SUSE® Observability Agent in the same Kubernetes cluster where you will deploy the OpenTelemetry Demo.

  1. In the SUSE® Observability UI, install the Kubernetes StackPack for the target cluster. For the full flow, see Quick start guide.

  2. Copy the Helm command generated by the Kubernetes StackPack instructions from the SUSE® Observability UI.

  3. Add a values file that enables the OpenTelemetry pipeline and telemetry gateway.

The OpenTelemetry Demo sends OTLP data to the telemetry gateway in the SUSE® Observability Agent. Enable the gateway in the Agent Helm values:

cat > agent-otel-values.yaml <<'EOF'
otel:
  enabled: true
  telemetryGateway:
    enabled: true
EOF

Add --values agent-otel-values.yaml to the generated Agent Helm command. The final command should look like this, with the cluster-specific values from the UI-generated command preserved:

helm upgrade --install suse-observability-agent suse-observability/suse-observability-agent \
  --namespace suse-observability-agent \
  --create-namespace \
  --set-string 'stackstate.apiKey'='<service-token>' \
  --set-string 'stackstate.cluster.name'='demo-cluster' \
  --set-string 'stackstate.url'='https://observability.acme.com/receiver/stsAgent' \
  --values agent-otel-values.yaml \
  <cluster-specific values from the Kubernetes StackPack instructions>

The stackstate.apiKey service token, stackstate.cluster.name, and stackstate.url can be obtained from the Kubernetes StackPack instructions in the SUSE® Observability UI.

If the Agent is already installed, run the same Helm command with --values agent-otel-values.yaml added.

The effective Agent values must include:

otel:
  enabled: true
  telemetryGateway:
    enabled: true

For the telemetry gateway details and endpoint names, see Telemetry gateway.

Verify that the telemetry gateway is running:

kubectl -n suse-observability-agent get deploy,svc | grep telemetry-gateway

This tutorial assumes the default telemetry gateway service name and namespace:

http://suse-observability-agent-otel-telemetry-gateway.suse-observability-agent.svc.cluster.local:4317

Deploy the OpenTelemetry Demo

Create a namespace and values file for the public OpenTelemetry Demo Helm chart.

The values file disables the demo chart’s bundled collector and local observability backends, then points the demo services at the SUSE® Observability Agent telemetry gateway. This keeps the setup focused on the data path used by this tutorial.

cat > otel-demo-values.yaml <<'EOF'
default:
  envOverrides:
    - name: OTEL_COLLECTOR_NAME
      value: suse-observability-agent-otel-telemetry-gateway.suse-observability-agent.svc.cluster.local

opentelemetry-collector:
  enabled: false

prometheus:
  enabled: false

grafana:
  enabled: false

jaeger:
  enabled: false

opensearch:
  enabled: false
EOF

Install the demo:

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update

helm upgrade --install opentelemetry-demo open-telemetry/opentelemetry-demo \
  --namespace telemetry-demo \
  --create-namespace \
  --values otel-demo-values.yaml

The telemetry-demo namespace matches the scaffolded StackPack template’s expected namespace for OTel components. Wait for the demo pods to become ready. The otel-collector, prometheus, grafana, jaeger, and opensearch pods should not be present with the values above.

kubectl -n otel-demo get pods

Verify telemetry reaches SUSE® Observability

Check that a demo service points at the Agent telemetry gateway:

kubectl -n otel-demo describe deploy checkout | grep -A2 OTEL_COLLECTOR_NAME

Then open the SUSE® Observability UI and verify that OpenTelemetry services and service instances are visible. If no data appears, check the telemetry gateway troubleshooting guidance in Telemetry gateway.

Deploy the scaffolded StackPack

Create and test-deploy the generic StackPack:

sts stackpack scaffold --name my-stackpack --display-name "My StackPack"
cd my-stackpack
sts stackpack test-deploy -d . --yes

The generic template is modeled on the OpenTelemetry Demo webshop. After it is installed, review the generated menu item, component overview, highlights, metrics, and monitor output in the SUSE® Observability UI.

For the complete custom integration tutorial, including hands-on customization examples, see Create a Custom Integration.

Clean up

Remove the demo workload when you are done:

helm uninstall opentelemetry-demo --namespace otel-demo
kubectl delete namespace otel-demo