Skip to content

NAAS v2.0 Release Notes

NAAS v2.0 is a major release introducing a new API version, Python client library, CLI tool, Helm chart, and significant security and operational improvements.

Highlights

  • v2 API — New hyphenated routes (/v2/send-command), standardized field names (host/platform), full OpenAPI spec
  • Python client library — pip install naas-client for typed, ergonomic API access with sync and async support
  • CLI tool — pip install naas-client[cli] for terminal-based network operations with human and JSON output
  • Helm chart — Parameterized Kubernetes deployment under charts/naas/
  • JWT API keys with RBAC — Role-based access control (admin/operator/viewer) with context-scoped authorization
  • Worker Prometheus metrics — naas_worker_jobs_total, naas_worker_job_duration_seconds, naas_worker_active_jobs

Breaking Changes

  • v2 routes use hyphenated paths (send-command not send_command)
  • v2 routes require host and platform fields (reject deprecated ip and device_type)
  • RBAC enforced on v2 routes — API keys must have appropriate role
  • Context authorization enforced on v2 routes — API keys scoped to allowed contexts

See Upgrading to v2.0 for the full migration guide.

New Features

Python Client Library

from naas_client import NaasClient

with NaasClient("https://naas.example.com", api_key="eyJ...") as client:
    job = client.send_command(host="10.0.0.1", platform="cisco_ios", commands=["show version"])
    result = job.wait(timeout=30)
  • Synchronous and async clients (NaasClient, AsyncNaasClient)
  • Job and AsyncJob objects with wait(), poll(), cancel(), replay()
  • Auto-generated models from OpenAPI spec
  • Typed exceptions: NaasApiError, NaasAuthError, NaasTimeoutError

CLI Tool

naas send-command --host 10.0.0.1 --platform cisco_ios --wait "show version"
naas jobs list --status failed
naas api-keys create --role operator --contexts prod
  • Human-readable tables (terminal) or JSON (pipes/CI)
  • Exit codes for CI: 0=success, 1=job failed, 2=API error, 3=auth error, 4=timeout
  • Config file support (~/.config/naas/config.toml)
  • Shell completion for bash, zsh, fish

Helm Chart

helm install naas charts/naas --set secrets.redisPassword=changeme
  • Configurable API/worker replicas, resources, and metrics ports
  • Bundled or external Redis
  • Optional Ingress resource
  • Existing secret support

Security

  • JWT API key authentication with create/revoke/rotate lifecycle
  • RBAC: admin, operator, viewer roles
  • Context-scoped authorization (restrict API keys to specific routing contexts)
  • Credential encryption at rest in Redis
  • HMAC-signed webhook payloads
  • Structured audit event logging

Operational

  • Worker Prometheus metrics (jobs counter, duration histogram, active gauge)
  • Circuit breakers with per-device tracking
  • SSH connection pooling with idle eviction
  • Orphaned job reaper
  • Idempotency key support

v1 Deprecation

v1 routes remain available but are deprecated. All v1 responses include:

X-API-Deprecated: true
Sunset: 2027-01-01

v1 routes will be removed in v3.0.

Compatibility

  • Python 3.11+
  • Netmiko 4.x
  • Redis 7+
  • Kubernetes 1.27+ (Helm chart)