Introduction

The Dispatcher service is an API Gateway providing a way to route APIs. It is built based on the Spring Cloud Gateway and includes all its features (as describe in the Spring Cloud Gateway public documentation). It also provides path rewriting rules for Yambas and the ApiOmat cloud environment. See How It works to have a deeper understanding of how the Spring Cloud Gateway works.

Prerequisites

Following port should be available:

8000 (HTTP)

Installation of Consul is required!

Installation of AdoptOpenJDK is required when not using Docker!

System requirements

The following instance configurations are recommended.

Size	CPU	Memory	Disk	Typical Cloud Instance Types
All	2 core	1 GB RAM	500 MB	AWS: t2.medium
				Azure: Standard_ B1MS

Installation

USERNAME, PASSWORD, and TOKEN values are provided per customer from ApiOmat.

Debian/Ubuntu

Debian/Ubuntu

# Install the repo key
wget -O - https://repo-int.apiomat.com/yambas/rest/web/Key/LIVE/apiomat-archive-keyring.asc | sudo apt-key add -
# Add the repository
echo "deb https://<USERNAME>:<PASSWORD>@repo.apiomat.com/yambas/rest/web/Repo/LIVE/deb ./" | sudo tee /etc/apt/sources.list.d/apiomat.list
 
# Update APT and install
apt-get update
apt-get install -y aom-dispatcher
service dispatcher start

Centos/Oracle/RedHat

Centos/Oracle/RedHat

# Add the repository
echo "[apiomat]
name=ApiOmat
baseurl=https://<USERNAME>:<PASSWORD>@repo.apiomat.com/yambas/rest/web/Repo/LIVE/rpm
gpgcheck=0
enabled=1" > /etc/yum.repos.d/apiomat.repo
 
# Install
yum -y --nogpgcheck install aom-dispatcher
service dispatcher start

Suse

Suse

# Add the repository
zypper addrepo --no-gpgcheck https://repo.apiomat.com/yambas/rest/web/Repo/LIVE/suse?token=<TOKEN> "ApiOmat"
 
# Refresh zypper and install
zypper refresh
zypper --no-gpg-checks --non-interactive install aom-dispatcher
service dispatcher start

Docker Compose

Docker Compose

# Docker login
docker login -u <USERNAME> -p <PASSWORD>
 
# Store the following file and execute:
docker-compose -f dispatcher.yml up

dispatcher.yml:

version: '3'
services:
  consul:
    image: library/consul
    # bind port 8500 of container to localhost port 8500
    ports:
      - "8500:8500"
  dispatcher:
    image: apiomat/dispatcher:<VERSION>
    environment:
      SPRING_CLOUD_CONSUL_HOST: consul
      SPRING_CLOUD_CONSUL_PORT: 8500
    ports:
      - "8000:8000"
    depends_on:
      - consul

Kubernetes

Kubernetes

To obtain the latest manifest file, please contact the EASY ApiOmat support.

Helm

Helm

Docker login

#Docker login
kubectl create secret docker-registry regcred \
 --docker-server=https://index.docker.io/v1/ \
 --docker-username="<USERNAME>" \
 --docker-password="<PASSWORD>" \
 --docker-email="<MAIL>"

We are using helm to deploy the yambas replicaset

helm init
helm repo update
helm repo add apiomat https://apinautengmbh.github.io/helm/
helm fetch apiomat/apiomat-dispatcher

extract the archive (.tgz) and find the values.yml. Adjust the parameters as required.

helm install apiomat/apiomat-dispatcher --name apiomat-dispatcher --values values.yaml

Windows

Windows

Download file: https://repo.apiomat.com/yambas/rest/web/Repo/LIVE/aom-dispatcher-<VERSION>.zip?token=<TOKEN> and unzip to installation folder
Ensure that the path to your installed jdk\bin is set to the system-environment variable 'Path' (java.exe needs to be accessible for windows' system user!)

Open administrative console and execute

Dispatcher-<VERSION>.exe install

Dispatcher-<VERSION>.exe start

to install as service and start afterwards.

For a removal of the service, execute

Dispatcher-<VERSION>.exe uninstall

Configuration

General service configuration possibilities are described at the configurations main page.

Key	Description	Example
dispatcher.security.route-matchers[]	List of path pattern that should be secured and for which authentication is required.	To secure all endpoint under /yambas - dispatcher.security.route-matchers[0]=/yambas/**
spring.security.enable-nocache	If set to "true", all responses will contain a "Cache-Control" header with "no-cache, no-store, max-age=0, no-revalidate" header. For cases, where a backend-service is not capable of handling it correctly, to prevent security issues, but will decrease performance), set to false by default. (available since dispatcher 1.8.0)	false
dispatcher.logging.request.enable	Enable request logging (since dispatcher 1.8.0)	true
dispatcher.logging.request.includes	The included request information within the log, may be "HEADERS" "PAYLOAD" "URI" "HTTP_METHOD". Values are separated by space. (since dispatcher 1.8.0)	HEADERS URI HTTP_METHOD
dispatcher.logging.response.enable	Enable response logging (since dispatcher 1.8.0)	true
dispatcher.logging.response.includes	The included response information within the log, may be "HEADERS" "PAYLOAD" "EXECUTION_TIME" "STATUS". Values are separated by space. (since dispatcher 1.8.0)	HEADERS EXECUTION_TIME STATUS
dispatcher.logging.ignorePatterns	The patterns to not include into the log (since dispatcher 1.8.0)	"/example/.*"

For more route configuration please refer to the Spring Cloud Gateway configuration documentation.

Logging

Linux

Linux

Logging is done to a separate logfile:

tail -f /var/log/apiomat/dispatcher/dispatcher.log

Docker

Docker

Please replace <DISPATCHER_CONTAINER_ID> with your running container ID. You can list your running container using 'docker container list' command.

docker logs -f <DISPATCHER_CONTAINER_ID>

Kubernetes

Kubernetes

Please replace <DISPATCHER_CONTAINER_ID> with your running container ID. You can list your running container using 'kubectl get pods' command.

kubectl logs -f <DISPATCHER_CONTAINER_ID>

Windows

Windows

All logs are written to Event manager.

Next steps

Install and start your services and the Consul discovery client.
Check that every started service is registered and available through the Consul discovery client (default Consul UI is available on localhost at http://localhost:8500/ui/dc1/services).
Once the Dispatcher service is started you can now query and access your service endpoints through a single node (e.g. to access Yambas REST endpoint through the Dispatcher - http://localhost:8000/yambas/rest).

For the usage documentation see Dispatcher.

For a deeper use of the Spring Cloud Gateway features please refer to the following documentation links :

[Dispatcher] Installation