Axon Server Proxy Reference Guide
This reference guide covers Axon Server Proxy, a lightweight proxy server for Axon Server clusters.
What is Axon Server Proxy?
Axon Server Proxy is a gRPC proxy server that sits between Axon Framework applications and an Axon Server cluster. It provides a single entry point for applications, eliminating the need for them to directly address individual Axon Server nodes.
Key features
-
Simplified Networking: Applications only need to know the proxy address, not individual Axon Server node addresses
-
Transparent Proxying: Applications interact with the proxy exactly as they would with Axon Server
-
TLS Support: Independently configurable TLS for incoming connections (from applications) and outgoing connections (to Axon Server), so the proxy can fit into environments with different security policies on each side
-
Monitoring: Built-in metrics and health endpoints for observability
-
Native Image Support: Can be compiled to a native executable using GraalVM
Use cases
The Axon Server Proxy is particularly useful in these scenarios:
-
Load Balancer Integration: Place a TCP load balancer or ingress controller between applications and Axon Server. The load balancer handles traffic distribution while the proxy manages Axon Server-specific routing rules and context-based connections.
-
Network Segmentation: When application networks cannot directly reach all Axon Server nodes
-
Cloud Deployments: Where individual node addressing is complex or unstable
-
Kubernetes Environments: Simplifying service discovery and routing
-
Multi-Region Deployments: Providing a stable entry point across network boundaries
-
Mixed Security Zones: When applications and Axon Server nodes are in different trust domains with different TLS requirements. For example, TLS from applications to the proxy but plaintext on the internal cluster network, or the reverse
Architecture
The proxy sits between your applications and the Axon Server cluster, establishing bidirectional streaming gRPC connections. It maintains connection state and routes messages based on the Axon Server context and client identification.
Basic deployment
In a simple deployment, applications connect directly to the proxy:
Applications → Proxy → Axon Server Cluster
(gRPC) (gRPC)With load balancer
For high availability, you can deploy multiple proxy instances behind a load balancer. The load balancer performs simple TCP load balancing, while each proxy instance handles the Axon Server-specific routing rules:
Applications → Load Balancer → Proxy Instances → Axon Server Cluster
(TCP balancing) (Axon routing) (gRPC)This separation allows standard load balancers to distribute traffic without understanding Axon Server’s routing semantics.
The proxy handles:
-
Command dispatching
-
Query routing
-
Event streaming
-
Subscription management
All communication is transparent - applications use the standard Axon Server Connector and are unaware they’re communicating through a proxy.