Skip to content

Zone Configuration Job API Documentation

Overview

The Zone Configuration Job API is an asynchronous endpoint that retrieves detailed zone configuration information for Next Generation Data Center deployments. This API creates a background job to fetch and organize server data based on their roles within a deployment zone (mzone).

API Endpoint

GET /api/plugins/asset-index/zone-configuration-job/

Authentication

  • Required: Yes
  • Permission: IsAuthenticated

Request Parameters

Query Parameters

Parameter Type Required Description
servers string Yes Comma-delimited list of server hostnames to retrieve configuration for

Request Headers

Header Type Required Description
X-User-Id string No User identifier for tracking purposes
Authorization string Yes Bearer token for authentication

Request Example

curl -X GET "https://your-netbox-instance/api/plugins/asset-index/zone-configuration-job/?servers=server1,server2" \
  -H "Authorization: Token your-api-token" \
  -H "X-User-Id: user@example.com"

Response

Success Response (HTTP 202 Accepted)

The API immediately returns a job tracking response:

{
  "status": "pending",
  "job_pk": 456,
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response Fields: - status: Current job status (typically pending when first created) - job_pk: Internal job primary key for tracking - job_id: Unique UUID for the job (use this to check job status)

Job Output Structure

Once the job completes, the output contains:

{
  "success": true,
  "stdout": {
    "master_node": [...],
    "control_node": [...],
    "compute_node": [...],
    "edge_edge": [...],
    "edge_service": [...],
    "observability": [...]
  },
  "stderr": "",
  "skippederr": [],
  "exit_code": 0
}

Output Fields: - success: Boolean indicating overall success - stdout: Object containing categorized server data by role - stderr: Error messages (if any) - skippederr: Array of nodes that were skipped due to errors - exit_code: 0 for success, -1 for failure

Server Data Structure

Each server in the output contains:

{
  "hostname": "server1.example.com",
  "device_id": 123,
  "rack": "rack-01",
  "position": 42,
  "interfaces": [...],
  "ip_addresses": [...],
  "config_context": {...},
  "control": true,
  "master": false,
  "compute": false,
  "edge": false,
  "service": false,
  "observability": false
}

Processing Flow

Data Collection

For each server hostname: 1. Device Data: Fetches device information from NetBox 2. Interface Data: Retrieves network interface configurations 3. IP Address Data: Collects IP address assignments 4. Config Context: Gathers configuration context data

Role Categorization

Servers are categorized based on their roles: - master_node: Control nodes with master role - control_node: Control nodes without master role - compute_node: Compute nodes - edge_edge: Edge nodes - edge_service: Service nodes - observability: Observability nodes

Error Handling

Common Errors

Error Cause Resolution
Missing servers parameter Required parameter not provided Include comma-delimited server list in query
Invalid hostname Server not found in NetBox Verify server hostname exists in NetBox
Role not assigned Server lacks required role tags Ensure server has appropriate role assignment
Authentication failure Invalid or missing token Provide valid authentication token

Error Response Example

{
  "success": false,
  "stdout": "",
  "stderr": "Error message details",
  "skippederr": [
    "server1.example.com: node is not part of the roles [master, control, compute, edge, observability]",
    "server2.example.com: error Connection timeout"
  ],
  "exit_code": -1
}

Job Status Tracking

To check the status of your job, use the job_id returned in the initial response:

# Check job status
curl -X GET "https://your-netbox-instance/api/core/jobs/{job_id}/" \
  -H "Authorization: Token your-api-token"

Use Cases

1. Zone Expansion

Add new servers to an existing zone: 

GET /api/plugins/asset-index/zone-configuration-job/?servers=new-server1,new-server2

Best Practices

  1. Server List: Keep server lists reasonable (< 100 servers per request)
  2. Error Handling: Always check skippederr array for partial failures
  3. Job Monitoring: Poll job status for completion before using results
  4. Authentication: Use service accounts with appropriate permissions
  5. Logging: Include X-User-Id header for audit trails
  • Server Job: /api/plugins/asset-index/servers-job/
  • Job Status: /api/core/jobs/{job_id}/

Troubleshooting

Job Stuck in Pending

  • Check RQ worker status
  • Verify queue is processing
  • Review worker logs

Incomplete Results

  • Check skippederr array
  • Verify server roles are assigned
  • Ensure all required data exists in NetBox

Authentication Issues

  • Verify token is valid
  • Check user permissions
  • Ensure API access is enabled