Deployment History

TeamsEnterprise

Review deployment timelines, per-device results, configuration diffs, and audit logs for all stack deployments.

Overview

Every deployment action in NetStacks — deploy, modify, redeploy, rollback, and delete — is recorded with full audit details. Deployment history provides a complete timeline of what was pushed, to which devices, by whom, and whether it succeeded or failed.

Each deployment record captures:

Status — The final deployment state (completed, failed, rolled_back)
Device counts — Total devices targeted, how many succeeded, and how many failed
Timestamps — When the deployment was created, started, and completed
Per-device details — The rendered configuration pushed to each device, the backup configuration captured before changes, validation results, and any error messages
Deployment logs — Timestamped log entries with level (info, warning, error), message, and optional structured details

Audit trail

Deployment history serves as an audit trail for compliance and troubleshooting. Every deployment records the user who initiated it via the created_by field, making it possible to trace who changed what and when.

How It Works

Deployment Records

Each deployment creates a Deployment record that stores the high-level status and aggregate counts. The deployment references the stack instance (via stack_instance_id) or a standalone template (via template_id). It tracks whether rollback_enabled and validation_enabled were set, along with the total_devices, succeeded_count, and failed_count.

Per-Device Deployment Records

For each device in the deployment, a DeviceDeployment record stores:

rendered_config — The exact configuration text that was pushed to the device
backup_config — A snapshot of the device's configuration before any changes were made (captured when rollback_enabled is true)
validation_result — Structured data from pre-deployment validation checks
error_message — The error description if the device deployment failed
started_at and completed_at timestamps for per-device duration tracking

Deployment Logs

Each device deployment generates timestamped log entries (DeploymentLog) with a level (info, warning, or error), a human-readable message, and an optional details object for structured diagnostic data. Logs are retained for all deployments and can be queried by deployment ID.

Step-by-Step Guide

Walk through reviewing deployment history to understand what was deployed, when, and whether it succeeded.

Step 1: Navigate to the Stack Instance

Go to Stacks → Instances and select the instance whose history you want to review. The instance detail view shows a deployment timeline with all past deployments.

Step 2: View the Deployment Timeline

The timeline lists all deployments in reverse chronological order. Each entry shows the deployment name, status (completed, failed, rolled_back), device counts, the user who initiated it, and timestamps.

Step 3: Open a Deployment

Click on a deployment to see its details. The deployment detail view shows the overall status, duration, and per-device breakdown.

Step 4: Inspect Per-Device Results

Expand a device to see its individual deployment result. For succeeded devices, review the rendered configuration to confirm what was pushed. For failed devices, read the error message to diagnose the cause.

Step 5: Compare Rendered vs Backup Config

For any device deployment, you can view both the rendered config (what was pushed) and the backup config (what was there before). Comparing these shows exactly what changed on the device.

Step 6: View Deployment Logs

Open the logs tab to see timestamped entries for the deployment. Filter by log level (info, warning, error) to focus on issues. Log entries include structured details for programmatic analysis.

Step 7: Use History for Troubleshooting

When a device has unexpected configuration, use deployment history to trace when the change was made, what configuration was pushed, and whether it was part of a stack deployment or a manual change.

Code Examples

List All Deployments

list-deployments.shbash

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

Deployment List Response

deployment-list-response.jsonjson

[
  {
    "id": "dep-f8b3c1a2",
    "stack_instance_id": "inst-a7c4e2d1",
    "template_id": null,
    "name": "DC1-Core-Baseline-2025-01",
    "status": "completed",
    "rollback_enabled": true,
    "validation_enabled": true,
    "total_devices": 3,
    "succeeded_count": 3,
    "failed_count": 0,
    "created_by": "user-admin-01",
    "created_at": "2025-01-15T10:05:00Z",
    "started_at": "2025-01-15T10:05:01Z",
    "completed_at": "2025-01-15T10:05:45Z"
  },
  {
    "id": "dep-c2d9e4f5",
    "stack_instance_id": "inst-a7c4e2d1",
    "template_id": null,
    "name": "DC1-Core-Baseline-2025-01",
    "status": "failed",
    "rollback_enabled": true,
    "validation_enabled": false,
    "total_devices": 3,
    "succeeded_count": 2,
    "failed_count": 1,
    "created_by": "user-admin-01",
    "created_at": "2025-01-10T14:30:00Z",
    "started_at": "2025-01-10T14:30:02Z",
    "completed_at": "2025-01-10T14:31:15Z"
  }
]

Get Deployment with Per-Device Details

get-deployment-detail.shbash

# Get deployment details including per-device results
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://controller.example.net/plugins/stacks/admin/deployments/dep-f8b3c1a2?include_devices=true" | jq .

