Stack Templates

TeamsEnterprise

Combine multiple Jinja2 templates into a single deployable stack with ordered services and shared variables.

Overview

A stack template is a grouping mechanism that combines multiple Jinja2 configuration templates — called services — into a single deployable unit. Instead of pushing NTP, SNMP, Syslog, and ACL configurations one template at a time, you define a stack template that deploys the entire device baseline as one atomic operation.

Each stack template declares which templates to include, the order they execute in, and how variables are classified:

Services — An ordered list of Jinja2 templates. Each service references an existing template by ID, has a display name, and an execution order number.
Shared variables — Variables whose values are the same across all target devices (for example, ntp_server or snmp_community).
Per-device variables — Variables that differ for each target device (for example, hostname or management_ip).
API variables — Variables whose values are automatically fetched from an external API endpoint at deploy time using JSON path extraction.

When to use stacks

Use stack templates whenever you need to deploy two or more related configurations to the same set of devices. A stack ensures that all services deploy together and can roll back together if any service fails.

How It Works

A StackTemplate references existing Jinja2 templates by their IDs. It does not duplicate template content — it creates a deployment plan that says "render and push these templates in this order."

Service Ordering

Each service in the stack has an order field. During deployment, NetStacks renders and pushes services in ascending order. A service with order: 1 executes before order: 2. This matters when one configuration depends on another — for example, interface addressing must be configured before routing protocols reference those interfaces.

Variable Classification

When you add templates to a stack, NetStacks extracts all Jinja2 variables from every template. You then classify each variable as either shared (same value for all devices) or per-device (unique value per target device). This classification determines the UI flow when creating stack instances.

API Variables

API variables (ApiVariableConfig) let you auto-populate variable values from external systems at deploy time. Each API variable defines a resource_id, an HTTP endpoint, an HTTP method (GET, POST, or PUT), an optional request body, and a json_path expression to extract the value from the response. This is useful for pulling the latest SNMP community string from a secrets manager or fetching a device's management IP from a CMDB.

Device Count Tracking

Each stack template tracks a device_count field that indicates how many devices are currently deployed with this stack. This gives you visibility into the blast radius before making changes to the template.

Step-by-Step Guide

Follow these steps to create a stack template that deploys a complete device baseline.

Step 1: Create Individual Templates First

Stack templates reference existing Jinja2 templates. Before creating a stack, ensure each service template exists and renders correctly on its own. See the Template Basics guide for creating templates.

Step 2: Navigate to the Stacks Section

In the NetStacks UI, go to Stacks in the main navigation. Click New Stack Template to open the creation form.

Step 3: Name and Describe the Stack

Give the stack a descriptive name (for example, "DC1 Core Baseline") and an optional description explaining what configurations it deploys and which device roles it targets.

Step 4: Add Services

Click Add Service to select a Jinja2 template from your template library. Give each service a name and set its execution order. Lower order numbers execute first.

Execution order matters

Services execute in ascending order by their order field. If your SNMP configuration depends on interface IP addresses being configured first, ensure the interface template has a lower order number than the SNMP template.

Step 5: Classify Variables

NetStacks extracts all Jinja2 variables from the added templates. For each variable, choose whether it is shared (same value for every device) or per-device (unique value per target). Variables like ntp_server are typically shared. Variables like hostname are always per-device.

Step 6: Configure API Variable Sources (Optional)

For variables that should be fetched from an external API at deploy time, configure an API variable source. Specify the endpoint URL, HTTP method, and a JSON path expression to extract the value from the response.

Step 7: Save the Stack Template

Click Save. The stack template is now available for creating instances and deploying to devices.

Code Examples

Stack Template with Three Services

This stack template deploys a complete monitoring baseline — NTP time synchronization, SNMP monitoring, and Syslog forwarding — to network devices:

stack-template-example.jsonjson

{
  "id": "stk-tmpl-9f3a2b1c",
  "name": "Monitoring Baseline",
  "description": "NTP + SNMP + Syslog baseline for all network devices",
  "services": [
    {
      "template_id": "tmpl-ntp-001",
      "name": "NTP Configuration",
      "order": 1
    },
    {
      "template_id": "tmpl-snmp-002",
      "name": "SNMP Monitoring",
      "order": 2
    },
    {
      "template_id": "tmpl-syslog-003",
      "name": "Syslog Forwarding",
      "order": 3
    }
  ],
  "shared_variables": [
    "ntp_server_primary",
    "ntp_server_secondary",
    "snmp_community",
    "syslog_server"
  ],
  "per_device_variables": [
    "hostname",
    "management_ip",
    "snmp_location"
  ],
  "device_count": 0,
  "created_at": "2025-01-15T09:30:00Z",
  "updated_at": "2025-01-15T09:30:00Z"
}

