Skip to content

Latest commit

 

History

History
212 lines (137 loc) · 9.46 KB

README.md

File metadata and controls

212 lines (137 loc) · 9.46 KB
Raw

First Steps with AxonServer on Kubernetes

This example was made using Docker Desktop on MacOs. Its likely that there are some adaptions needed to run it on Windows and/or minikube. The example is based on running-axon-server k8s-se (GitHub).

This is meant to provide basic knowledge to get started. It isn't by no means a manual for a production setup. Also see DISCLAIMER.md.

A reference list of commands and scripts can be found in COMMANDS.md.

Tools

Enable Kubernetes Metrics

To get more insights on how resources are distributed in Kubernetes, Enable Kubernetes Metrics Server on Docker Desktop describes how metrics-server can be installed. Here is a short summary of the steps and commands:

  • If the following command results in an error message like Metrics API not available, the metrics server is not installed:

    kubectl top node

  • Download components.yaml from the latest release of kubernetes-sigs/metrics-server:

    curl -L https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml > components.yaml

  • Install the metrics serer:

    kubectl apply -f components.yaml

  • If there is a certificate error it may help to add --kubelet-insecure-tls to the args of the metrics-server template definition. It shouldn't be needed for newer versions though.

Overview with Kubernetes Dashboard

A web user interface like the Kubernetes Dashboard can help to get more insights in what is going on within Kubernetes, especially for troubleshooting. Follow the instruction in Deploy and Access the Kubernetes Dashboard or on github.com/kubernetes/dashboard to install it. Here is a summary:

  • Get latest release version number:

    curl --silent "https://api.github.com/repos/kubernetes/dashboard/releases/latest" | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/'

  • Install latest release (here v2.7.0):

    kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml

  • Create admin user:

    kubectl apply -f kubernetes-dashboard/dashboard-admin-user.yaml

  • Create login token:

    kubectl -n kubernetes-dashboard create token admin-user

  • Enable Access (in separate terminal):

    kubectl proxy

  • Open the Dashboard:
    Use the following URL and login using the previously generated token: http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy

  • Change the namespace in the header of the web user interface to "All namespaces" to see them all.

  • If the session has expired, stop the kubectl proxy with Control + C and repeat the last 3 steps.

Deploy Axon Server

Execute the scripts below to deploy Axon Server.

Please look through the scripts e.g. with cat *.sh before you you execute them. Don't execute them if something seems suspicious for you.

  • ./cleanup.sh deletes generated files (properties, yml, token, ssl)
  • ./deploy-secrets.sh creates the namespace running-se or the one given with command option -n and deploys axonserver.properties, token and certificate in Kubernetes
  • ./deploy-axonserver.sh deploys Axon Server as a StatefulSet into the namespace running-se or the one given with command option -n in Kubernetes

Current Status of Axon Server

Use this command to get the current status of all elements that are installed within the Kubernetes Namespace. This might take a while. Repeat the command until you see 1/1 Running. See Troubleshooting if status is 0/1 Pending.

kubectl get all --namespace running-se

Create Axon Server Admin User

Axon Server access control needs to be deactivated to create the first admin user using axonserver-cli.jar. This is only meant to be used for local or test environments.

  • Download https://download.axoniq.io/axonserver/AxonServer.zip directly or from AxonIQ Downloads.

  • Extract the ZIP and copy axonserver-cli.jar into your working directory or add it to your path.

  • Get the currently deployed axonserver.properties:

    kubectl get configmaps axonserver-properties --namespace running-se -o yaml > axonserver-properties-disabled-accesscontrol.yml

  • Edit the file axonserver-properties-disabled-accesscontrol.yml and change axoniq.axonserver.accesscontrol.enabled to false.

  • Apply the changed property file to Kubernetes:

    kubectl apply -f axonserver-properties-disabled-accesscontrol.yml --namespace running-se

  • Restart Axon Server:

    kubectl rollout restart statefulset axonserver --namespace running-se

  • Wait until Axon Server is up and running again:

    kubectl get all --namespace running-se

  • Create the admin user: In this example we choose user admin with password admin. Use secure values for test- and production environments.

    ./axonserver-cli.jar register-user -u admin -p admin -r ADMIN -s -i

  • Reenable access control again:

    kubectl get configmaps axonserver-properties --namespace running-se -o yaml > axonserver-properties-enabled-accesscontrol.yml

    Edit the file axonserver-properties-enabled-accesscontrol.yml and set axoniq.axonserver.accesscontrol.enabled back to true. Then apply those changes with these commands:

    kubectl apply -f axonserver-properties-enabled-accesscontrol.yml --namespace running-se
kubectl rollout restart statefulset axonserver --namespace running-se
kubectl get all --namespace running-se

Open Web User Interface

Open the web user interface: https://localhost:8024
You can log in using the credentials from the former step. There might be warnings about the certificate. For the local installation they can be ignored.

Quick Test

Please look through the script e.g. with cat *.sh before you you execute it. Don't execute it if something seems suspicious for you.

Run the script ./run-quicktest.sh (and optional -n <namespace-name>) to create an example event to try out Axon Server's Event Store. After execution you should see the event in the web user interface under "Search" by pressing the search button without a filter.

Troubleshooting

Here are some questions and troubles i had when i tried to reproduce the steps of the Webinar Running Axon Server in 2020 on YouTube.

Where is "axonserver.yml" ?

Since this example is a bit more advanced, the YAML files are generated by the scripts based on the given templates. These are basic templates without using Helm. So axonserver.yml will be generated within ./deploy-axonserver.sh and already applied to Kubernetes. You can of course comment the last line out of the script and apply the file yourself with the following command if you want.

kubectl apply -f axonserver.yml --namespace running-se

Script not executable

The scripts should already be executable. So the following command is only necessary in case they are not.

chmod +x *.sh

Status pending

If the following command shows, that the pod of Axon Server is in status pending, open the pod in the Kubernetes Dashboard and read through the events. If it is because of insufficient resources, open the Docker Desktop, increase the resources and restart.

kubectl get all --namespace running-se

Where can i find "axonserver-cli.jar"?

References