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

# 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

# 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

# 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 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

# Docker login
kubectl create secret docker-registry regcred \
 --docker-server=https://index.docker.io/v1/ \
 --docker-username="<USERNAME>" \
 --docker-password="<PASSWORD>" \
 --docker-email="<MAIL>"
 
# Store the following file and execute
kubectl apply -f dispatcher.yml

dispatcher.yml

# Source: apiomat-dispatcher/templates/service.yaml
kind: Service
apiVersion: v1
metadata:
  name: release-name-apiomat-dispatcher
  labels:
    app: apiomat-dispatcher
    chart: apiomat-dispatcher-1.1.0
    release: "release-name"
    heritage: "Tiller"
spec:
  ports:
    - name: http
      port: 8000
      protocol: TCP
  type: NodePort
  selector:
    app: apiomat-dispatcher
    release: release-name
---
# Source: apiomat-dispatcher/templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: apiomat-dispatcher
    chart: apiomat-dispatcher-1.1.0
    heritage: Tiller
    release: release-name
  name: release-name-apiomat-dispatcher
spec:
  replicas: 1
  selector:
    matchLabels:
      app: apiomat-dispatcher
      chart: apiomat-dispatcher-1.1.0
      release: release-name
  template:
    metadata:
      labels:
        app: apiomat-dispatcher
        chart: apiomat-dispatcher-1.1.0
        release: release-name
    spec:
      imagePullSecrets:
        - name: <regcred>
      containers:
        - name: apiomat-dispatcher
          image: docker.io/apiomat/dispatcher:1.1.0
          command:
            - --spring.cloud.consul.enabled=false
          ports:
            - containerPort: 8000
              name: ms-port
          resources:
            limits:
              memory: 1Gi
            requests:
              memory: 1Gi
 
          livenessProbe:
            httpGet:
              path: /actuator/health
              port: 8000
            initialDelaySeconds: 30
            periodSeconds: 10
            timeoutSeconds: 5
            successThreshold: 1
            failureThreshold: 6
          readinessProbe:
            httpGet:
              path: /actuator/health
              port: 8000
            initialDelaySeconds: 5
            periodSeconds: 10
            timeoutSeconds: 5
            successThreshold: 1
            failureThreshold: 6
          imagePullPolicy: Always
          securityContext:
            capabilities: {}
            privileged: false
 
---
# Source: apiomat-dispatcher/templates/ingress.yaml
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: release-name-apiomat-dispatcher
  labels:
    app: apiomat-dispatcher
    chart: apiomat-dispatcher-1.1.0
    release: release-name
    heritage: Tiller
spec:
  rules:
    - host: "example.domain"
      http:
        paths:
          - path: /
            backend:
              serviceName: release-name-apiomat-dispatcher
              servicePort: ms-port

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

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.

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

Logging

Linux

Logging is done to a separate logfile:

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

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

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

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