Repository files navigation

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

• AWSAuto Scaling groups
• AzureVirtual Machine Scale Sets

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

• How It Works
• Documentation
• Supported Operating Systems and Architectures
• Installation
  • Manual Installation
  • Snap Installation
  • Homebrew Installation
• NGINX Plus Configuration
• Configuration for Cloud Providers
• Usage
• Troubleshooting
• Building a Software Package
• Contacts
• Contributing
• Support

nginx-asg-sync is an agent process that runs on the same instance as NGINX Plus. It polls for changes to the backendinstance 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 NGINXPlus 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 youscale 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.

The documentation forthe latest stable release is available via a link in the description of the release. See thereleases page.

We provide.rpm and.deb packages for386,amd64,arm64,ppc64le ands390x.

Support for other operating systems or architectures can be added.

1. Get a software package for your OS:
   • For a stable release, download a package from thereleases page.
   • For the latest source code from the main branch, build a software package by followingtheseinstructions.
2. Install the package:
   • For CentOS/RHEL based OSs, run:sudo rpm -i <package-name>.rpm
   • For Debian based OSs, run:sudo dpkg -i <package-name>.deb

You can install the NGINX Plus Integration with Cloud Autoscaling from theSnap Store.

sudo snap install nginx-asg-sync

You can add the NGINX homebrew tap with

brew tap nginx/tap

and then install the formula with

brew install nginx-asg-sync

As an example, we configure NGINX Plus to load balance two groups of instances -- backend-group-one andbackend-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 tothe diagram at the top of this README.

upstreambackend-one{zone backend-one64k;state /var/lib/nginx/state/backend-one.conf;}upstreambackend-two{zone backend-two64k;state /var/lib/nginx/state/backend-two.conf;}server {listen80;status_zone backend;location/backend-one{proxy_set_header Host$host;proxy_pass http://backend-one;   }location@hc-backend-one{internal;proxy_connect_timeout1s;proxy_read_timeout1s;proxy_send_timeout1s;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_timeout1s;proxy_read_timeout1s;proxy_send_timeout1s;proxy_pass http://backend-two;health_check interval=1s mandatory;   }}server {listen8080;location/api{api write=on;    }location/dashboard.html{root /usr/share/nginx/html;    }}

• We declare two upstream groups –backend-one andbackend-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. Thestate directive names the file where the dynamically configurable list of servers is stored, enabling it to persistacross restarts of NGINX Plus.
• We define a virtual server that listens on port 80. NGINX Plus passes requests for/backend-one to the instancesof 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 bynginx-asg-sync:
  • The API is available at127.0.0.1:8080/api

Because cloud provider APIs return the instances IP addresses before the instances are ready and/or provisioned, werecommend setting up mandatory activehealthchecks 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 stillbeing 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 mandatoryparameter 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 aInService state of theLifecycle with the parameterin_service set totrue. 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 theInService 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 aterminating state and the asg-sync removing its IP from NGINX Plus. To guarantee that NGINX Plus doesn't send anyrequests to a terminated instance, make sure the instance goes to theTerminating:Wait state for a period greaterthan the intervalsync_interval.

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

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

sudo service nginx-asg-sync start|stop|restart

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

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

• make
• Docker
• Go (optional, to build the binary locally)
• GoReleaser (optional, to build the binaries and packages locally)

To build the binary locally, and only for the host architecture, runmake nginx-asg-sync.

To build the binaries and packages for all the supported architectures, runmake build-goreleaser.

To build the binaries and packages for all the supported architectures in Docker, runmake build-goreleaser-docker.

Note

When building with GoReleaser the resulting binaries and packages are located in thedist folder.

We’d like to hear your feedback! If you have any suggestions or experience issues with the NGINX Plus Integration withCloud Autoscaling, please create an issue or send a pull request on GitHub. You can contact us directly viaintegrations@nginx.com or on theNGINX Community Slack.

If you'd like to contribute to the project, please read ourContributing guide.

Support from theNGINX Professional Services Team is available when usingnginx-asg-sync.