Distributed Service Execution

The gateway architecture allows for a highly available, scalable deployment to ensure your services always have enough resources to execute as well as increasing the likelihood they can be run in the event of an outage.

Cluster Architecture

Gateway supports an architecture model where the management of gateway resources and handling of incoming requests is handled by one or more gateway core servers and the actual service execution is delegated to special gateway runner nodes. A group of gateway core/runner nodes that share the same resources (services, decorators, etc) is known as a cluster.

Simple Gateway Cluster

A simple gateway cluster architecture with a single core server and three runner nodes is shown below. To utilize gateway runners, an etcd database must be configured so that database resources can be shared within the cluster. All runner nodes must be able to connect to the etcd database and to the core server that lives in the control plane.

Similar to a regular gateway server deployment, a gateway client will send all requests to the core gateway server.

Use the following sections to configure the etcd database, core server, runners, and the gateway client.

Etcd Database

An etcd database is necessary to run gateway in a distributed core/runner architecture. As a database, etcd stores data in a multi-version persistent key-value store.

• Information on setting up, running and using etcd is available on its website → etcd

• Information on configuring etcd server/etc cluster can be found here → Etcd Database

Core Server

Use these instructions for setting up the core server:

1. Configure the gateway server to connect with the etcd server/etcd cluster (different from a gateway cluster):

   1. Set the configuration variable GATEWAY_STORE_ETCD_HOSTS to the hostname:port of the etcd server.
   2. If running an etcd cluster, set it to a space separated list of hosts exposed in the etcd cluster, e.g. hostname1:port hostname2:port.
   3. Verify that all of the GATEWAY_STORE_ETCD_* configuration variables defined in Store Variables are correctly set for your particular cluster.
   4. If you need to migrate data between a local database to an etcd database, reference the iagctl db migrate command.

2. Set the cluster ID to your desired value via the configuration variable GATEWAY_APPLICATION_CLUSTER_ID. If you switch your cluster ID, all gateway resources will now be pulled from/saved to a different namespace within the database. This design allows for architectures where multiple gateway clusters share the same etcd database.

3. Set the configuration variable GATEWAY_APPLICATION_MODE to server. For more on Application Mode see → Modes of Operation.

4. Switch the configuration variable GATEWAY_SERVER_DISTRIBUTED_EXECUTION to true. This will set the gateway server to always round-robin between gateway runners that are also registered to the same etcd database and share the same GATEWAY_APPLICATION_CLUSTER_ID.

5. Verify all remaining GATEWAY_SERVER_* configuration variables are correctly set to allow the gateway client to send requests to the gateway server.

6. Run iagctl server. The gateway server will listen for requests from the configured gateway client.

Runners

Use these instructions for setting up all gateway runners:

1. Set all of the GATEWAY_STORE_ETCD_* configuration variables to the same values as the gateway core server.
2. Set GATEWAY_APPLICATION_CLUSTER_ID to the same value as the gateway core server.
3. Set GATEWAY_APPLICATION_MODE to runner.
4. Set GATEWAY_RUNNER_* configuration variables to the appropriate values to ensure the runner nodes can properly communicate with the core server.
5. Run iagctl runner and look for an INFO level log that says registered runner with etcd database.

Gateway Client

Use these instructions for setting up gateway clients to send requests to gateway servers:

1. Set the GATEWAY_CLIENT_HOST configuration variable to the hostname of the gateway server.
2. Verify all other GATEWAY_CLIENT_* configuration variables are correctly configured to connect to the gateway server.
3. Login to the gateway server by following the login guide.
4. Run iagctl get runners on the client to see a list of all runners that are currently online and registered to the cluster.
5. Run requests as you normally would against the server. Observe that when services are executed, corresponding logs are present on the actual runner node.

Multiple Cluster Architecture

If desired, multiple clusters can be deployed. Each cluster will need its own unique GATEWAY_APPLICATION_CLUSTER_ID.

Multiple clusters can be useful in scenarios where the runners need to be close to the actual infrastructure they are sending requests to, especially if firewalls are a factor. A gateway client can send requests to the different clusters to execute the different services that pertain to each cluster.

The diagram below shows a scenario where each cluster has its own etcd database. This setup is entirely optional as multiple clusters can share the same etcd database, if desired. It is should be noted, however, that clusters that share the same etcd database will not share actual database resources (services, decorators, etc) as resources are given their own namespace in the database per cluster ID.