Terraform Module to Deploy Axon Server on Kubernetes

---

Usage

Single Node Deployment

For a single node deployment, you don't need to provide a license or console authentication:

module "axonserver" {
  source = "[email protected]:AxonIQ/terraform-axonserver-k8s.git?ref=v1.20"
  
  axonserver_tag = "2025.1.5-jdk-17"

  nodes_number  = 1
  cluster_name  = "axonserver"
  public_domain = "axoniq.net"
  namespace     = "axonserver"
}

Multi-Node Cluster Deployment

For multi-node deployments (clustering), you must provide either a license file or console authentication token:

module "axonserver" {
  source = "[email protected]:AxonIQ/terraform-axonserver-k8s.git?ref=v1.20"
  
  axonserver_tag = "2025.1.5-jdk-17"

  nodes_number  = 3
  cluster_name  = "axonserver"
  public_domain = "axoniq.net"
  namespace     = "axonserver"
  
  # Option 1: Provide a license file
  axonserver_license_path = file("${path.module}/axoniq.license")
  
  # Option 2: Or use console authentication (Axon Server Cloud)
  # console_authentication = "your-console-token"
  
  # Optional: Custom properties file
  axonserver_properties = file("${path.module}/axonserver.properties")
}

GKE Network Endpoint Groups (NEGs)

To enable GKE NEGs for direct pod communication:

module "axonserver" {
  source = "[email protected]:AxonIQ/terraform-axonserver-k8s.git?ref=v1.20"
  
  axonserver_tag = "2025.1.5-jdk-17"

  nodes_number  = 3
  cluster_name  = "axonserver"
  public_domain = "axoniq.net"
  namespace     = "axonserver"
  
  axonserver_license_path = file("${path.module}/axoniq.license")
  
  # Enable NEGs for GKE
  gke_neg      = true
  gke_neg_zone = ["us-central1-a", "us-central1-b", "us-central1-c"]
}

Advanced Configuration

For advanced scenarios with custom JVM options and access control settings:

module "axonserver" {
  source = "[email protected]:AxonIQ/terraform-axonserver-k8s.git?ref=v1.20"
  
  axonserver_tag = "2025.1.5-jdk-17"

  nodes_number  = 3
  cluster_name  = "axonserver"
  public_domain = "axoniq.net"
  namespace     = "axonserver"
  
  axonserver_license_path = file("${path.module}/axoniq.license")
  
  # Custom JVM options
  java_tool_options = "-Xmx2g -Xms2g -XX:+UseG1GC"
  
  # Disable access control (not recommended for production)
  accesscontrol_enabled = false
}

Deploy your own Axon Server image

If you want to deploy another Axon Server docker image, different from the one in axoniq/axonserver:

module "axonserver" {
  source = "[email protected]:AxonIQ/terraform-axonserver-k8s.git?ref=v1.20"
  
  axonserver_tag = "2025.1.5-jdk-17"
  axonserver_image = "eu.gcr.io/my-project/axonserver"

  nodes_number  = 1
  cluster_name  = "axonserver"
  public_domain = "axoniq.net"
  namespace     = "axonserver"
}

Inputs

Name	Description	Type	Default	Required
axonserver_tag	Axon Server Tag	string	"latest"	no
axonserver_image	Axon Server image URL repo	string	"axoniq/axonserver"	no
image_pull_policy	Determines when Kubernetes pulls a container image from the registry	string	"IfNotPresent"	no
namespace	Kubernetes cluster namespace	string	"axonserver"	no
create_namespace	Whether to create the namespace or use an existing one	bool	true	no
cluster_name	Axon Server cluster name	string	""	yes
nodes_number	Number of Axon Server nodes to deploy. When > 1, either console_authentication or axonserver_license_path is required	number	1	yes
public_domain	The domain that is added to the hostname when returning hostnames to client applications	string	""	yes
axonserver_license_path	Path to the Axon Server license file. Required for multi-node deployments (nodes_number > 1) unless console_authentication is provided	string	""	conditional
console_authentication	Console authentication token for Axon Server Cloud. Required for multi-node deployments (nodes_number > 1) unless axonserver_license_path is provided	string	""	conditional
axonserver_properties	Custom Axon Server properties file content. If not provided, a default configuration will be generated	string	""	no
java_tool_options	Java tool options for passing custom JVM options to Axon Server (e.g., heap size, GC settings)	string	""	no
accesscontrol_enabled	Enable Axon Server access control. Recommended to keep enabled in production	bool	true	no
resources_limits_cpu	CPU resource limits for Axon Server pods	number	1	no
resources_limits_memory	Memory resource limits for Axon Server pods	string	"1Gi"	no
resources_requests_cpu	CPU resource requests for Axon Server pods	number	1	no
resources_requests_memory	Memory resource requests for Axon Server pods	string	"1Gi"	no
events_storage	Persistent volume size for event storage	string	"5Gi"	no
log_storage	Persistent volume size for log storage	string	"2Gi"	no
data_storage	Persistent volume size for data storage	string	"10Gi"	no
plugins_storage	Persistent volume size for plugins storage	string	"1Gi"	no
license_storage	Persistent volume size for license storage (only used with console_authentication)	string	"1Gi"	no
devmode_enabled	Enable Axon Server development mode (disables security features)	bool	false	no
assign_pods_to_different_nodes	Use pod anti-affinity to avoid co-location of replicas on the same Kubernetes node	bool	false	no
gke_neg	Enable GKE Network Endpoint Groups (NEGs) for direct pod communication. When enabled, gke_neg_zone must be provided	bool	false	no
gke_neg_zone	List of GKE zones for NEG configuration. Required when gke_neg is true	list(string)	[]	conditional

Outputs

Name	Description
axonserver_token	The Axon Server internal token, automatically generated by Terraform

Important Notes

Clustering Requirements

When deploying a multi-node cluster (nodes_number > 1), you must provide one of the following:

• axonserver_license_path: Path to your Axon Server Enterprise license file
• console_authentication: Authentication token for Axon Server Cloud

Single node deployments (nodes_number = 1) do not require either of these parameters.

GKE Network Endpoint Groups

When enabling GKE NEGs (gke_neg = true), you must provide at least one zone in gke_neg_zone. This feature creates Network Endpoint Groups for direct pod communication, useful for:

• Load balancing directly to pods
• Bypassing kube-proxy
• Improved performance for gRPC connections

Access Control

Access control is enabled by default (accesscontrol_enabled = true). This is the recommended setting for production environments. Only disable access control in development or testing scenarios where security is not a concern.

Providers

Name	Version
kubernetes	>= 2.31.0
random	>= 3.6.2

Requirements

Name	Version
terraform	>= 1.9.0

License

Apache 2 Licensed. See LICENSE for full details.

Authors

Made with contrib.rocks.