-
Notifications
You must be signed in to change notification settings - Fork 25
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
0 parents
commit 37c6c34
Showing
165 changed files
with
100,201 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
/build | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
/* | ||
* Copyright (C) 2017 Nginx, Inc. | ||
* All rights reserved. | ||
* | ||
* Redistribution and use in source and binary forms, with or without | ||
* modification, are permitted provided that the following conditions | ||
* are met: | ||
* 1. Redistributions of source code must retain the above copyright | ||
* notice, this list of conditions and the following disclaimer. | ||
* 2. Redistributions in binary form must reproduce the above copyright | ||
* notice, this list of conditions and the following disclaimer in the | ||
* documentation and/or other materials provided with the distribution. | ||
* | ||
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | ||
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | ||
* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | ||
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | ||
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | ||
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||
* SUCH DAMAGE. | ||
*/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,31 @@ | ||
GO_DOCKER_RUN = docker run --rm -v $(shell pwd)/cmd/sync:/go/src/github.com/nginxinc/nginx-asg-sync/cmd/sync -v $(shell pwd)/build:/build -w /go/src/github.com/nginxinc/nginx-asg-sync/cmd/sync | ||
GOLANG_CONTAINER = golang:1.8 | ||
|
||
all: amazon centos7 ubuntu-trusty ubuntu-xenial | ||
|
||
test: | ||
$(GO_DOCKER_RUN) $(GOLANG_CONTAINER) go test | ||
|
||
compile: test | ||
$(GO_DOCKER_RUN) $(GOLANG_CONTAINER) go build -o /build/nginx-asg-sync | ||
|
||
amazon: compile | ||
make -C os-packages/builders/amazon/ | ||
docker run --rm -v $(shell pwd)/os-packages/rpm:/rpm -v $(shell pwd)/build:/build amazon-builder | ||
|
||
centos7: compile | ||
make -C os-packages/builders/centos7/ | ||
docker run --rm -v $(shell pwd)/os-packages/rpm:/rpm -v $(shell pwd)/build:/build centos7-builder | ||
|
||
ubuntu-xenial: compile | ||
make -C os-packages/builders/ubuntu-xenial/ | ||
docker run --rm -v $(shell pwd)/os-packages/debian:/debian -v $(shell pwd)/build:/build ubuntu-xenial-builder | ||
|
||
ubuntu-trusty: compile | ||
make -C os-packages/builders/ubuntu-trusty/ | ||
docker run --rm -v $(shell pwd)/os-packages/debian:/debian -v $(shell pwd)/build:/build ubuntu-trusty-builder | ||
|
||
clean: | ||
-rm -r build | ||
|
||
.PHONY: test |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,173 @@ | ||
# NGINX Plus Integration with AWS Auto Scaling groups -- nginx-asg-sync | ||
|
||
**nginx-asg-sync** allows [NGINX Plus](https://www.nginx.com/products/) to support scaling when load balancing [AWS Auto Scaling groups](http://docs.aws.amazon.com/autoscaling/latest/userguide/WhatIsAutoScaling.html): when the number of instances in an Auto Scaling group changes, nginx-asg-sync adds the new instances to the NGINX Plus configuration and removes the terminated ones. | ||
|
||
More details on this solution are available in the blog post [Load Balancing AWS Auto Scaling Groups with NGINX Plus](https://www.nginx.com/blog/load-balancing-aws-auto-scaling-groups-nginx-plus/). | ||
|
||
Below you will find instructions on how to use nginx-asg-sync. | ||
|
||
## Contents | ||
|
||
1. [Supported Operating Systems](#supported-operating-systems) | ||
1. [Setting up Access to the AWS API](#setting-up-access-to-the-aws-api) | ||
1. [Installation](#installation) | ||
1. [Configuration](#configuration) | ||
1. [Usage](#usage) | ||
1. [Troubleshooting](#troubleshooting) | ||
1. [Building a Software Package](#building-a-software-package) | ||
1. [Support](#support) | ||
|
||
## Supported Operating Systems | ||
|
||
We provide packages for the following operating systems: | ||
|
||
* Ubuntu: 14.04 (Trusty), 16.04 (Xenial) | ||
* CentOS/RHEL: 7 | ||
* Amazon Linux | ||
|
||
Support for other operating systems can be added. | ||
|
||
## Setting up Access to the AWS API | ||
|
||
nginx-asg-sync uses the AWS API to get the list of IP addresses of the instances of an Auto Scaling group. To access the AWS API, nginx-asg-sync must have credentials. To provide credentials to nginx-asg-sync: | ||
|
||
1. [Create an IAM role](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) and attach the predefined `AmazonEC2ReadOnlyAccess` policy to it. This policy allows read-only access to EC2 APIs. | ||
1. When you launch the NGINX Plus instance, add this IAM role to the instance. | ||
|
||
Alternatively, you can use the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environmental variables to provide credentials to nginx-asg-sync. | ||
|
||
## Installation | ||
|
||
To install nginx-asg-sync: | ||
|
||
1. Download a software package for your OS with the latest version of nginx-asg-sync from the [Releases page](https://github.com/nginxinc/nginx-asg-sync/releases). | ||
1. Install the package: | ||
|
||
For Amazon Linux or CentOS/RHEL, run: `$ sudo rpm -i <package-name>.rpm` | ||
|
||
For Ubuntu, run: `$ sudo dpkg -i <package-name>.deb` | ||
|
||
## Configuration | ||
|
||
As an example, we configure NGINX Plus to load balance two AWS Auto Scaling groups -- backend-group-one and backend-group-two. NGINX Plus routes requests to the appropriate Auto Scaling group based on the request URI: | ||
|
||
* Requests for /backend-one go to Backend One group. | ||
* Requests for /backend-two go to Backend Two group. | ||
|
||
### NGINX Plus Configuration | ||
|
||
```nginx | ||
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 /backend-two { | ||
proxy_set_header Host $host; | ||
proxy_pass http://backend-two; | ||
} | ||
} | ||
server { | ||
listen 8080; | ||
root /usr/share/nginx/html; | ||
location = / { | ||
return 302 /status.html; | ||
} | ||
location = /status.html { | ||
} | ||
location /status { | ||
access_log off; | ||
status; | ||
} | ||
location /upstream_conf { | ||
upstream_conf; | ||
} | ||
} | ||
``` | ||
|
||
* We declare two upstream groups – **backend-one** and **backend-two**, which correspond to our Auto Scaling 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 APIs on it, which are required by nginx-asg-sync: | ||
* The on-the-fly API is available at **127.0.0.1:8080/upstream_conf** | ||
* The status API is available at **127.0.0.1:8080/status** | ||
|
||
### nginx-asg-sync Configuration | ||
|
||
nginx-asg-sync is configured in the file **aws.yaml** in the **/etc/nginx** folder. For our example, we define the following configuration: | ||
|
||
```yaml | ||
region: us-west-2 | ||
upstream_conf_endpoint: http://127.0.0.1:8080/upstream_conf | ||
status_endpoint: http://127.0.0.1:8080/status | ||
sync_interval_in_seconds: 5 | ||
upstreams: | ||
- name: backend-one | ||
autoscaling_group: backend-one-group | ||
port: 80 | ||
kind: http | ||
- name: backend-two | ||
autoscaling_group: backend-two-group | ||
port: 80 | ||
kind: http | ||
``` | ||
|
||
* The `region` key defines the AWS region where we deploy NGINX Plus and the Auto Scaling groups. | ||
* The `upstream_conf` and the `status_endpoint` keys define the NGINX Plus API endpoints. | ||
* The `sync_interval_in_seconds` key defines the synchronization interval: nginx-asg-sync checks for scaling updates every 5 seconds. | ||
* The `upstreams` key defines the list of upstream groups. For each upstream group we specify: | ||
* `name` – The name we specified for the upstream block in the NGINX Plus configuration. | ||
* `autoscaling_group` – The name of the corresponding Auto Scaling group. | ||
* `port` – The port on which our backend applications are exposed. | ||
* `protocol` – The protocol of the traffic NGINX Plus load balances to the backend application, here `http`. If the application uses TCP/UDP, specify `stream` instead. | ||
|
||
## Usage | ||
|
||
nginx-asg-sync runs as a system service and supports the start/stop/restart commands. | ||
|
||
For Ubuntu 14.04 and Amazon Linux, run: `$ sudo start|stop|restart nginx-asg-sync` | ||
|
||
For Ubuntu 16.04 and CentOS7/RHEL7, 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 | ||
|
||
To build a software package, run: `$ make <os>` | ||
where `<os>` is the target OS. The following values are allowed: | ||
* `amazon` for Amazon Linux | ||
* `centos7` for CentOS7/RHEL7 | ||
* `ubuntu-trusty` for Ubuntu 14.04 | ||
* `ubuntu-xenial` for Ubuntu 16.04 | ||
|
||
If you run make without any arguments, it will build software packages for all supported OSes. | ||
|
||
## Support | ||
|
||
Support from the [NGINX Professional Services Team](https://www.nginx.com/services/) is available when using nginx-asg-sync. |
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
Oops, something went wrong.