✨ New: Try our AI‑powered Search (Ctrl + K) — Read more

Architecture Overview

Prev Next

This article is intended to assist Customer Experience Engineers, Network Engineers, Field Engineers, with a comprehensive understanding of the Crosswork Assurance platform architecture, data flows, and component relationships for effective troubleshooting and support.

Executive Summary

Crosswok Assurance (formerly Cisco Crosswork Assurance) is a cloud-native network monitoring and analytics platform built on Kubernetes. The platform processes telemetry data from network sensors, performs real-time analytics, and provides actionable insights through a modern web interface.

Key characteristics:

  • 60+ microservices deployed as Kubernetes workloads
  • Event-driven architecture using Apache Kafka
  • Multi-tenant with complete data isolation
  • Horizontally scalable for enterprise deployments

System Context

This diagram shows how the solution fits into your environment. External systems (sensors, users, integrations) connect to Crosswork Assurance, which processes and stores telemetry data:

Three-Plane Architecture

We organize the 60+ services into three logical planes. This grouping helps you quickly narrow down where to look when troubleshooting:

Control Plane

These services manage how the platform is configured and how sensors are orchestrated. Issues here are often subtle—sensors failing to register, configuration changes not taking effect, or tenant-specific problems. Check this plane when the system is "running" but not behaving as expected.

Service Responsibility
Sensor-Orchestrator Manages sensor lifecycle, configuration distribution
Config-Service Centralized configuration management
Tenant-Manager Multi-tenant provisioning and isolation
License-Service License validation and feature enablement

Data Plane

This is where the real work happens. Sensor data flows through these services to be ingested, processed, and stored. When users report "missing data," "stale metrics," or "dashboards not updating," you'll be investigating this plane.

Service Responsibility
Sensor Collector High-performance telemetry ingestion
Fedex WebSocket broker for real-time data
Ignite Stream processing and aggregation
Spark Jobs Batch analytics and ML pipelines

Presentation Plane

This is what you and your users interact with directly. When someone reports they "can't access the system" or "the UI is broken," start here. These services handle authentication, serve the web interface, and expose APIs.

Service Responsibility
Gather REST API gateway
Foxtrot gNMI/gRPC interface for programmatic access
UI (nginx) Web application serving
Grafana Metrics visualization dashboards

Data Flow Pipeline

Understanding how data moves through Crosswork Assurance is critical for troubleshooting. When data is missing, you can trace backwards through this pipeline to find where the flow is broken.

Pipeline Stages

The following table shows each stage of the data pipeline. Data flows from left to right—if you're missing data, start checking from the right (closest to the UI) and work backwards:

Stage Component Function
1. Ingestion Sensor Collector Receives raw telemetry from sensors via gRPC
2. Broker Fedex Routes data to Kafka topics by type
3. Stream Kafka Durable message queue with topic partitioning
4. Process Ignite Real-time aggregation, alerting, enrichment
5. Store Druid Time-series storage optimized for analytics
6. Serve Gather API layer for queries and dashboards

Kafka Topics

Kafka organizes data into topics. Knowing which topics exist helps you verify data is flowing correctly:

Topic Pattern Data Type
spark_raw_in.* Raw telemetry from sensors
spark_latent_in.* Delayed/batch telemetry
normalized.* Processed, normalized metrics
alert-events Generated alerts

Data Stores

Crosswork Assurance uses specialized databases for different types of data. Understanding which database stores what helps you know where to look when troubleshooting:

Database Purpose Data Stored
PostgreSQL Relational data Configuration, users, tenants, metadata
Druid Time-series analytics Metrics, measurements, events
Redis/Valkey Caching Sessions, query cache, real-time state
MinIO Object storage Druid segments, backups, large files

Deployment Modes

Crosswork Assurance supports different deployment configurations depending on your requirements:

Mode Nodes Use Case
Single Node 1 Development, POC, small deployments
HA Mode 3+ (odd) Mission-critical with etcd quorum

Service Quick Reference

Use this table when you need to quickly check a specific service's health or find its logs:

Service Port Health Endpoint Key Logs to Check
Gather 80 /health API errors, auth failures
Fedex 80 /health WebSocket connections, Kafka lag
Ignite 80 /health Processing errors, memory usage
RoadRunner 80 /health Sensor connections, ingestion rate
Zitadel 8080 /healthz Auth errors, DB connectivity

Common Questions

Q: Why is data not appearing in the UI?

Check the data pipeline in order:

  1. Sensor connectivity (RoadRunner logs)
  2. Kafka consumer lag
  3. Ignite processing errors
  4. Druid ingestion status

Q: Why are queries slow?

Druid historical cache may not be warmed. After restart, allow 10-15 minutes for cache population. Check druid_historical_cache_hit_rate metric.

Q: Why are sensors not connecting?

Verify:

  1. Certificate validity (mTLS)
  2. Network connectivity to RoadRunner port
  3. Sensor-Orchestrator configuration
  4. Firewall rules for sensor traffic

Next Steps

Now that you understand the architecture, use these guides for specific tasks:

This article walks through the mental model we've built into the troubleshooting documentation. The goal is to give you a consistent framework for understanding the solution—not just a list of commands, but a way of thinking about the system.

© 2026 Cisco and/or its affiliates. All rights reserved.

For more information about trademarks, please visit:
Cisco trademarks 
For more information about legal terms, please visit:
Cisco legal terms