nginx-asg-sync

NGINX Plus Integration with Cloud Autoscaling -- nginx-asg-sync

nginx-asg-sync allows NGINX Plus to discover instances (virtual machines) of a scaling group of a cloud provider. The following providers are supported:

• AWS Auto Scaling groups
• Azure Virtual Machine Scale Sets

When the number of instances changes, nginx-asg-sync adds the new instances to the NGINX Plus configuration and removes the terminated ones.

How It Works

nginx-asg-sync is an agent process that runs on the same instance as NGINX Plus. It polls for changes to the backend instance groups via the Cloud Provider API.

When it sees that a scaling event has happened, it adds or removes the corresponding backend instances from the NGINX Plus configuration via the NGINX Plus API.

Note: nginx-asg-sync does not scale cloud scaling groups, it only gets the IP addresses of the instances in the groups.

In the example below (AWS), NGINX Plus is configured to load balance among the instances of two AWS Auto Scaling groups -- Backend One and Backend Two. nginx-asg-sync, running on the same instance as NGINX Plus, ensures that whenever you scale the Auto Scaling groups, the corresponding instances are added (or removed) from the NGINX Plus configuration.

Below you will find documentation on how to use nginx-asg-sync.

Documentation

Note: the documentation for the latest stable release is available via a link in the description of the release. See the releases page.

Contents:

• NGINX Plus Integration with Cloud Autoscaling -- nginx-asg-sync
  • How It Works
  • Documentation
  • Supported Operating Systems
  • Installation
    • NGINX Plus Configuration
    • Configuration for Cloud Providers
  • Usage
  • Troubleshooting
  • Building a Software Package
  • Support

Supported Operating Systems

We provide packages for the following operating systems:

• Ubuntu 16.04 and later, Debian 9/10
• CentOS/RHEL: 7, 8
• Amazon Linux: 1, 2

Support for other operating systems can be added.

Installation

1. Get a software package for your OS:
   • For a stable release, download a package from the releases page.
   • For the latest source code from the master branch, build a software package by following these instructions.
2. Install the package:
   • For Amazon Linux or CentOS/RHEL, run: $ sudo rpm -i <package-name>.rpm
   • For Ubuntu or Debian, run: $ sudo dpkg -i <package-name>.deb

NGINX Plus Configuration

As an example, we configure NGINX Plus to load balance two groups of instances -- backend-group-one and backend-group-two. NGINX Plus routes requests to the appropriate group based on the request URI:

• Requests for /backend-one go to Backend One group.
• Requests for /backend-two go to Backend Two group.

This example corresponds to the diagram at the top of this README.

upstream backend-one {
   zone backend-one 64k;
   state /var/lib/nginx/state/backend-one.conf;
}

upstream backend-two {
   zone backend-two 64k;
   state /var/lib/nginx/state/backend-two.conf;
}

server {
   listen 80;

   status_zone backend;

   location /backend-one {
       proxy_set_header Host $host;
       proxy_pass http://backend-one;
   }

   location @hc-backend-one {
       internal;
       proxy_connect_timeout 1s;
       proxy_read_timeout 1s;
       proxy_send_timeout 1s;

       proxy_pass http://backend-one;
       health_check interval=1s mandatory;
   }

   location /backend-two {
       proxy_set_header Host $host;
       proxy_pass http://backend-two;
   }

   location @hc-backend-two {
       internal;
       proxy_connect_timeout 1s;
       proxy_read_timeout 1s;
       proxy_send_timeout 1s;

       proxy_pass http://backend-two;
       health_check interval=1s mandatory;
   }
}

server {
    listen 8080;

    location /api {
        api write=on;
    }

    location /dashboard.html {
      root /usr/share/nginx/html;
    }
}

• We declare two upstream groups – backend-one and backend-two, which correspond to our instance groups. However, we do not add any servers to the upstream groups, because the servers will be added by nginx-aws-sync. The state directive names the file where the dynamically configurable list of servers is stored, enabling it to persist across restarts of NGINX Plus.
• We define a virtual server that listens on port 80. NGINX Plus passes requests for /backend-one to the instances of the Backend One group, and requests for /backend-two to the instances of the Backend Two group.
• We define a second virtual server listening on port 8080 and configure the NGINX Plus API on it, which is required by nginx-asg-sync:
  • The API is available at 127.0.0.1:8080/api

Because cloud provider APIs return the instances IP addresses before the instances are ready and/or provisioned, we recommend setting up mandatory active healthchecks for all upstream groups - @hc-backend-one and @hc-backend-two. This way, NGINX Plus won't pass any request to an instance that is still being provisioned or has been deleted recently.

Small timeouts ensure that a health check will fail fast if the backend instance is not healthy. Also, the mandatory parameter ensures NGINX Plus won't consider a newly added instance healthy until a health check passes.

When using AWS it's possible to filter out the instances that are not in a InService state of the Lifecycle with the parameter in_service set to true. This will ensure that the IP won't be added until the instance is ready to accept requests. This also works when an instance is being terminated: the asg-sync will remove the IP of an instance that went from the InService state to one of the terminating states. Note: because the asg-sync works on a polling-based model, there will be a delay between the instance going to a terminating state and the asg-sync removing its IP from NGINX Plus. To guarantee that NGINX Plus doesn't send any requests to a terminated instance, make sure the instance goes to the Terminating:Wait state for a period greater than the interval sync_interval_in_seconds.

Configuration for Cloud Providers

See the example for your cloud provider: AWS, Azure.

Usage

nginx-asg-sync runs as a system service and supports the start/stop/restart commands.

For Amazon Linux 1, run: $ sudo start|stop|restart nginx-asg-sync

For Ubuntu >= 16.04, Debian 9/10, CentOS7/RHEL7, CentOS8/RHEL8 and Amazon Linux 2, run: $ sudo service nginx-asg-sync start|stop|restart

Troubleshooting

If nginx-asg-sync doesn’t work as expected, check its log file available at /var/log/nginx-aws-sync/nginx-aws-sync.log.

Building a Software Package

You can compile nginx-asg-sync and build a software package using the provided Makefile. Before you start building a package, make sure that the following software is installed on your system:

• make
• Docker
• Go (optional, to build the binary locally)

To build a software package, run: $ make <os> where <os> is the target OS. The following values are allowed:

• amazon for Amazon Linux 1
• amazon2 for Amazon Linux 2
• centos7 for CentOS7/RHEL7
• centos8 for CentOS8/RHEL8
• debian for Ubuntu >= 16.04 and Debian 9/10

by default the nginx-asg-sync binary will be built locally, to build it inside a Docker container add the TARGET parameter to make, for example:

$ make debian TARGET=container

If you run make without any arguments, it will build software packages for all supported OSes.

Support

Support from the NGINX Professional Services Team is available when using nginx-asg-sync.