Cluster Templates

Cluster Templates enable administrators to maintain AxonServer cluster configuration as code.

The cluster template is a YAML file, describing a cluster’s configuration. It’s possible to predefine replication groups, contexts, metadata, applications (with tokens), users, and their roles, so that teams can share the configuration.

The cluster template runs exactly once, on the first clean Axon Server start-up, if there is no previous cluster configuration defined. Therefore, the cluster template doesn’t override any existing configuration. Its purpose is to use them during active development, to be able to share the configuration across development teams.

Usage

To use the cluster template feature, all you need to do is define a valid cluster template YAML file. If this file is present on a fresh Axon Server startup, it automatically picks it up and configures the cluster accordingly.

Each cluster node needs to have the cluster template YAML file copy. Each node reads this file, finds its own configuration and configures itself.

Default path from which Axon Server reads configuration is ./cluster-template.yml

You can override this path anytime by setting Axon Server property: axoniq.axonserver.clustertemplate.path:/mypath/cluster-template.yml

Configuration

Below you can find an example of a basic cluster setup: the _admin and default contexts are in separate replication groups, replicated across all nodes.

axoniq:
  axonserver:
    cluster-template:
      first: axonserver-enterprise-1
      replicationGroups:
      - name: _admin
        roles:
        - node: axonserver-enterprise-1
          role: PRIMARY
        - node: axonserver-enterprise-2
          role: PRIMARY
        - node: axonserver-enterprise-3
          role: PRIMARY
        contexts:
        - name: _admin
      - name: default
        roles:
        - node: axonserver-enterprise-2
          role: PRIMARY
        - node: axonserver-enterprise-3
          role: PRIMARY
        - node: axonserver-enterprise-1
          role: PRIMARY
        contexts:
        - name: default
      applications: []
      users: []

Cluster overview after applying the default configuration

Cluster overview after applying default configuration

Export

In order to avoid mistakes while writing a cluster configuration file, Axon Server provides an export button that generates a cluster template file based on current setup.

Location of export button at Settings page

Recommended mechanism - Creating an advanced cluster setup

Start a fresh Axon Server setup (use basic cluster template setup mentioned above).
Configure a cluster via the UI, by creating users, applications, replication groups and contexts.
Use the export button located at "Settings -> Configuration" panel to download the current cluster configuration.
Replace the basic cluster template with the newly exported cluster template configuration.

Use export button from main - leader node. Leader node always contains complete cluster configuration, while it might happen that followers don’t.