Stack Instances

Overview

A stack instance is a live deployment binding — it connects a stack template to target devices with concrete variable values and tracks the deployment state. Once created, you trigger deployment actions (deploy, validate, modify, redeploy, rollback, delete) against the instance.

Deployment State Machine

Every deployment progresses through a well-defined state machine with seven possible statuses:

How It Works

When you trigger a deployment, NetStacks orchestrates a multi-step process across all target devices.

1. Validation Phase

The deployment enters validating status. NetStacks connects to each target device, verifies SSH credentials, and optionally checks the current running configuration. If validation_enabled is set, the system compares expected state against actual device state before proceeding.

2. Configuration Push

The deployment moves to in_progress. For each target device, NetStacks renders all service templates using the merged variable values (shared values plus device overrides), then pushes the rendered configuration in service order. Each device gets a DeviceDeployment record tracking its individual status, the rendered_config that was pushed, and a backup_config snapshot of what was there before.

3. Per-Device Tracking

Each target device has its own deployment status. The parent deployment tracks aggregate counts: total_devices, succeeded_count, and failed_count. Individual device deployments store validation_result, error_message, and timestamps for when they started and completed.

4. Rollback Handling

If rollback_enabled is true and a device fails, NetStacks automatically enters rolling_back status. It pushes the backup_config to failed devices, restoring them to their previous state. Once rollback completes, the status moves to rolled_back.

5. Available Actions

After initial deployment, you can perform additional actions:

• Validate — Check for configuration drift by comparing the rendered config against the device's current running config.
• Modify — Update variable values or device overrides and push the changes to devices.
• Redeploy — Re-render and push all templates again, useful after template content changes.
• Delete/Undeploy — Remove the deployed configuration from target devices.

Step-by-Step Guide

Walk through deploying a stack instance and monitoring it through the state machine.

Step 1: Open the Stack Instance

Navigate to Stacks → Instances and select the instance you want to deploy (for example, "DC1-Core-Baseline-2025-01"). The instance detail view shows target devices, variable values, and current state.

Step 2: Trigger Deployment

Click Deploy. Optionally enable Dry Run to preview rendered configurations without pushing them to devices. Enable Rollback to automatically revert failed devices to their backup configuration.

Step 3: Monitor Deployment Progress

The deployment status bar shows real-time progress: how many devices have succeeded, how many have failed, and how many are still in progress. Click on any device to see its individual deployment details.

Step 4: Inspect Per-Device Results

For each device, you can view:

• Rendered config — The exact configuration that was pushed
• Backup config — The configuration that existed before deployment
• Validation result — Results from pre-deployment validation
• Error message — Details if the device deployment failed

Step 5: Handle Failures

If any device fails, inspect the error message to understand the cause. Common causes include SSH authentication failures, configuration syntax errors, and device timeouts. After fixing the issue, use Redeploy to retry.

Step 6: Validate for Drift

After deployment, use the Validate action to check whether devices have drifted from their expected configuration. The validation response includes drift_entries showing the path, drift type, and expected vs actual values.

Code Examples

Deploy a Stack Instance

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://controller.example.net/plugins/stacks/admin/deployments/deploy" \
  -d '{
    "stack_instance_id": "inst-a7c4e2d1",
    "dry_run": false,
    "rollback_enabled": true,
    "validation_enabled": true
  }'

Deployment Response

{
  "id": "dep-f8b3c1a2",
  "stack_instance_id": "inst-a7c4e2d1",
  "name": "DC1-Core-Baseline-2025-01",
  "status": "in_progress",
  "rollback_enabled": true,
  "validation_enabled": true,
  "total_devices": 3,
  "succeeded_count": 0,
  "failed_count": 0,
  "created_by": "user-admin-01",
  "created_at": "2025-01-15T10:05:00Z",
  "started_at": "2025-01-15T10:05:01Z",
  "completed_at": null
}

Per-Device Deployment Detail

Query a deployment with ?include_devices=true to see individual device results:

