Deployment

This guide covers deploying the DSX Event Bus into a DSX AI Factory. Each Kubernetes cluster (one CSC, one or more CPCs) runs its own event bus instance. CPC instances federate to the CSC via NATS leaf node connections through a Kubernetes Gateway API controller.

Before starting, ensure all infrastructure prerequisites, secrets, and certificates are provisioned. See Pre-Deployment for the full checklist. For day-2 operations, monitoring, and configuration tuning, see Operations.

Evaluation Install (~10 minutes)

To evaluate DSX Exchange locally without Vault, VSO, or production certificate infrastructure, use the local/ evaluation framework. This creates Kind clusters and deploys a fully functional event bus:

$
make -C local setup-infra      # Kind clusters + MetalLB + Envoy Gateway + cert-manager + Keycloak
$
make -C local deploy-nats       # Deploy NATS event bus to all clusters
$
make -C local validate-nats     # Verify connectivity

See local/README.md for the full set of evaluation targets including functional tests, performance benchmarks, and MQTT client tooling.

If you already have access to a running broker and need to build or test an MQTT integration application, use the Integrator Quickstart instead of this operator deployment flow.

The rest of this page covers the production deployment path.

Prerequisites

Version-pinned where there is a known compatibility break; see Pre-Deployment for details.

• Kubernetes 1.27+ — Gateway API CRDs require this minimum
• Helm 4.0+ — Helm 3 is not supported
• Envoy Gateway 1.5+ or compatible Gateway API controller — TCPRoute/TLSRoute v1alpha2 APIs
• MetalLB 0.13+ or cloud LoadBalancer — CRD-based config (IPAddressPool)
• cert-manager
• Prometheus Operator
• Keycloak or OIDC provider (if using OAuth2)
• Secrets pipeline that materializes Kubernetes Secrets (e.g., Vault with Vault Secrets Operator)

Resource Requirements (defaults — configurable per deployment)

Install Order

1. Infrastructure (Gateway API controller, MetalLB, cert-manager)
2. Keycloak or OIDC provider (if using OAuth2)
3. Build the auth-callout container image — see Pre-Deployment
4. CSC cluster event bus
5. CPC cluster event buses (connect to CSC via leaf nodes)

Secrets

All NKey secrets must be provisioned before deploying the event bus. Any secrets pipeline that materializes Kubernetes Secrets works (see Pre-Deployment — Secrets Pipeline). Generate keys locally with the provided script:

$
# Generate secrets for CSC with CPC IDs 1 and 2
$
./deploy/scripts/generate-nkeys.sh -c csc 1 2
$
$
# Generate secrets for CPC-1
$
./deploy/scripts/generate-nkeys.sh -c cpc-1

See Authentication for details on the auth model and required keys.

Deploying the Event Bus

CSC Cluster

$
helm dependency update ./deploy/nats-event-bus
$
$
helm install dsx ./deploy/nats-event-bus \
>
  -n dsx --create-namespace \
>
  -f values-common.yaml \
>
  -f values-csc.yaml

CSC values configure the cluster type, list of CPC IDs that will connect, and auth permissions:

1
global:
2
  eventBus:
3
    clusterType: csc
4
    cpcIds: ["1", "2"]
5
    auth:
6
      permissions:
7
        oauth2:
8
          mqtt-client:
9
            azp: "mqtt-client"
10
            account: "CSC"
11
            permissions:
12
              pub:
13
                allow: ["events.>"]
14
              sub:
15
                allow: ["events.>"]
16
        mtls:
17
          mqtt-client:
18
            identity: "CN=mqtt-client.csc"
19
            account: "CSC"
20
        noauth:
21
          account: "CSC"

If using OAuth2, configure the JWKS endpoint and issuer so the auth-callout can validate tokens. This must be set on every cluster (CSC and each CPC), not just the CSC — without it, that cluster’s auth-callout cannot validate JWTs and will silently reject all OAuth2 connections:

1
auth-callout:
2
  serviceConfig:
3
    jwks:
