Axon Server Google Marketplace Installation Guide

Installing Axon Server using Google Marketplace

Axon Server Enterprise is now listed in Google GCP Marketplace. This allows your team to deploy a single instance or a 3-node cluster Axon Server in your Google Project.

Purpose and intended audience

This guide is intended for engineers, developers, and system administrators who want to install Axon Server on the Google Marketplace.

The guide covers

Requirements for your Google Project
An overview of required and recommended fields
How to deploy a cluster across multiple regions
How to secure your Axon Server installation
Basic maintenance guide for your cluster

Pre-requisites

The network is the backbone for communication between Axon Server Enterprise nodes and applications.

During the installation process, a DNS entry is created for each Axon Server node: this is used to configure and set up communication between the nodes.

VPC Network and Subnetwork
Your Google project must have an existing VPC Network and Subnetwork configured for the zones in where you want to install your cluster: you can define one using the Google Console UI

Cloud DNS Zone
Your Google project must have a Cloud DNS Zone configured: you can define one using the Google Console UI.

Write down the name of your Cloud DNS Zone : it will be requested in a form field during the installation process.

Cloud Resource Manager API
The deployment uses Cloud Resource Manager API, therefore this API must be enabled before proceeding with the installation.

Secret manager API
If you plan to store your sensitive data in Google Secret Manager, you must enable the API first.

Required and recommended fields overview

The following is a list of fields that you will be prompted to fill in during your installation.

Deployment name

This is used in the installation to give the deployment a name and to distinguish it from other deployments in the same Google project.

It is also used as a PREFIX to name resources used by the deployment.

Deployment Service Account / Service account ID / Service Account description

Used by Google as the user to run Terraform: it requires several admin roles because they are used to create resources in the project itself.

Cloud DNS Zone of your network domain (mandatory / prerequisite)

This is a prerequisite that must be created in the project beforehand. It is used to create DNS entries for instances, for example axonserver-1.mydomain.net, axonserver-2.mydomain.net axonserver-3.mydomain.net.

These addresses are used by the configuration for internal calls and can be used by the user to connect to the VM from a running Axon Framework application.

Internal Network Domain

This is the domain to append to the hostname of the VM’s. It should match the value the user entered in the DNS zone details (for example, mydomain.net).

Enable Google Ops Agent This is a non-mandatory option, but recommended. You may incur in additional charges from Google for using this service.

Google Ops Agent is the Google way to collect logs and metrics, and is displayed in the dashboard / log explorer.

Use Google Secret Manager

This is a non-mandatory option, but recommended. You may incur in additional charges from Google for using this service.

If selected, sensitive data such as the admin password (randomly generated during the installation) will be stored in the Google Secrets Manager, where only accounts with specific permissions can access and read/change the value.

If not selected these values will be stored in the VM Metadata : these values can be read by anyone who has access to the Google Dashboard, even users with lower permissions (such as editor role).

Google Secret Manager is mandatory when running multi-region deployments. See Multi-region cluster deployments.

Cluster ID

A unique identifier for your Axon Server cluster, used to name secrets and cloud resources shared across deployments.

For a standard single-deployment installation, any meaningful name will do (for example, axonserver-prod). For multi-region deployments, all deployments that belong to the same cluster must share the same Cluster ID-this is how separate deployments discover and share each other’s credentials.

Axoniq Platform Axon Server Token

This is a non-mandatory option.

Allows you to delegate license provisioning and initial cluster configuration to Axoniq Platform. When set, Axon Server will retrieve its license and bootstrap configuration from the platform rather than using local settings.

If you use this option, your license must be purchased through Axoniq Platform.

Join Existing Cluster

This is a non-mandatory option.

When enabled, the nodes in this deployment will join an existing cluster instead of bootstrapping a new one. Use this when adding nodes to a cluster that is already running-for example, when scaling out or when deploying across multiple regions.

When this option is selected, no new secrets or tokens are created. The credentials established by the original deployment are reused.

Autocluster First Node Hostname

This is a non-mandatory option.

The internal hostname of the first node in the existing cluster (for example, axonserver-0.mydomain.net). When set, new nodes use this address to locate and join the running cluster.

This field is required when deploying across multiple regions. See Multi-region cluster deployments for the full procedure.

Instance Count

The number of Axon Server nodes to deploy in this group. Accepted values are 1 to 3. For a production-grade cluster with high availability, 3 nodes is recommended. A single node is suitable for development or testing purposes.

Disk configuration

Each node is provisioned with two dedicated data disks in addition to the boot disk:

Disk for replication logs and configuration-stores Axon Server’s internal replication data and configuration files. The default size is 10 GB; adjust based on your expected cluster activity.
Disk for event store-stores your application’s events and is typically the largest disk. The default size is 100 GB; adjust based on your expected event volume and retention requirements.

Both disks persist independently of the VM instance, so data survives restarts.

Firewall rules

The deployment creates firewall rules for the following ports. Each rule can be enabled or disabled independently, and access can be restricted to specific source IP ranges using CIDR notation.