API Variable Configuration

This example configures an API variable that auto-fetches the current SNMP read-only community string from a secrets manager at deploy time:

api-variables-example.jsonjson

{
  "api_variables": {
    "snmp_community": {
      "resource_id": "secrets-vault",
      "endpoint": "https://vault.example.net/v1/secret/data/network/snmp",
      "method": "GET",
      "json_path": "$.data.data.ro_community",
      "description": "SNMP RO community from Vault"
    },
    "syslog_server": {
      "resource_id": "cmdb-api",
      "endpoint": "https://cmdb.example.net/api/v1/services/syslog",
      "method": "GET",
      "json_path": "$.result.primary_server",
      "description": "Primary syslog server from CMDB"
    }
  }
}

Jinja2 Template Referenced by a Service

Each service in a stack references a Jinja2 template. Here is the NTP template that the first service renders:

ntp-config.j2jinja2

! NTP Configuration for {{ hostname }}
ntp server {{ ntp_server_primary }} prefer
ntp server {{ ntp_server_secondary }}
ntp source {{ management_ip }}
ntp authenticate
ntp trusted-key 1
clock timezone UTC

List Stack Templates via API

list-stack-templates.shbash

# List all stack templates for your organization
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://controller.example.net/plugins/stacks/admin/stacks" | jq .

# Get a specific stack template with service details
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://controller.example.net/plugins/stacks/admin/stacks/stk-tmpl-9f3a2b1c" | jq .

Questions & Answers

Q: What is a stack template?: A: A stack template is a grouping of multiple Jinja2 configuration templates (called services) into a single deployable unit. It defines which templates to deploy, in what order, and how variables are shared across services. Think of it as a deployment blueprint for a complete device configuration.
Q: How many templates can a stack include?: A: There is no hard limit on the number of services in a stack template. In practice, stacks typically include 2 to 10 services. A common pattern is a "device baseline" stack with NTP, SNMP, Syslog, AAA, and ACL templates — around 5 services.
Q: What is the difference between shared and per-device variables?: A: Shared variables have the same value for every target device in a deployment. For example, ntp_server is typically the same across all devices in a site. Per-device variables have a unique value for each target device. For example, hostname and management_ip are always different per device.
Q: What are API variables?: A: API variables are values that are automatically fetched from an external HTTP endpoint at deploy time. You configure the endpoint URL, HTTP method, and a JSON path expression to extract the value from the response. This is useful for pulling secrets from a vault, fetching inventory data from a CMDB, or reading the latest firmware version from an update server.
Q: Can I reorder services after creating the stack?: A: Yes. You can edit a stack template at any time to change service order, add new services, or remove existing ones. Changing the order updates the order field on each service. Existing stack instances are not affected until they are redeployed.
Q: How does execution order work during deployment?: A: During deployment, NetStacks renders and pushes services in ascending order by their order field. Service with order: 1 completes before order: 2 begins. If a lower-order service fails and rollback is enabled, higher-order services are not attempted.

Troubleshooting

Template not found when adding a service

If a Jinja2 template does not appear in the template picker when adding a service, verify the template exists and is published. Draft or deleted templates cannot be added to a stack. Navigate to Templates and confirm the template is visible.

Variable conflicts between services

If two templates in the same stack use the same variable name but expect different values, you will see unexpected rendered output. For example, if both an NTP template and a DNS template use a variable called server, they will receive the same value. Rename the variable in one template to be more specific (for example, ntp_server and dns_server).

API variable endpoint unreachable

If an API variable fails to resolve during deployment, the deployment will report a validation error. Verify:

The endpoint URL is reachable from the Controller server
Authentication headers or tokens are valid and not expired
The JSON path expression matches the actual response structure
The external service is not rate-limiting requests from the Controller

Stack template shows zero device count

The device_count field reflects the number of devices currently deployed with active instances of this stack. If you created a stack template but have not yet created any instances or deployed them, the count will be zero.

Learn more about related NetStacks features:

Template Basics — Create and manage the Jinja2 templates that stack services reference
Creating Stacks — Create stack instances from templates and assign target devices
Stack Instances — Deploy, monitor, and manage live stack deployments
Variable Overrides — Customize variable values per device within a stack deployment
Template Variables — Understand variable extraction, defaults, and Jinja2 filters