Gateways at sites

A gateway created with --served-by site runs at your site, as its own gateway instance beside the agent. It accepts calls only on the entrances the site’s enrolment gives it, such as an address on the plant’s network, and the site opens nothing towards the hub or the internet. Machines on the same network call the APIs there directly, and the calls never leave the site.

Create the gateway#

$ weikio gateway create factory --env production --served-by site --hostname api.factory.corp.example --networks 10.20.0.0/16 --entrance lan

Enrol the site to serve it#

Each site that has the label gateway=factory runs an instance of the gateway. Enrol the site with the gateway in what it runs and the address its entrance listens on:

$ weikio agent enrol factory-1 --host linux-compose --capabilities os=linux,site=factory,environment=production,gateway=factory --projects finance --runs integrations,gateway --entrance lan=10.20.0.5:443 --out ./factory-1/

The entrance listens with HTTPS on that address alone, and it is the only port the site’s stack publishes. TLS ends in the gateway itself. The caller’s address is the address the connection comes from, and the gateway checks the client certificate on that same connection. Entrances change by issuing the site a new bundle with weikio agent credentials factory-1 --entrance lan=....

Where the upstream is#

The integrations of the same host listen on the agent’s address, which the site’s stack names integrations, at the port the integration uses: Camel’s 8080 unless camel.server.port sets another. An API at the site calls such an integration at http://integrations:<port>, written as a value per environment like every upstream address:

clusters:
  - ClusterId: orders
    Destinations:
      orders: { Address: "{{orders-url}}" }    # orders-url = http://integrations:8080 in production

That address reaches only the integrations of the host the call arrives at, so the integration must run on every host that serves the gateway. Give it the same requirement, such as site: factory. Another system on the site’s network is called by its own address, which the site’s operator opens as for any other client.

Certificates#

Each gateway instance makes its own key on its host and asks the hub for a certificate over the site’s link, so the key never leaves the host. The hub signs a name no public authority signs, such as one under .internal, with the platform’s own authority, orders a public name from Let’s Encrypt or your own ACME server, or lets the instance order from an ACME server that only the site reaches. Machines that call a name the platform’s authority signs trust it once, from weikio platform authority get.

Site certificates renew from half their lifetime, so a site whose link is cut keeps a valid certificate for at least the other half.

While the link is cut#

The gateway keeps serving every route table it has, and changes at the hub reach it when the link returns. It serves a table only while the hub confirmed it within the last 24 hours, so a site that stays cut off longer stops serving and says how old its tables are. Until the link returns, a subscription’s limit is counted in each instance instead of once across all of them.

Partners through the hub#

A partner on the internet reaches an API that only the site reaches through a hub gateway that relays to the site’s gateway, with no port opened at the site. Name the hub gateway in the site gateway’s --relay-from, deploy the version on both, and relay one to the other:

$ weikio gateway set factory --relay-from partner
$ weikio api deploy finance/orders@v1 --env production --gateways partner,factory
$ weikio api set-gateways finance/orders@v1 --env production --via partner=factory

The hub admits the caller by its subscription and the gateway’s rules, and the site calls the upstream. A relayed call crosses the site’s link as one message, so its body and headers together can be at most 1 MiB.

What a site gateway doesn’t serve#

Webhook versions publish into the hub’s event stream, so they’re served by hub gateways only. To take calls at a site, put a proxy version in front of the integration’s own HTTP endpoint.

weikio describe agent factory-1 shows the site’s entrances, the gateways it serves and what its instance last reported, and weikio get apim-instances lists every gateway instance at the hub and at the sites. Gateways at sites run on Linux hosts.