Port	Protocol	Purpose
22	TCP	SSH access to the VMs. Recommended to restrict to known IP ranges in production.
7000	TCP	Communication with Axoniq Platform. Required when using the Axoniq Platform Axon Server Token option.
7001	TCP	gRPC connections from Axon Framework applications.
8024	TCP	HTTP connections and the Axon Server Admin UI.
8124	TCP	Internal cluster communication. Mandatory-must remain enabled for nodes to replicate data.
8224	TCP	Internal cluster communication. Mandatory-must remain enabled for nodes to replicate data.

Port

Protocol

Purpose

TCP

SSH access to the VMs. Recommended to restrict to known IP ranges in production.

7000

TCP

Communication with Axoniq Platform. Required when using the Axoniq Platform Axon Server Token option.

7001

TCP

gRPC connections from Axon Framework applications.

8024

TCP

HTTP connections and the Axon Server Admin UI.

8124

TCP

Internal cluster communication. Mandatory-must remain enabled for nodes to replicate data.

8224

TCP

Internal cluster communication. Mandatory-must remain enabled for nodes to replicate data.

Multi-region cluster deployments

Axon Server Enterprise supports distributing cluster nodes across multiple regions or availability zones. This is useful when you need to improve resilience, reduce latency, or meet data-locality requirements.

In this model, each group of nodes that shares the same availability zone is managed as a separate Marketplace deployment. The deployments are linked together by a shared Cluster ID, which causes them to share secrets and cluster membership.

Requirements

Google Secret Manager must be enabled on all deployments.
This is the mechanism that allows separate deployments to share credentials securely. Make sure the Use Google Secret Manager option is selected on every deployment before proceeding.

Steps

Deploy your first group of nodes.
Fill in all required fields as normal and choose a meaningful, unique Cluster ID (for example, axonserver-prod). Complete this deployment and wait for all nodes to be up and healthy before continuing.
Retrieve the internal hostname of the first node.
Once the first deployment is running, open the Axon Server UI on any of its nodes and note the internal hostname of node 0 (for example, axonserver-0.mydomain.net).
You can reach the UI by opening a tunnel with the following command:
```
gcloud compute start-iap-tunnel YOUR_INSTANCE_NAME-0 --project=YOUR_PROJECT_ID --zone=YOUR_ZONE 8024 --local-host-port=localhost:8024
```
Then open http://localhost:8024 in your browser. The default username is admin; see the UI credentials note in the maintenance section for how to retrieve the password.
Deploy each additional group of nodes.
For every subsequent deployment-one per additional region or availability zone-configure the following fields:
- Cluster ID-must be identical to the one used in the first deployment.
- Use Google Secret Manager-must be enabled.
- Join Existing Cluster-enable this so the new nodes attach to the existing cluster rather than forming a new one.
- Autocluster First Node Hostname-set this to the internal hostname retrieved in step 2.

Repeat step 3 for each additional region you need to cover.

Basic maintenance of your cluster

After installation

At the end of a successful deployment, the Marketplace shows the following output values:

Admin URL-the URL to reach the Axon Server Admin UI.
Username-the default admin username (admin).
Password-the randomly generated admin password.
Internal Token-the internal cluster token used for inter-node authentication.

Make a note of these values before leaving the page. If you missed them, both the admin password and the internal token are also stored as secrets in Google Secret Manager (if that option was enabled), named after your Cluster ID-for example, axonserver-prod-admin-password and axonserver-prod-internal-token.

After the installing Axon Server Enterprise three new VMs will be available in your project.

You can gather the list of available VMs using the following command

gcloud compute instances list --project=YOUR_PROJECT_ID

If you want to adjust some properties for your cluster, you can ssh into your machine with the following command

gcloud compute ssh YOUR_INSTANCE_NAME-0 --project=YOUR_PROJECT_ID --zone=YOUR_ZONE

You can connect to the AxonServer UI by opening a tunnel on port 8024 to one of the instances in your cluster, and then opening http://localhost:8024 in your browser.

gcloud compute start-iap-tunnel YOUR_INSTANCE_NAME-0 --project=YOUR_PROJECT_ID --zone=YOUR_ZONE 8024 --local-host-port=localhost:8024

The default username is admin. The password is displayed at the end of the Marketplace installation process. If you missed it, you can also retrieve it from the Google Secret Manager-look for the secret named after your Cluster ID (for example, axonserver-prod-admin-password).

Check logs and VMs resources

If you enabled Google Ops Agent during the installation, you can check the logs by going to Google Logs Explorer and selecting axonserver in the _Select log names dropdown.

The Observability panel of your VMs will display important information such as CPU Utilization, Memory Utilization, Disk Space Utilization, Disk IOPS and details of running processes

If you haven’t enabled the Google Ops Agent option, you can check the logs and VM resources using Axonserver UI or by opening an ssh connection to the VM.

Update your Axon Server

Axon Server is installed as a Linux package in your VM instance. You can then update it as a regular package, using sudo apt update axonserver -y
After the update process, you will need to stop and restart the process.

sudo systemctl stop axonserver
sudo systemctl start axonserver

As a regular Axon Server cluster, we recommend that you update and restart a single instance at a time to ensure that your cluster is running with zero downtime. After each restart, you need to check the health of your cluster. You can do this by looking at one of your AxonServer UIs that is not restarting.

Secure your AxonServer installation

By default, your cluster is installed without TLS/SSL enabled.

To secure your AxonServer installation and prepare it for production, please consult the Security section of the Axon Server reference guide.