Skip to content

Context Routing

Contexts allow NAAS to route jobs to workers in specific network segments, VRFs, or geographies. This is essential in enterprise environments where the same IP address exists in multiple VRFs, or where workers in different locations have different device reachability.

Overview

A context is a named routing scope. Each context maps to a dedicated RQ queue. Workers declare which contexts they serve, and callers specify which context a job targets.

Caller → API → naas-{context} queue → Worker serving {context} → Device

Why Contexts?

In enterprise networks, IP addresses are not globally unique:

  • 10.1.1.1 in VRF corp is a different device than 10.1.1.1 in VRF oob
  • A worker in the corp network cannot reach OOB management devices
  • A worker in Hong Kong cannot reach London devices

Without contexts, NAAS cannot guarantee a job reaches a worker with the correct reachability.

Configuration

API: Define valid contexts

NAAS_CONTEXTS=default,corp,oob-dc1,oob-dc2,hk-prod,hk-oob,lon-prod,lon-oob

Unknown context names in requests return 400 Bad Request.

Worker: Declare served contexts

# Single context
WORKER_CONTEXTS=oob-dc1

# Multiple contexts
WORKER_CONTEXTS=oob-dc1,oob-dc2

# Default (backwards compatible — omit for single-segment deployments)
# WORKER_CONTEXTS not set → serves "default" context

Usage

Basic request with context

{
  "host": "10.1.1.1",
  "context": "oob-dc1",
  "platform": "cisco_ios",
  "commands": ["show version"]
}

Default context (backwards compatible)

{
  "host": "192.168.1.1",
  "platform": "cisco_ios",
  "commands": ["show version"]
}

Omitting context defaults to "default". Existing deployments require no changes.

Use Cases

Multi-VRF (same IP, different devices)

// Corp device at 10.1.1.1
{"host": "10.1.1.1", "context": "corp", "commands": ["show version"]}

// OOB management device at same IP, different VRF
{"host": "10.1.1.1", "context": "oob-dc1", "commands": ["show version"]}

Geographic routing

// Route to Hong Kong workers only
{"host": "10.100.1.1", "context": "hk-prod", "commands": ["show bgp summary"]}

// Route to London workers only
{"host": "10.200.1.1", "context": "lon-prod", "commands": ["show bgp summary"]}

OOB management plane

// Target device via out-of-band management, not production network
{"host": "172.16.1.1", "context": "oob-dc1", "commands": ["show logging"]}

Context Discovery

List active contexts with worker counts and queue depths:

curl -k https://naas.example.com/v2/contexts

{
  "contexts": [
    {"name": "corp",    "workers": 3, "queue_depth": 2},
    {"name": "oob-dc1", "workers": 1, "queue_depth": 0},
    {"name": "hk-prod", "workers": 2, "queue_depth": 5},
    {"name": "lon-prod", "workers": 2, "queue_depth": 1}
  ]
}

Error Responses

Unknown context (400)

{"error": "Unknown context. See GET /v2/contexts for valid contexts."}

No workers available (503)

{"error": "No workers available for the requested context"}

This occurs when the context is valid but no workers are currently serving it. Check worker health and WORKER_CONTEXTS configuration.

Kubernetes Deployment

Deploy separate worker pools per context:

# Main deployment (API + shared Redis)
helm install naas charts/naas \
  --set config.NAAS_CONTEXTS=corp,oob-dc1,oob-dc2,hk-prod,hk-oob

# Corp workers
helm install naas-worker-corp charts/naas \
  --set api.replicas=0 --set redis.enabled=false \
  --set redis.external.host=naas-redis.naas.svc \
  --set config.WORKER_CONTEXTS=corp

# OOB workers
helm install naas-worker-oob charts/naas \
  --set api.replicas=0 --set redis.enabled=false \
  --set redis.external.host=naas-redis.naas.svc \
  --set config.WORKER_CONTEXTS=oob-dc1,oob-dc2

# Hong Kong workers
helm install naas-worker-hk charts/naas \
  --set api.replicas=0 --set redis.enabled=false \
  --set redis.external.host=naas-redis.naas.svc \
  --set config.WORKER_CONTEXTS=hk-prod,hk-oob

# k8s/worker-corp/deployment.yaml
env:
  - name: WORKER_CONTEXTS
    value: "corp"

# k8s/worker-oob/deployment.yaml
env:
  - name: WORKER_CONTEXTS
    value: "oob-dc1,oob-dc2"

# k8s/worker-hk/deployment.yaml
env:
  - name: WORKER_CONTEXTS
    value: "hk-prod,hk-oob"

See Kubernetes deployment guide for full details.