Skip to content

NGINX in ASAB Maestro

NGINX technology provides:

  • Application gateway capabilities
  • Load balancing
  • Service discovery
  • Authorization for other services in the cluster

Servers

ASAB Maestro organizes NGINX configuration into following structure:

  • HTTP server: http, see the config
  • HTTPS server: https, see the config
  • Internal HTTP server on a port tcp/8890: internal, see the config
  • Upstreams

NGINX configuration in descriptors

nginx section of a descriptor provides information about how the respective service expects the NGINX to be configured. It means that it specifies proxy forwarding rules that expose the microservice API.

The example of a descriptor /Site/.../Descriptors/foobar.yaml:

define:
  type: rc/descriptor

...  

nginx:

  api:
    port: 5678

  upstreams:
    upstream-foobar-extra: 1234

  https:
    location = /_introspect:
      - internal
      - proxy_method POST
      - proxy_pass http://{{UPSTREAM}}/introspect
      - proxy_ignore_headers Cache-Control Expires Set-Cookie

    location /subpath/api/foobar:
      - rewrite ^/subpath/api/(.*) /$1 break
      - proxy_pass http://upstream-foobar-extra

    server:
      - ssl_client_certificate shared/custom-certificate.pem
      - ssl_verify_client optional

NGINX configuration to YAML conversion

NGINX configuration in ASAB Maestro is translated into YAML, so it can be included in the model or descriptors.

Following NGINX configuration snipplet:

location /api/myapp {
  rewrite ^/api/myapp/(.*) /myapp/$1 break;
  proxy_pass http://my-server:8080;
}

becomes in ASAB Maestro YAML files:

location /api/myapp:
  - rewrite ^/api/myapp/(.*) /myapp/$1 break
  - proxy_pass http://my-server:8080

Similarly, you can add configuration to server block:

    server:
      - ssl_client_certificate shared/lmio-receiver/client-ca-cert.pem
      - ssl_verify_client optional

Section api

api section allows quick specification of the "main" API of the service. The key port specifies TCP port on which the API is exposed by the service.

This entry will generate respective location and upstream entries.

Full automation

The api section can be easily the only section in the nginx part of the service descriptor.

Section upstream

Specific upstream of a service. Every instance of a service will be added to the upstreams record of the NGINX configuration.

upstream refers to all available instances of a service.

nginx:
  upstreams:
    upstream-foobar-extra: 1234

Service foobar defines additional API "extra" that is available on the port tcp/1234. It becomes available as an upstream with the name upstream-foobar-extra and can be used as http://upstream-foobar-extra in the proxy_pass commands in locations.

Resulting upstream configuration, assuming three instances of foobar service are located on three nodes of the cluster:

upstream upstream-foobar-extra {
    keepalive 32;
    server server1:3081;
    server server2:3081;
    server server3:3081;
}

Server configuration

Other possibilities are implemented for each server separately (http, https, internal).

Additional locations can be specified for the server.

Section location

Typically, a proxy configuration of the particular component or the location of the statically served content.

Each additional location is added to the nginx configuration once per service, unless INSTANCE_ID parameter is used in the header of the location. Then, the location is introduced for each instance.

Section server

Server-block configuration.

Model-level NGINX configuration

You can specify custom NGINX configuration on the model-level like so:

define:
  type: rc/model

...

nginx:
  https:
    location /my-special-location:
      - gzip_static on
      - alias /webroot/lmio-webui/dist

This adds location "/my-special-location" to https server.

Web applications distribution

NGINX technology serves web applications. webapp-dist sherpa downloads and installs web applications defined in the model. Web applications are deployed (if needed) everytime the model is applied (i.e. "up" command is issued).

Example of model.yaml:

define:
  type: rc/model

...

webapps:
  /: My Web application
  /auth: SeaCat Auth WebUI
  /influxdb: InfluxDB UI

...

The section webapps in the model prescribes deployment of three web applications:

  1. "My Web application" will be deployed to / location of the HTTPS server
  2. "SeaCat Auth WebUI" will be deployed to /auth location of the HTTPS server
  3. "InfluxDB UI" will be deployed to /influxdb location of the HTTPS server

Supported web application types: