Skip to content

Commit

Permalink
GitBook: [master] 12 pages modified
Browse files Browse the repository at this point in the history
  • Loading branch information
domaincomponents authored and gitbook-bot committed Jul 27, 2020
1 parent e2c5025 commit 840c158
Show file tree
Hide file tree
Showing 12 changed files with 78 additions and 76 deletions.
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,4 @@ The Axon platform consists of Axon Framework and Axon Server. It is provided by
* The commercial version, called "Axon Server Enterprise", as well as the various "Packs", are closed source and provided under a commercial license agreement.

If you have any questions about licensing, or want to obtain a license to our commercial software, please contact us via [axoniq.io](https://axoniq.io) or [sales@axoniq.io](mailto:sales@axoniq.io).

2 changes: 1 addition & 1 deletion axon-framework/monitoring-and-metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -313,5 +313,5 @@ public class MetricsConfig {
configurer.configureMessageMonitor(QueryBus.class, messageMonitorFactory);
}
}

```

2 changes: 1 addition & 1 deletion axon-framework/queries/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ A summary of the various sub-sections is given below.
| [Query Dispatchers](query-dispatchers.md) / [Query Handlers](query-handlers.md) | Functional Development concerns for Query Messages using the Axon Framework |
| [Implementations](implementations.md) | Non-Functional Development concerns for Query Messages using the Axon Framework |
| [Configuration](configuration.md) | Configuration concerns for Query Messages using the Axon Framework |
| [Exception Handling]() | Exception Handling concerns for Query Messages using the Axon Framework |
| [Exception Handling](./) | Exception Handling concerns for Query Messages using the Axon Framework |

This guide is complemented by a video tutorial which gives a practical demonstration of the concepts explained in this section. The tutorial is available at -> [Axon Coding Tutorial - Query Messages](https://www.youtube.com/watch?v=jS1vfc5EohM&feature=youtu.be)

Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ The system configuration can be maintained/supplied in three ways.

### _Configuration File_

The most commonly and preferred way is to have an _axonserver.properties_ or _\_ \_axonserver.yml _\_\*\*\_file which contains the desired configuration parameters. The location of the file should be the current working directory or alternatively can be placed within a "\_config"_ subdirectory \(relative to the current working directory\).
The most commonly and preferred way is to have an _axonserver.properties_ or _\_ \_axonserver.yml _\_\*\*\_file which contains the desired configuration parameters. The location of the file should be the current working directory or alternatively can be placed within a "\_config"\_ subdirectory \(relative to the current working directory\).

An important note - In case both files are detected by Axon Server, it will read from both.

Expand Down
4 changes: 2 additions & 2 deletions axon-server/administration/multi-context.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@

> Note: This feature is only available on the Enterprise Edition of AxonServer
To recap the definition as we have seen in the [clustering]() section, contexts allow for strong segregation of data without requiring deploying and managing full instances.
To recap the definition as we have seen in the [clustering](multi-context.md) section, contexts allow for strong segregation of data without requiring deploying and managing full instances.

An Axon Server EE cluster can be setup to store events for multiple contexts. Each context has it own set of files \(containing Event/Snapshot data\) stored in a separate directory. The creation process involves the addition of member nodes within a cluster that will serve that context and the provisioning of a separate physical directory on each of those member nodes. The location of the newly created directory would be under the _root data directory_ of the member node.

A depiction of multiple registered contexts within an Axon Server EE cluster is shown below

![Multiple contexts within an Axon Server EE cluster](../../.gitbook/assets/multi-context.jpg)

The [clustering]() section details the creation of the \__admin and default contexts_ when a new Axon Server cluster is created. The _\_admin_ context **is used to process all configuration changes in Axon Server, so it contains the master configuration from which all contexts get their information. The** \__admin_ context does not have an event store and the configuration information is stored in a control database. The _default_ context is the context used by clients when they have not specified any context information. In case you would like to create a cluster without creating a default context, it is recommended to use the [Automatic-Initialization]() feature where you can control explicitly which contexts can be created or not.
The [clustering](multi-context.md) section details the creation of the \__admin and default contexts_ when a new Axon Server cluster is created. The _\_admin_ context **is used to process all configuration changes in Axon Server, so it contains the master configuration from which all contexts get their information. The** \__admin_ context does not have an event store and the configuration information is stored in a control database. The _default_ context is the context used by clients when they have not specified any context information. In case you would like to create a cluster without creating a default context, it is recommended to use the [Automatic-Initialization](multi-context.md) feature where you can control explicitly which contexts can be created or not.

## Context Maintenance

Expand Down
2 changes: 1 addition & 1 deletion axon-server/installation/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,5 @@ A summary of the various sub-sections is given below:
| Sub-Section | Purpose |
| :--- | :--- |
| [Local Installation](local-installation/) | Covers all aspects of installing Axon Server SE/EE locally. |
| [Docker / K8s](https://github.com/domaincomponents/reference-guide/tree/4956c6e019f17c74b15fc46eca23dc6abc33e514/axon-server/installation/docker-k8s/README.md) | Covers all aspects of installing Axon Server SE/EE in Docker / K8s. |
| [Docker / K8s](docker-k8s/) | Covers all aspects of installing Axon Server SE/EE in Docker / K8s. |

2 changes: 1 addition & 1 deletion axon-server/installation/docker-k8s/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Docker / K8s

Axon provides support for Axon Server SE/EE to be run as Docker images utilizing plain Docker images / Docker Compose or larger-scale infrastructural products such as Kubernetes, Cloud-Foundry or Red Hat OpenShift.
Axon provides support for Axon Server SE/EE to be run as Docker images utilizing plain Docker images / Docker Compose or larger-scale infrastructural products such as Kubernetes, Cloud-Foundry or Red Hat OpenShift.

| Version | |
| :--- | :--- |
Expand Down
16 changes: 8 additions & 8 deletions axon-server/installation/docker-k8s/axon-server-ee.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ This section is split into 3 sub-sections.
* [Deployment using Docker Compose ](axon-server-ee.md#docker-compose)and
* [Deployment using Kubernetes](axon-server-ee.md#kubernetes)

### Construction of the Image
## Construction of the Image

Axon does not provide a public image for Axon Server EE. A starter Dockerfile is included below which can be tailored as per your requirements. This will work for OpenShift, Kubernetes, as well as Docker and Docker Compose.

Expand Down Expand Up @@ -63,11 +63,11 @@ $ docker build --tag ${TAG} .

The ${TAG} could be any tag that you would like to give to the Axon Server EE Docker image. This completes the construction of the Docker image. The image can pushed to your local repository or you could keep it local if you only want to run it on your development machine. The next step is to run it either using [Docker Compose](axon-server-ee.md#docker-compose) or [Kubernetes](axon-server-ee.md#kubernetes).

### Docker Compose
## Docker Compose

Axon Server EE is meant to be run in a distributed manner i.e. as a cluster where there will be multiple instances of Axon Server EE nodes running all interconnected to each other.
Axon Server EE is meant to be run in a distributed manner i.e. as a cluster where there will be multiple instances of Axon Server EE nodes running all interconnected to each other.

The installation process assumes that Docker Compose will be used to run a 3-node Axon Server EE cluster i.e. running 3 services of the same container image we built above. Let us designate these services as "_axonserver-1_", "_axonserver-2_" and "_axonserver-3_". We will also give a tag to the image that we constructed above as "_axonserver-ee:running_".
The installation process assumes that Docker Compose will be used to run a 3-node Axon Server EE cluster i.e. running 3 services of the same container image we built above. Let us designate these services as "_axonserver-1_", "_axonserver-2_" and "_axonserver-3_". We will also give a tag to the image that we constructed above as "_axonserver-ee:running_".

Each container instance will use separate volumes for “data”, “events”, and “log”. We will use "secrets" to inject the license file, tokens as well as the cluster/context definitions using the [autocluster](../local-installation/axon-server-ee.md#auto-clustering) mechanism. An environment variable is added to tell Axon Server about the location of the license file.

Expand Down Expand Up @@ -231,11 +231,11 @@ Starting Axon Server EE using the docker-compose command is depicted below.
$ docker-compose up
```

### Kubernetes
## Kubernetes

The deployment of Axon Server EE on Kubernetes essentially follows the same principle as we have seen for Axon Server SE i.e. using Stateful Sets. However to cater to the distributed deployment topology of Axon Server EE, there will be some changes that would need to be done.

The Dockerfile that we [built](axon-server-ee.md#construction-of-the-image) above would need a change. This is due to the fact that volumes are mounted as owned by the mount location’s owner in Docker, while Kubernetes uses a special security context, defaulting to root. Since our EE image runs Axon Server under its own user \(axonserveree\), it has no rights on the mounted volume other than “read”. The context can be specified, but only through the user or group’s ID, and not using their name as we did in the image, because that name does not exist in the k8s management context. So we have to adjust the first stage to specify a specific numeric value _\(here we have given 1001\)_ , and then use that value in the security context of the Stateful set which we shall see below.
The Dockerfile that we [built](axon-server-ee.md#construction-of-the-image) above would need a change. This is due to the fact that volumes are mounted as owned by the mount location’s owner in Docker, while Kubernetes uses a special security context, defaulting to root. Since our EE image runs Axon Server under its own user \(axonserveree\), it has no rights on the mounted volume other than “read”. The context can be specified, but only through the user or group’s ID, and not using their name as we did in the image, because that name does not exist in the k8s management context. So we have to adjust the first stage to specify a specific numeric value _\(here we have given 1001\)_ , and then use that value in the security context of the Stateful set which we shall see below.

The change is depicted below. As before, create the image using _docker build_ and give it a tag \(e.g. axonserveree-running\)

Expand All @@ -259,7 +259,7 @@ $ kubectl create secret generic axonserveree-token --from-file=./axoniq.token -n
secret/axonserver-token created
$ kubectl create configmap axonserveree-properties --from-file=./axonserver.properties -n ${axonserveree-ns}
configmap/axonserver-properties created
$
$
```

In the descriptor we now have to declare the secret, add a volume for it, and mount the secret on the volume. Then a list of volumes has to be added to link the actual license and properties.
Expand Down Expand Up @@ -374,7 +374,7 @@ $ kubectl apply -f axonserver-sts.yml -n ${axonserveree-ns}
statefulset.apps/axonserveree created
```

The next step would be to create the two services required for Axon Server EE i.e. axonserver-gui on 8024 \(HTTP\) and axonserver on 8124 \(gRPC\).
The next step would be to create the two services required for Axon Server EE i.e. axonserver-gui on 8024 \(HTTP\) and axonserver on 8124 \(gRPC\).

```text
---
Expand Down
22 changes: 11 additions & 11 deletions axon-server/installation/docker-k8s/axon-server-se.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@ This section is split into 3 sub-sections.
* [Deployment using Docker Compose](axon-server-se.md#docker-compose)
* [Deployment using Kubernetes](axon-server-se.md#kubernetes)

### Docker Image
## Docker Image

Axon provides a ready to use [Axon Server SE image](https://hub.docker.com/r/axoniq/axonserver/). The image is built using a compact image from Google’s “distroless” base images at the gcr.io repository, in this case “gcr.io/distroless/java:11”.

To run the provided image the command below can be executed. This starts Axon Server SE in a docker container with exposes the HTTP \(8024\) and GRPC \(8124\) ports to the host.
To run the provided image the command below can be executed. This starts Axon Server SE in a docker container with exposes the HTTP \(8024\) and GRPC \(8124\) ports to the host.

```bash
$ docker run -d --name -p 8024:8024 -p 8124:8124 axoniq/axonserver
Expand Down Expand Up @@ -57,11 +57,11 @@ logging.file.max-history=10
logging.file.max-size=10MB
```

#### Customization
### Customization

The directory locations for the volumes can be specified as per your requirements. The image also has a third directory "/config" which is not marked as a volume. This gives you the capability to have an "axonserver.properties" file which can be placed in this location to override the above mentioned settings as well as add new properties similar to a local install.

Assuming that you have a directory "_axonserverse**"**_ which will be the designated location for your volumes and configuration information.
Assuming that you have a directory "_axonserverse**"**_ which will be the designated location for your volumes and configuration information.

We will first create the sub-directories for the volumes/configuration. We will also add a couple of custom properties \(name/hostname\) to the axonserver.properties file which will be placed in the config sub-directory. As stated above, you can add additional properties to control the configuration.

Expand All @@ -81,13 +81,13 @@ docker run -d --rm --name axonserver -p 8024:8024 -p 8124:8124 -v `pwd`/axonserv

Now if you query the API \(utilizing the “curl” command depicted above\) it will show that it is running with name “axonserver” and hostname “localhost”. Also the data directory will contain the ControlDB file, PID file, and a copy of the log output. The “events” directory will have the event and snapshot data.

This completes a basic setup of the Axon Server SE Docker image with implementation of customizations.
This completes a basic setup of the Axon Server SE Docker image with implementation of customizations.

### Docker Compose
## Docker Compose

Running Axon Server SE in docker-compose helps address more complex requirements around distributed scenarios. The following file will help start Axon Server SE with “./data”, “./events”, and “./config” mounted as volumes and the config directory is actually Read-Only.
Running Axon Server SE in docker-compose helps address more complex requirements around distributed scenarios. The following file will help start Axon Server SE with “./data”, “./events”, and “./config” mounted as volumes and the config directory is actually Read-Only.

This again assumes that you have a directory "_axonserverse**"**_ which will be the designated location for your volumes and configuration information.
This again assumes that you have a directory "_axonserverse**"**_ which will be the designated location for your volumes and configuration information.

```text
version: '3.3'
Expand Down Expand Up @@ -148,7 +148,7 @@ axonserver_1 | /_/ \_\/_/\_\___/|_| |_|____/ \___|_| \_/ \___|_|
axonserver_1 | Standard Edition Powered by AxonIQ
```

### Kubernetes
## Kubernetes

An Axon Server SE instance has a clear and persistent identity, in that it saves identifying information about itself in the controlDB. Also, if it is used as an event store, the context’s events will be stored on disk as well, essentially _**Axon Server SE is a stateful application**_.

Expand Down Expand Up @@ -254,9 +254,9 @@ spec:
---
```

Important to note here is that this is a pretty basic descriptor in the sense that it does not have any settings for the amount of memory and/or cpu to reserve for Axon Server SE which you may want to do for long-running deployments.
Important to note here is that this is a pretty basic descriptor in the sense that it does not have any settings for the amount of memory and/or cpu to reserve for Axon Server SE which you may want to do for long-running deployments.

To deploy, you would need a Kubernetes cluster and access to the [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/) utility to help control these clusters. For a development Kubernetes cluster, it is recommended to use [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) or [Red Hat CodeReady Containers](https://github.com/code-ready/crc) which installs a Red Hat OpenShift Kubernetes cluster on your laptop . For production it is recommended to use a managed service like AWS [EKS](https://aws.amazon.com/eks/) / Google's [GKE](https://cloud.google.com/kubernetes-engine) or Azure's [AKS](https://azure.microsoft.com/en-us/services/kubernetes-service).
To deploy, you would need a Kubernetes cluster and access to the [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/) utility to help control these clusters. For a development Kubernetes cluster, it is recommended to use [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) or [Red Hat CodeReady Containers](https://github.com/code-ready/crc) which installs a Red Hat OpenShift Kubernetes cluster on your laptop . For production it is recommended to use a managed service like AWS [EKS](https://aws.amazon.com/eks/) / Google's [GKE](https://cloud.google.com/kubernetes-engine) or Azure's [AKS](https://azure.microsoft.com/en-us/services/kubernetes-service).

The first step would be to create a separate namespace for Axon Server SE.

Expand Down
2 changes: 1 addition & 1 deletion extensions/tracing.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ With this instrumentation, we can chain synchronous and asynchronous commands an
</dependency>
```

The first dependency is [Spring Boot starter for Axon Tracing extension](../getting-started/maven-dependencies.md#axon-tracing-spring-boot-starter), which is the quickest start in to an extension configuration.
The first dependency is [Spring Boot starter for Axon Tracing extension](https://github.com/domaincomponents/reference-guide/tree/375d9d62c18f30922cb3bc5be76351deeb9a64f0/getting-started/maven-dependencies.md#axon-tracing-spring-boot-starter), which is the quickest start in to an extension configuration.

The second dependency is [Jaeger](https://www.jaegertracing.io/) implementation for OpenTracing.

Expand Down
Loading

0 comments on commit 840c158

Please sign in to comment.