4
      url: "https://keycloak.example.com/realms/event-bus/protocol/openid-connect/certs"
5
      issuer: "https://keycloak.example.com/realms/event-bus"

The CSC also needs CPC leaf user public keys to authorize incoming leaf connections. The chart generates auth-callout env refs from global.eventBus.cpcIds; create matching nats-leaf-cpc-{id} secrets with a pubkey key.

CPC Clusters

$
helm install dsx ./deploy/nats-event-bus \
>
  -n dsx --create-namespace \
>
  -f values-common.yaml \
>
  -f values-cpc.yaml \
>
  -f values-cpc-1.yaml    # cluster-specific overrides

CPC values set the cluster type, cluster ID, CSC endpoint, and cross-layer routing:

1
global:
2
  eventBus:
3
    clusterType: cpc
4
    clusterId: "1"
5
    cscEndpoint: "nats://csc-gateway:7422"
6
    crossLayer:
7
      cscExports: ["broadcast.>"]
8
      cscPrefixedExports: ["command.>"]
9
      cpcExports: ["sensor.>"]

If using OAuth2, each CPC also needs the auth-callout.serviceConfig.jwks block — see the CSC section above. Without it, OAuth2 connections to this CPC are silently rejected.

Cross-Layer Routing

Cross-layer settings control which topics are copied between the CPC local topic space and the CSC unified topic space:

The three lists must not overlap. A subject pattern that appears in more than one list creates cyclic NATS imports that crash the NATS pod (CrashLoopBackOff) with no user-facing error at install time.

Gateway Configuration

Configure Gateway API listeners and TCPRoute/TLSRoute resources for external access:

1
global:
2
  eventBus:
3
    gateway:
4
      routes:
5
        mqtt:
6
          enabled: true
7
          kind: TCPRoute
8
          gatewayName: event-bus-gateway
9
          gatewayNamespace: event-bus
10
          sectionName: mqtt
11
        natsClient:
12
          enabled: true
13
          kind: TCPRoute
14
          gatewayName: event-bus-gateway
15
          gatewayNamespace: event-bus
16
          sectionName: nats-client
17
        natsLeafnode:
18
          enabled: true
19
          kind: TCPRoute
20
          gatewayName: event-bus-gateway
21
          gatewayNamespace: event-bus
22
          sectionName: nats-leafnode
23
        mqttMtls:
24
          enabled: true
25
          kind: TLSRoute
26
          gatewayName: event-bus-gateway
27
          gatewayNamespace: event-bus
28
          sectionName: mqtt-mtls
29
          hostnames: ["event-bus.example.com"]

mTLS Hostname Agreement

The mqttMtls route uses a TLSRoute (Passthrough mode). Three values must agree or clients get a silent connection reset:

1. Server certificate SANs — the hostname or IP the cert is issued for
2. mqttMtls.hostnames — the SNI values the TLSRoute accepts
3. Client broker URL — MQTT clients derive SNI from the host portion of the URL

If a client connects to ssl://<LB-IP>:8883, it sends SNI=<LB-IP>. If the TLSRoute hostname is a DNS name, Envoy drops the connection before the TLS handshake reaches the NATS pod. Either add the LB IP to both the cert SANs and the TLSRoute hostnames, or assign a DNS name to the LB IP and have clients use that name.

Validation

$
# Check all pods are running
$
kubectl get pods -n dsx
$
$
# Test MQTT connectivity
$
mqttx pub -h $GATEWAY_IP -p 1883 -t test/topic -m "hello" \
>
  -u "oauthtoken" -P "$ACCESS_TOKEN" -V 3.1.1
$
$
# Test NATS connectivity
$
nats pub test.topic "hello" --server nats://$GATEWAY_IP:4222

Monitoring

NATS Surveyor exports Prometheus metrics from the NATS cluster. The mTLS cluster’s SYS account is federated to the main cluster via leaf node, enabling centralized monitoring of both instances.

Key NATS metric families:

• nats_core_* — server metrics (connections, messages, bytes)
• nats_account_* — per-account metrics
• nats_jetstream_* — stream and consumer metrics