Skip to content

Commit

Permalink
adding tagging feature docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Gregory Woods authored and Gregory Woods committed Jul 23, 2019
1 parent 1efe20a commit c23282c
Show file tree
Hide file tree
Showing 3 changed files with 54 additions and 23 deletions.
3 changes: 2 additions & 1 deletion SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@
* [Query processing](configuring-infrastructure-components/query-processing.md)
* [Deadlines](configuring-infrastructure-components/deadlines.md)

## Operations Guide
## Operations Guide

* [Setting up Axon Server](operations-guide/setting-up-axon-server/setting-up-axon-server.md)
* [Launch](operations-guide/setting-up-axon-server/launch.md)
Expand All @@ -65,6 +65,7 @@
* [Axon Server clustering](operations-guide/setting-up-axon-server/axon-server-clustering.md)
* [Multi-context](operations-guide/setting-up-axon-server/multi-context.md)
* [Command-line interface](operations-guide/setting-up-axon-server/command-line.md)
* [Tagging](operations-guide/setting-up-axon-server/tagging.md)
* [Production considerations](operations-guide/production-considerations/production-considerations.md)
* [Versioning Events](operations-guide/production-considerations/versioning-events.md)
* [Serializers](operations-guide/production-considerations/serializers.md)
Expand Down
47 changes: 25 additions & 22 deletions operations-guide/setting-up-axon-server/axon-server-clustering.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ Axon Server Enterprise can be deployed as a cluster to guarantee high availabili
should the node that they are currently connected to become unreachable.

Within a single cluster you can define contexts. Contexts are comparable to logical databases in a RDBMS. They allow for strong segregation without requiring deploying and managing full instances.
They may be used for "bounded contexts" in the DDD sense, multi-tenancy (with a context per tenant), and different retention policies.
They may be used for "bounded contexts" in the DDD sense, multi-tenancy (with a context per tenant), and different retention policies.
When you define a context, you assign nodes that will serve that context. Data is replicated between these nodes and client connect to these nodes. For replication purposes there is one leader
per context. The leader orchestrates the replication of data and confirms to clients when transactions are committed. To have a valid leader
for a context, a majority of the nodes must be active (when you have a cluster with 3 nodes, you need at least 2 active nodes, for a cluster of 4 nodes you would need 3 active nodes).

Axon Server Enterprise has one special context, called "_admin". This context is used to process all configuration changes in Axon Server, so it contains the master configuration from which
all contexts get their information.
Axon Server Enterprise has one special context, called "_admin". This context is used to process all configuration changes in Axon Server, so it contains the master configuration from which
all contexts get their information.

To get started with Axon Server Enterprise you have perform the following steps:

Expand All @@ -22,14 +22,14 @@ To get started with Axon Server Enterprise you have perform the following steps:
4. add the other nodes to the cluster using the "register-node" command.

When you start a new Axon Server Enterprise instance it does not have any contexts defined and is not capable of handling any commands from clients. This differs from starting a standard
Axon Server which is immediately available for use.
Axon Server which is immediately available for use.

The init-cluster commands creates 2 contexts ("_admin" and "default"). The default context is the context used by clients when they have not specified any context information.
The init-cluster commands creates 2 contexts ("_admin" and "default"). The default context is the context used by clients when they have not specified any context information.
As this node is the only node in the cluster at this point it will be leader in both contexts.

Next you can add more nodes to the cluster. For these nodes, you do not call the init-cluster command, you must add them to the cluster using the register-node command. When you register a
node in the cluster it will be added to all contexts by default. If you want to add it to specific contexts you can specify this in the command. You can always assign or unassign nodes from
a context later, but when you have a large event store synchronizing the data to the new member may take some time.
Next you can add more nodes to the cluster. For these nodes, you do not call the init-cluster command, you must add them to the cluster using the register-node command. When you register a
node in the cluster it will be added to all contexts by default. If you want to add it to specific contexts you can specify this in the command. You can always assign or unassign nodes from
a context later, but when you have a large event store synchronizing the data to the new member may take some time.

All communication between Axon Server nodes uses a dedicated port (8223 by default). When nodes are in different locations you have to make sure that this ports is accessible for all
Axon Server nodes.
Expand All @@ -47,7 +47,7 @@ This must be a unique name in the cluster.

### axoniq.axonserver.hostname

The hostname of the node as it would be used by clients. This defaults to the hostname of the machine, however this may not be the name as it is known externally. The final hostname that is
The hostname of the node as it would be used by clients. This defaults to the hostname of the machine, however this may not be the name as it is known externally. The final hostname that is
communicated to the clients is the combination of this hostname field and the axoniq.axonserver.domain property (if set)

### axoniq.axonserver.domain
Expand All @@ -57,7 +57,7 @@ The domain that is added to the hostname when returning hostnames to client appl
### axoniq.axonserver.internal-hostname

The hostname as it will be used for communication between axonserver nodes. Defaults to the axoniq.axonserver.hostname.
May be used in combination with the internal-domain to make it a fully qualified name.
May be used in combination with the internal-domain to make it a fully qualified name.

### axoniq.axonserver.internal-domain

Expand All @@ -70,13 +70,17 @@ on the same machine, each needs to have a unique port.

### axoniq.axonserver.internal-port

Port used for gRPC communication between Axon Server nodes. Defaults to 8224, when you would want to run multiple nodes
Port used for gRPC communication between Axon Server nodes. Defaults to 8224, when you would want to run multiple nodes
on the same machine, each needs to have a unique port.

### server.port

HTTP port used to access the UI and REST services. Defaults to 8024.

### axoniq.axonserver.clients-connection-strategy

The strategy that is used when clients make connections to Axon Server nodes. Defaults to `subscriptionCount` which balances connections across all nodes based on load. Also configurable to `matchingTags` (which is described [here](../../../operations-guide/setting-up-axon-server/tagging.md)).


## Starting a cluster

Expand All @@ -86,7 +90,7 @@ create the cluster, using the command line interface.
First step is call the init-cluster command on the first node:

```bash
$ java -jar axonserver-cli.jar init-cluster -S http://[node]:[port]
$ java -jar axonserver-cli.jar init-cluster -S http://[node]:[port]
```

With [node] being the hostname of the first node and [port] the HTTP port. When you run this command
Expand All @@ -103,11 +107,11 @@ The next step is to add the other nodes to the cluster, using the register-node
$ java -jar axonserver-cli.jar register-node -S http://[node]:[port] -h [first-node] -p [internal-grpc-port]
```

The values for [node] and [port] are the hostname and HTTP port for the new node to add. The [first-node] is the internal hostname of
The values for [node] and [port] are the hostname and HTTP port for the new node to add. The [first-node] is the internal hostname of
the first node, this should be the name that the new node uses to contact the first node. The [internal-grpc-port] is the port number of
for internal communication on the first node, usually 8224.
for internal communication on the first node, usually 8224.

When you run this command on the new node and you are using default ports you can omit the -S option and the -p option.
When you run this command on the new node and you are using default ports you can omit the -S option and the -p option.

After adding a second node to the cluster you will see this information in the overview page:

Expand All @@ -119,21 +123,20 @@ You can repeat this for the third node, and then you will see the following info

## Access control

Axon Server nodes expect a common token on internal requests when access control is enabled. This token must be defined in the axonserver.properties file
Axon Server nodes expect a common token on internal requests when access control is enabled. This token must be defined in the axonserver.properties file
with the property *axoniq.axonserver.accesscontrol.internal-token*. The value for this property needs to be the same on all nodes.

## Transport Layer Security

Axon Server uses the same key for the internal and external gRPC port for TLS. However you can use different certificates for the two ports.
By default, Axon Server uses the value from *axoniq.axonserver.ssl.cert-chain-file* property, but if you want to use another certificate for the internal communication
set this in the property *axoniq.axonserver.ssl.internal-cert-chain-file*.
Axon Server uses the same key for the internal and external gRPC port for TLS. However you can use different certificates for the two ports.
By default, Axon Server uses the value from *axoniq.axonserver.ssl.cert-chain-file* property, but if you want to use another certificate for the internal communication
set this in the property *axoniq.axonserver.ssl.internal-cert-chain-file*.

If you are using self-signed certificates, or certificates where the CA is not included in the cacerts keystore on the JVM,
If you are using self-signed certificates, or certificates where the CA is not included in the cacerts keystore on the JVM,
specify the CA certificate in the property *axoniq.axonserver.ssl.internal-trust-manager-file*.


## Internal APIs and stability guarantees

Within the endpoints documented in /swagger-ui.html, you can find some /internal/* APIs that are not part of the public APIs.
Within the endpoints documented in /swagger-ui.html, you can find some /internal/* APIs that are not part of the public APIs.
These APIs are not supposed to be used and will change without notice.

27 changes: 27 additions & 0 deletions operations-guide/setting-up-axon-server/tagging.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Configuring Client Connections (Tagging)

> Note - This feature is only available in Axon Server Enterprise
To optimise the connections between framework clients and Axon Server, its is possible to tag both clients and Axon Server with information which describes properties of those clients and nodes. Axon Server will then use these tags to make a connection to the client.

A typical tag could describe where the respective client and server node are running (e.g. a cloud provider's region) encouraging that the nearest, and therefore fastest, connections are made.

## Tag Matching

A match is made when the the label and the value of the tag matches. For example, a server tagged with `"computeRegion": "europe"` will match with a client tag of `"computeRegion": "europe"`. Similarly if server is tagged with `"computeRegion": "europe"` and client is tagged with `"computeRegion": "asia"` then this is not considered a match.

If both client and server are tagged with multiple tags then the connection that is made will be based on the highest number of matches. If multiple nodes have a equal number of matching tags then the node with the lightest load is chosen.

## Enabling tagging

To enable tagging you must modify configuration on both the client and the server.

### Axon Server

Set the value of property `axoniq.axonserver.clients-connection-strategy` to `matchingTags` to enable the tagging connection strategy.

Then configure the tags that you would like for each node through properties using `axoniq.axonserver.tags.computeRegion: europe`. Additional tags can be specified by adding to the `tags` element (e.g. `axoniq.axonserver.tags.networkSpeed: fast`).

### Client

On the client side, you can add tags by using the property `axon.tags.computeRegion: europe` and, similar to server configuration, additional tags can be added.

0 comments on commit c23282c

Please sign in to comment.