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

Defines specific upstreams for a service. Each service instance is added to the upstreams record in the NGINX configuration.

Visit Nginx docs to learn more about the upstream directive.

Example:

nginx:
  upstreams:
    upstream-foobar: 1234

Service foobar has published API on port tcp/1234. The additional upstream record is defined and named upstream-foobar.

Assuming three instances of foobar service on three nodes, the resulting upstream configuration is:

upstream upstream-foobar {
  keepalive 32;
  server server1:3081;
  server server2:3081;
  server server3:3081;
}
Advanced usage of upstreams

You can define an upstream as a list to add more configuration options.

For example, SeaCat Auth, an authorization server, requires that requests from one user during a single session are sent to the same instance of the service. NGINX can ensure this using the ip_hash balancing method.

Here is the descriptor section defining upstreams for SeaCat Auth: 

nginx:
  upstreams:
  upstream-seacat-auth-public:
    - port 3081
    - ip_hash
  upstream-seacat-auth-private:
    - port 8900
    - ip_hash

Considering node1 and node2 are hostnames of the nodes in the cluster, the resulting NGINX configuration for the upstreams will be: 

upstream upstream-seacat-auth-public {
  keepalive 32;
  server node1:3081;
  server node2:3081;
  ip_hash;
}

upstream upstream-seacat-auth-private {
  keepalive 32;
  server node1:8900;
  server node2:8900;
  ip_hash;
}

In the list, you can specify any additional configuration you want to add to the upstream configuration. The port directive is not used by NGINX directly but is processed by Maestro. The server configuration is added for each instance of the service (in this case, SeaCat Auth) present in the cluster.

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. It overrides generated configuration.

In the example, extra section in the model.yaml adds location "/my-special-location" to https server.

define:
  type: rc/model

...

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

You can set also server and upstream configuration. port option in the upsstream configuration is not supported in model overrides.

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: