NetStacksNetStacks
Contact SalesGet Started

Creating Stacks

TeamsEnterprise

Create stack instances from templates, assign target devices, and provide variable values for deployment.

Overview

Creating a stack is the process of turning a stack template into a concrete deployment plan. A stack instance binds a stack template to specific target devices and provides concrete variable values. This is the bridge between defining what to deploy (the stack template) and actually deploying it to live devices.

When you create a stack instance, you specify three things:

  • Target devices — Which devices receive the configuration, identified by device ID, host address, and SSH port.
  • Variable values — Concrete values for all shared variables declared in the stack template (for example, ntp_server = 10.0.0.10).
  • Device overrides — Per-device variable values that differ from the shared defaults (for example, unique hostnames and management IPs for each device).
Instances vs deployments

A stack instance is the configuration plan. A deployment is the act of pushing that plan to devices. You can create an instance (state: pending) and deploy it later, or modify variables and redeploy an existing instance.

How It Works

The stack instance creation flow collects all information needed to render and push configurations to target devices.

Target Device Selection

You select target devices from your device inventory. Each target device is stored as an object with device_id, host (IP address or hostname), and port (SSH port, typically 22). You can target devices across multiple sites and locations in a single instance.

Variable Resolution

The variable_values field stores shared variable values that apply to all target devices. The device_overrides field is a nested map keyed by device ID, where each entry contains variable values specific to that device. At render time, device overrides take precedence over shared values.

Deploy Wizard UI Flow

The NetStacks UI provides a step-by-step deploy wizard that guides you through instance creation:

  1. Select a stack template from the template library
  2. Name the instance (a descriptive name for tracking)
  3. Select target devices from the device inventory
  4. Fill in shared variable values
  5. Fill in per-device variable values and overrides
  6. Review the summary showing all devices and variables
  7. Create the instance (initial state is pending)

Instance State

After creation, the instance starts in the pending state. It remains in this state until you trigger a deployment action. The instance stores a reference to the stack template, all variable values, and the list of target devices — everything needed to render and push configurations.

Step-by-Step Guide

Follow the deploy wizard to create a stack instance that deploys a monitoring baseline to three core routers.

Step 1: Select a Stack Template

Navigate to Stacks and click Create Instance. Select the stack template you want to deploy — for example, "Monitoring Baseline" which includes NTP, SNMP, and Syslog services.

Step 2: Name the Instance

Enter a descriptive name for the instance. Use a naming convention that includes the site, device role, and date — for example, DC1-Core-Baseline-2025-01. This name appears in deployment history and audit logs.

Naming conventions

Include the site code, device role, and a date or version identifier in the instance name. This makes it easy to find specific deployments in history — for example, NYC-Edge-Monitoring-v2 or LAX-Spine-Baseline-2025Q1.

Step 3: Select Target Devices

Choose devices from your inventory. You can filter by site, role, vendor, or tags. Select all devices that should receive this configuration. For this example, select three core routers: core-rtr-01, core-rtr-02, and core-rtr-03.

Step 4: Fill In Shared Variable Values

Enter values for all shared variables. These values apply to every target device:

  • ntp_server_primary: 10.0.0.10
  • ntp_server_secondary: 10.0.0.11
  • snmp_community: netstack$RO
  • syslog_server: 10.0.0.20

Step 5: Fill In Per-Device Variable Values

For each target device, enter the device-specific values:

  • core-rtr-01: hostname = core-rtr-01.dc1, management_ip = 10.0.1.1, snmp_location = DC1-Row1-Rack3
  • core-rtr-02: hostname = core-rtr-02.dc1, management_ip = 10.0.1.2, snmp_location = DC1-Row2-Rack7
  • core-rtr-03: hostname = core-rtr-03.dc1, management_ip = 10.0.1.3, snmp_location = DC1-Row3-Rack12

Step 6: Review and Create

The wizard summary shows every device with its resolved variable values. Verify that shared values are correct and per-device values are assigned to the right devices. Click Create Instance to save. The instance is created in the pending state, ready for deployment.

Code Examples

Create a Stack Instance via API

Use the stack instances API to create an instance that targets three core routers with shared monitoring variables and per-device hostnames:

create-stack-instance.shbash
curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://controller.example.net/plugins/stacks/admin/instances" \
  -d '{
    "stack_template_id": "stk-tmpl-9f3a2b1c",
    "name": "DC1-Core-Baseline-2025-01",
    "target_devices": [
      { "device_id": "dev-001", "host": "10.0.1.1", "port": 22 },
      { "device_id": "dev-002", "host": "10.0.1.2", "port": 22 },
      { "device_id": "dev-003", "host": "10.0.1.3", "port": 22 }
    ],
    "variable_values": {
      "ntp_server_primary": "10.0.0.10",
      "ntp_server_secondary": "10.0.0.11",
      "snmp_community": "netstack$RO",
      "syslog_server": "10.0.0.20"
    },
    "device_overrides": {
      "dev-001": {
        "hostname": "core-rtr-01.dc1",
        "management_ip": "10.0.1.1",
        "snmp_location": "DC1-Row1-Rack3"
      },
      "dev-002": {
        "hostname": "core-rtr-02.dc1",
        "management_ip": "10.0.1.2",
        "snmp_location": "DC1-Row2-Rack7"
      },
      "dev-003": {
        "hostname": "core-rtr-03.dc1",
        "management_ip": "10.0.1.3",
        "snmp_location": "DC1-Row3-Rack12"
      }
    }
  }'

Instance Creation Response

The API returns the created stack instance with its ID, state, and all configured values:

instance-response.jsonjson
{
  "id": "inst-a7c4e2d1",
  "org_id": "org-001",
  "stack_template_id": "stk-tmpl-9f3a2b1c",
  "name": "DC1-Core-Baseline-2025-01",
  "target_devices": [
    { "device_id": "dev-001", "host": "10.0.1.1", "port": 22 },
    { "device_id": "dev-002", "host": "10.0.1.2", "port": 22 },
    { "device_id": "dev-003", "host": "10.0.1.3", "port": 22 }
  ],
  "variable_values": {
    "ntp_server_primary": "10.0.0.10",
    "ntp_server_secondary": "10.0.0.11",
    "snmp_community": "netstack$RO",
    "syslog_server": "10.0.0.20"
  },
  "device_overrides": {
    "dev-001": { "hostname": "core-rtr-01.dc1", "management_ip": "10.0.1.1", "snmp_location": "DC1-Row1-Rack3" },
    "dev-002": { "hostname": "core-rtr-02.dc1", "management_ip": "10.0.1.2", "snmp_location": "DC1-Row2-Rack7" },
    "dev-003": { "hostname": "core-rtr-03.dc1", "management_ip": "10.0.1.3", "snmp_location": "DC1-Row3-Rack12" }
  },
  "state": "pending",
  "owner_id": "user-admin-01",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z"
}

List Stack Instances

list-instances.shbash
# List all stack instances
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://controller.example.net/plugins/stacks/admin/instances" | jq .

# Get a specific instance by ID
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://controller.example.net/plugins/stacks/admin/instances/inst-a7c4e2d1" | jq .

Questions & Answers

Q: How do I create a stack instance?
A: Use the deploy wizard in the UI or the POST /plugins/stacks/admin/instances API endpoint. Provide a stack template ID, a name, target devices, shared variable values, and optional per-device overrides. The instance is created in the pending state, ready for deployment.
Q: Can I deploy to devices in different locations?
A: Yes. The target devices list can include devices from any location in your inventory. Each target device is identified by its device ID, host address, and SSH port. There is no restriction on mixing devices from different sites, racks, or geographic locations.
Q: What happens if a target device is offline?
A: The instance is still created successfully because creation only stores the deployment plan. When you trigger a deployment, NetStacks validates connectivity to each target device during the validating phase. Offline devices will fail validation, and the deployment will report which devices are unreachable.
Q: Can I modify an instance after creation?
A: Yes. You can update variable values and device overrides on an existing instance using the modify action. If the instance has already been deployed, use the modify endpoint to change values and then redeploy to push the updated configuration.
Q: How many devices can I target in a single instance?
A: There is no hard limit on the number of target devices. In practice, deployments targeting hundreds of devices are common. NetStacks processes devices in parallel during deployment for performance, with per-device status tracking so you can monitor progress across large fleets.
Q: Can I create multiple instances from the same template?
A: Yes. A stack template is a reusable blueprint. You can create any number of instances from the same template, each targeting different devices with different variable values. For example, one instance for DC1 core routers and another for DC2 core routers, both using the same "Monitoring Baseline" template.

Troubleshooting

Missing required variables

If the creation form reports missing variables, check that you have provided values for all variables declared in the stack template. Shared variables need a value in variable_values. Per-device variables need a value either in variable_values (as a default) or in device_overrides for each target device.

Device not found in inventory

If a device does not appear in the target device picker, verify that the device exists in the device inventory and that you have permission to deploy to it. Devices must be added to the inventory before they can be targeted by a stack instance. See Adding Devices.

Duplicate instance names

Instance names must be unique within your organization. If you receive a duplicate name error, append a version number or date suffix to the name (for example, DC1-Core-Baseline-v2 or DC1-Core-Baseline-2025-02).

Permission errors on creation

Stack instance creation requires appropriate role-based permissions. Verify that your user account has the stack management permission and that the target devices are within your organization scope.

Learn more about related NetStacks features:

  • Stack Templates — Define reusable stack blueprints with ordered services and variable classification
  • Stack Instances — Deploy, monitor, and manage live stack instances on target devices
  • Variable Overrides — Customize variable values per device within a deployment
  • Deployment History — Review deployment timelines, logs, and per-device results
  • Adding Devices — Add devices to your inventory before targeting them in stack deployments