Deployment Detail with Device Results

deployment-with-devices.jsonjson

{
  "id": "dep-f8b3c1a2",
  "status": "completed",
  "total_devices": 3,
  "succeeded_count": 3,
  "failed_count": 0,
  "device_deployments": [
    {
      "id": "dd-001",
      "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",
      "error_message": null,
      "started_at": "2025-01-15T10:05:02Z",
      "completed_at": "2025-01-15T10:05:08Z"
    },
    {
      "id": "dd-002",
      "device_id": "dev-002",
      "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.2",
      "backup_config": "ntp server 192.168.1.100",
      "error_message": null,
      "started_at": "2025-01-15T10:05:03Z",
      "completed_at": "2025-01-15T10:05:09Z"
    }
  ]
}

Get Deployment Logs

get-deployment-logs.shbash

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://controller.example.net/plugins/stacks/admin/deployments/dep-f8b3c1a2/logs" | jq .

Deployment Log Entries

deployment-logs.jsonjson

[
  {
    "id": "log-001",
    "device_deployment_id": "dd-001",
    "level": "info",
    "message": "Connected to device dev-001 (10.0.1.1:22)",
    "details": { "protocol": "ssh", "auth_method": "certificate" },
    "created_at": "2025-01-15T10:05:02Z"
  },
  {
    "id": "log-002",
    "device_deployment_id": "dd-001",
    "level": "info",
    "message": "Backup configuration captured (1,247 bytes)",
    "details": { "config_size": 1247 },
    "created_at": "2025-01-15T10:05:03Z"
  },
  {
    "id": "log-003",
    "device_deployment_id": "dd-001",
    "level": "warning",
    "message": "Device returned warning: NTP server 192.168.1.100 removed from config",
    "details": { "removed_lines": ["ntp server 192.168.1.100"] },
    "created_at": "2025-01-15T10:05:06Z"
  },
  {
    "id": "log-004",
    "device_deployment_id": "dd-001",
    "level": "info",
    "message": "Configuration applied successfully to dev-001",
    "details": { "lines_added": 3, "lines_removed": 1, "duration_ms": 6000 },
    "created_at": "2025-01-15T10:05:08Z"
  }
]

Questions & Answers

Q: How long is deployment history retained?: A: Deployment history is retained indefinitely in the PostgreSQL database. All deployment records, per-device details, and log entries are stored permanently unless manually deleted by an administrator.
Q: Can I compare two deployments?: A: Yes. Open two deployments from the same stack instance and compare the rendered configurations for the same device. This shows what changed between deployments — useful for tracking the effect of variable changes or template updates.
Q: How do I find failed deployments?: A: Filter the deployment list by status to show only failed deployments. Each failed deployment shows which devices failed with their error messages, making it straightforward to diagnose issues across your deployment history.
Q: What is stored in backup_config?: A: The backup_config field contains a snapshot of the device's relevant configuration section before any changes were pushed. It is captured when rollback_enabled is true on the deployment. This backup is used to restore the device to its previous state if the deployment fails and rollback is triggered.
Q: Can I export deployment history?: A: You can retrieve deployment history through the REST API using the GET /plugins/stacks/admin/deployments endpoint. The response is JSON, which can be exported to CSV, integrated with monitoring tools, or stored in external log management systems for long-term analysis.
Q: What information do deployment logs contain?: A: Each log entry includes a timestamp, log level (info, warning, or error), a human-readable message, and an optional details object with structured data. Logs capture connection events, backup operations, configuration pushes, device warnings, and errors.

Troubleshooting

Deployment not appearing in history

If a deployment does not appear in the history list, verify you are viewing the correct organization. Deployments are scoped to the organization that owns the stack instance. Also check your user permissions — viewing deployment history requires the appropriate role-based access.

Missing backup configuration

The backup_config field is only populated when rollback_enabled was set to true during the deployment. If rollback was not enabled, no backup was captured. For future deployments, always enable rollback on production targets to ensure backups are taken.

Log entries missing details

The details field on log entries is optional. Simple operations (like connection events) may only include a message without structured details. Error-level log entries typically include the most detailed information, such as the specific device error response or timeout duration.

Deployment duration seems too long

Check the per-device started_at and completed_at timestamps to identify which device took the longest. Long durations are usually caused by slow device responses, network latency, or large configuration payloads. Consider deploying to fewer devices per instance if timeout issues are frequent.

Learn more about related NetStacks features:

Stack Instances — Deploy and manage the instances that generate deployment history
Creating Stacks — Create stack instances with target devices and variables
Template Versioning — Track template changes that lead to redeployments
Audit Logs — Organization-wide audit trail for all administrative actions
Stack Templates — Define the deployment blueprints that instances are created from