{
  "id": "dd-001",
  "deployment_id": "dep-f8b3c1a2",
  "device_id": "dev-001",
  "service_name": "NTP Configuration",
  "status": "completed",
  "rendered_config": "ntp server 10.0.0.10 prefer\nntp server 10.0.0.11\nntp source 10.0.1.1",
  "backup_config": "ntp server 192.168.1.100\nntp source Loopback0",
  "validation_result": { "valid": true, "checks_passed": 3, "checks_total": 3 },
  "error_message": null,
  "started_at": "2025-01-15T10:05:02Z",
  "completed_at": "2025-01-15T10:05:08Z"
}

Validate for Configuration Drift

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://controller.example.net/plugins/stacks/admin/deployments/validate" \
  -d '{
    "stack_instance_id": "inst-a7c4e2d1"
  }'

Drift Detection Response

{
  "instance_id": "inst-a7c4e2d1",
  "drift_detected": true,
  "drift_entries": [
    {
      "device_id": "dev-002",
      "service_name": "NTP Configuration",
      "path": "ntp server",
      "drift_type": "modified",
      "expected": "ntp server 10.0.0.10 prefer",
      "actual": "ntp server 10.0.0.99 prefer"
    }
  ],
  "devices_checked": 3,
  "devices_drifted": 1
}

Questions & Answers

Q: What is a stack instance?

A: A stack instance is a live deployment binding that connects a stack template to specific target devices with concrete variable values. It tracks the deployment state and provides actions like deploy, validate, modify, redeploy, and delete.

Q: What are the deployment statuses?

A: There are seven statuses: pending (created, not deployed), validating (checking device connectivity), in_progress (pushing configurations), completed (all devices succeeded), failed (one or more devices failed), rolling_back (reverting to backup configs), and rolled_back (rollback complete).

Q: How does rollback work?

A: When rollback_enabled is set to true and a device fails during deployment, NetStacks automatically captures a backup_config before pushing changes and restores it on failure. The deployment status transitions from failed to rolling_back to rolled_back.

Q: What happens if one device fails?

A: The failed device is marked individually with an error message. Other devices that have already succeeded remain in their new configuration. If rollback is enabled, only the failed device is rolled back. The overall deployment status shows failed with per-device counts so you can see exactly which devices succeeded and which failed.

Q: Can I retry a failed deployment?

A: Yes. After fixing the underlying issue (network connectivity, credentials, configuration syntax), use the Redeploy action to retry. Redeployment re-renders all templates and pushes to all target devices.

Q: How do I check for configuration drift?

A: Use the Validate action on a deployed instance. NetStacks connects to each device, reads the running configuration, and compares it against the expected rendered output. Drift entries show the path, drift type (modified, missing, or extra), and the expected vs actual values.

Q: What is dry-run mode?

A: Dry-run mode renders all templates with the configured variable values and connects to target devices for validation, but does not push any configuration changes. Use it to preview exactly what would be deployed before committing to a live push.

Troubleshooting

Device unreachable during deployment

If a device fails with a connection error during deployment, verify SSH connectivity from the Controller server. Check that the device IP and port are correct, the device is powered on, and no firewall rules block SSH from the Controller. Test with: nc -zv 10.0.1.1 22 from the Controller host.

Authentication failure

SSH authentication errors usually mean the credential stored in NetStacks is incorrect or expired. Verify the credential in the Credential Vault, update it if needed, and retry the deployment.

Configuration push rejected by device

Some devices reject configuration lines that conflict with existing config or contain syntax errors. Check the error_message on the failed device deployment for the exact rejection message. Correct the Jinja2 template and redeploy.

Rollback failed (backup config missing)

Rollback requires a backup_config snapshot. If rollback was not enabled during the original deployment, no backup was taken. Enable rollback_enabled: true on all production deployments to ensure backups are captured.

Deployment stuck in validating state

A deployment can appear stuck in validating if one or more devices are slow to respond. This typically resolves when the device connection times out. If the deployment remains in this state for more than 5 minutes, check Controller logs for connection timeout details.

Related Features

Learn more about related NetStacks features:

• Stack Templates — Define reusable stack blueprints with ordered services
• Creating Stacks — Create stack instances from templates with target devices and variables
• Variable Overrides — Customize variable values per device within a deployment
• Deployment History — Review deployment timelines, logs, and per-device results
• Credential Vault — Manage SSH credentials used for device connectivity during deployments