Skip to main content

All-up Visualization — Aspire + k3s

This guide shows how to visualize CitadelMesh locally (Aspire AppHost) and on your k3s cluster (Helm), side-by-side.

What you’ll see​

  • Aspire Dashboard (local): containers, projects, dependencies, logs, traces.
  • k3s (cluster): pods/services with kubectl, plus Grafana/Prometheus/Jaeger (if enabled) and NATS monitoring.
  • Gateway counters: scrape /metrics from the Node Gateway for quick feedback.

Local — Aspire AppHost​

  1. Install Aspire CLI/Dashboard (one-time): see Guides → Development Setup → Aspire Dashboard.
  2. Run AppHost:
cd src/CitadelMesh.AppHost
dotnet run

You’ll get a dashboard showing OPA, NATS, microservices, and more, with live logs and traces.

Cluster — k3s/Helm​

  1. Deploy (already done in the validation loop):
# Example (OPA enabled once chart is fixed)
helm upgrade --install citadel helm/citadelmesh -n citadel -f config/k3s/values-k3s-edge.yaml --create-namespace
  1. Visualize with kubectl:
kubectl get pods -n citadel
kubectl get svc -n citadel
  1. Port-forward commonly used services:
# NATS client + monitoring
kubectl port-forward svc/citadel-nats -n citadel 4222:4222 8222:8222

# Once observability is enabled in Helm
kubectl port-forward svc/citadel-prometheus -n citadel 9090:9090
kubectl port-forward svc/citadel-grafana -n citadel 3000:80
kubectl port-forward svc/citadel-jaeger-query -n citadel 16686:16686

Gateway — quick counters​

The Node Gateway exposes Prometheus metrics at /metrics.

cd src/CitadelMesh.Gateway
npm run dev
# In another terminal
curl -s http://localhost:7070/metrics | sed -n '1,50p'

Import the prefabricated Grafana dashboard from /grafana/citadel-gateway-dashboard.json (see below) to visualize HTTP counts by route.

One-click port-forwards (optional)​

Use config/k3s/port-forward.sh to open common forwards in separate terminals.

bash config/k3s/port-forward.sh

Grafana dashboard (import)​

  • Navigate to Grafana → Dashboards → Import → Upload /grafana/citadel-gateway-dashboard.json.
  • Set Prometheus as the data source.

You’ll see request volumes grouped by method/route/status.

Tips​

  • Run Aspire for local feature work; use k3s for production validation and SPIRE/mTLS policies.
  • When the Helm OPA template is fixed, re-enable OPA to validate safety flows end-to-end.
  • Keep the Gateway pointed at cluster NATS via port-forward for realistic messaging.