{"id":24060818,"url":"https://github.com/nginx/nginx-asg-sync","last_synced_at":"2025-04-07T06:08:23.684Z","repository":{"id":38434413,"uuid":"84063179","full_name":"nginx/nginx-asg-sync","owner":"nginx","description":"NGINX Plus Integration with Cloud Autoscaling ","archived":false,"fork":false,"pushed_at":"2025-02-05T00:25:38.000Z","size":4278,"stargazers_count":57,"open_issues_count":3,"forks_count":25,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-02-05T22:14:10.738Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nginx.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-03-06T11:01:26.000Z","updated_at":"2025-02-04T19:43:49.000Z","dependencies_parsed_at":"2023-10-23T08:31:17.271Z","dependency_job_id":"bf297827-c68b-4137-bf2c-71e739e65143","html_url":"https://github.com/nginx/nginx-asg-sync","commit_stats":null,"previous_names":["nginx/nginx-asg-sync","nginxinc/nginx-asg-sync"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx%2Fnginx-asg-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx%2Fnginx-asg-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx%2Fnginx-asg-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx%2Fnginx-asg-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nginx","download_url":"https://codeload.github.com/nginx/nginx-asg-sync/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247601448,"owners_count":20964864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-09T07:15:04.241Z","updated_at":"2025-04-07T06:08:23.657Z","avatar_url":"https://github.com/nginx.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable-next-line first-line-h1 --\u003e\n[![OpenSSFScorecard](https://api.securityscorecards.dev/projects/github.com/nginx/nginx-asg-sync/badge)](https://scorecard.dev/viewer/?uri=github.com/nginx/nginx-asg-sync)\n[![CI](https://github.com/nginx/nginx-asg-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/nginx/nginx-asg-sync/actions/workflows/ci.yml)\n[![FOSSAStatus](https://app.fossa.com/api/projects/custom%2B5618%2Fgithub.com%2Fnginx%2Fnginx-asg-sync.svg?type=shield)](https://app.fossa.com/projects/custom%2B5618%2Fgithub.com%2Fnginx%2Fnginx-asg-sync?ref=badge_shield)\n[![Go Report Card](https://goreportcard.com/badge/github.com/nginx/nginx-asg-sync)](https://goreportcard.com/report/github.com/nginx/nginx-asg-sync)\n![GitHub all releases](https://img.shields.io/github/downloads/nginx/nginx-asg-sync/total?logo=github)\n![GitHub release (latest by SemVer)](https://img.shields.io/github/downloads/nginx/nginx-asg-sync/latest/total?sort=semver\u0026logo=github)\n[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/nginx/nginx-asg-sync?logo=github\u0026sort=semver)](https://github.com/nginx/nginx-asg-sync/releases/latest)\n![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/nginx/nginx-asg-sync?logo=go)\n[![nginx-asg-sync](https://snapcraft.io/nginx-asg-sync/badge.svg)](https://snapcraft.io/nginx-asg-sync)\n[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)\n\n# NGINX Plus Integration with Cloud Autoscaling -- nginx-asg-sync\n\n**nginx-asg-sync** allows [NGINX Plus](https://www.nginx.com/products/) to discover instances (virtual machines) of a\nscaling group of a cloud provider. The following providers are supported:\n\n- AWS [Auto Scaling groups](http://docs.aws.amazon.com/autoscaling/latest/userguide/WhatIsAutoScaling.html)\n- Azure [Virtual Machine Scale Sets](https://docs.microsoft.com/en-us/azure/virtual-machine-scale-sets/)\n\nWhen the number of instances changes, nginx-asg-sync adds the new instances to the NGINX Plus configuration and removes\nthe terminated ones.\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n## Table of Contents\n\n- [How It Works](#how-it-works)\n- [Documentation](#documentation)\n- [Supported Operating Systems and Architectures](#supported-operating-systems-and-architectures)\n- [Installation](#installation)\n  - [Manual Installation](#manual-installation)\n  - [Snap Installation](#snap-installation)\n  - [Homebrew Installation](#homebrew-installation)\n- [NGINX Plus Configuration](#nginx-plus-configuration)\n- [Configuration for Cloud Providers](#configuration-for-cloud-providers)\n- [Usage](#usage)\n- [Troubleshooting](#troubleshooting)\n- [Building a Software Package](#building-a-software-package)\n- [Contacts](#contacts)\n- [Contributing](#contributing)\n- [Support](#support)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## How It Works\n\nnginx-asg-sync is an agent process that runs on the same instance as NGINX Plus. It polls for changes to the backend\ninstance groups via the Cloud Provider API.\n\nWhen it sees that a scaling event has happened, it adds or removes the corresponding backend instances from the NGINX\nPlus configuration via the NGINX Plus API.\n\n\u003e **Note**\n\u003e\n\u003e nginx-asg-sync does not scale cloud scaling groups, it only gets the IP addresses of the instances in the groups.\n\nIn the example below (AWS), NGINX Plus is configured to load balance among the instances of two AWS Auto Scaling groups\n-- Backend One and Backend Two. nginx-asg-sync, running on the same instance as NGINX Plus, ensures that whenever you\nscale the Auto Scaling groups, the corresponding instances are added (or removed) from the NGINX Plus configuration.\n\n![nginx-asg-sync-architecture](aws-auto-scaling-group-asg-sync.png)\n\nBelow you will find documentation on how to use nginx-asg-sync.\n\n## Documentation\n\nThe documentation for **the latest stable release** is available via a link in the description of the release. See the\n[releases page](https://github.com/nginx/nginx-asg-sync/releases).\n\n## Supported Operating Systems and Architectures\n\nWe provide `.rpm` and `.deb` packages for `386`, `amd64`, `arm64`, `ppc64le` and `s390x`.\n\nSupport for other operating systems or architectures can be added.\n\n## Installation\n\n### Manual Installation\n\n1. Get a software package for your OS:\n   - For a stable release, download a package from the [releases page](https://github.com/nginx/nginx-asg-sync/releases).\n   - For the latest source code from the main branch, build a software package by following [these\n     instructions](#building-a-software-package).\n2. Install the package:\n   - For CentOS/RHEL based OSs, run: `sudo rpm -i \u003cpackage-name\u003e.rpm`\n   - For Debian based OSs, run: `sudo dpkg -i \u003cpackage-name\u003e.deb`\n\n### Snap Installation\n\nYou can install the NGINX Plus Integration with Cloud Autoscaling from the [Snap Store](https://snapcraft.io/nginx-asg-sync).\n\n```console\nsudo snap install nginx-asg-sync\n```\n\n### Homebrew Installation\n\nYou can add the NGINX homebrew tap with\n\n```console\nbrew tap nginx/tap\n```\n\nand then install the formula with\n\n```console\nbrew install nginx-asg-sync\n```\n\n## NGINX Plus Configuration\n\nAs an example, we configure NGINX Plus to load balance two groups of instances -- backend-group-one and\nbackend-group-two. NGINX Plus routes requests to the appropriate group based on the request URI:\n\n- Requests for /backend-one go to Backend One group.\n- Requests for /backend-two go to Backend Two group.\n\nThis example corresponds to [the diagram](#how-it-works) at the top of this README.\n\n```nginx\nupstream backend-one {\n   zone backend-one 64k;\n   state /var/lib/nginx/state/backend-one.conf;\n}\n\nupstream backend-two {\n   zone backend-two 64k;\n   state /var/lib/nginx/state/backend-two.conf;\n}\n\nserver {\n   listen 80;\n\n   status_zone backend;\n\n   location /backend-one {\n       proxy_set_header Host $host;\n       proxy_pass http://backend-one;\n   }\n\n   location @hc-backend-one {\n       internal;\n       proxy_connect_timeout 1s;\n       proxy_read_timeout 1s;\n       proxy_send_timeout 1s;\n\n       proxy_pass http://backend-one;\n       health_check interval=1s mandatory;\n   }\n\n   location /backend-two {\n       proxy_set_header Host $host;\n       proxy_pass http://backend-two;\n   }\n\n   location @hc-backend-two {\n       internal;\n       proxy_connect_timeout 1s;\n       proxy_read_timeout 1s;\n       proxy_send_timeout 1s;\n\n       proxy_pass http://backend-two;\n       health_check interval=1s mandatory;\n   }\n}\n\nserver {\n    listen 8080;\n\n    location /api {\n        api write=on;\n    }\n\n    location /dashboard.html {\n      root /usr/share/nginx/html;\n    }\n}\n```\n\n- We declare two upstream groups – **backend-one** and **backend-two**, which correspond to our instance groups.\n  However, we do not add any servers to the upstream groups, because the servers will be added by nginx-aws-sync. The\n  `state` directive names the file where the dynamically configurable list of servers is stored, enabling it to persist\n  across restarts of NGINX Plus.\n- We define a virtual server that listens on port 80. NGINX Plus passes requests for **/backend-one** to the instances\n  of the Backend One group, and requests for **/backend-two** to the instances of the Backend Two group.\n- We define a second virtual server listening on port 8080 and configure the NGINX Plus API on it, which is required by\n  nginx-asg-sync:\n  - The API is available at **127.0.0.1:8080/api**\n\nBecause cloud provider APIs return the instances IP addresses before the instances are ready and/or provisioned, we\nrecommend setting up mandatory active\n[healthchecks](http://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#health_check) for all upstream groups -\n**@hc-backend-one** and **@hc-backend-two**. This way, NGINX Plus won't pass any request to an instance that is still\nbeing provisioned or has been deleted recently.\n\nSmall timeouts ensure that a health check will fail fast if the backend instance is not healthy. Also, the mandatory\nparameter ensures NGINX Plus won't consider a newly added instance healthy until a health check passes.\n\nWhen using AWS it's possible to filter out the instances that are not in a `InService` state of the\n[Lifecycle](https://docs.aws.amazon.com/autoscaling/ec2/userguide/AutoScalingGroupLifecycle.html) with the parameter\n`in_service` set to `true`. This will ensure that the IP won't be added until the instance is ready to accept requests.\nThis also works when an instance is being terminated: the asg-sync will remove the IP of an instance that went from the\n`InService` state to one of the terminating states.\n\n\u003e **Note**\n\u003e\n\u003e Because the asg-sync works on a polling-based model, there will be a delay between the instance going to a\n\u003e terminating state and the asg-sync removing its IP from NGINX Plus. To guarantee that NGINX Plus doesn't send any\n\u003e requests to a terminated instance, make sure the instance goes to the `Terminating:Wait` state for a period greater\n\u003e than the interval `sync_interval`.\n\n## Configuration for Cloud Providers\n\nSee the example for your cloud provider: [AWS](examples/aws.md), [Azure](examples/azure.md).\n\n## Usage\n\nnginx-asg-sync runs as a system service and supports the start/stop/restart commands.\n\n```console\nsudo service nginx-asg-sync start|stop|restart\n```\n\n## Troubleshooting\n\nIf nginx-asg-sync doesn’t work as expected, check its log file available at\n**/var/log/nginx-aws-sync/nginx-aws-sync.log**.\n\n## Building a Software Package\n\nYou can compile nginx-asg-sync and build a software package using the provided Makefile. Before you start building a\npackage, make sure that the following software is installed on your system:\n\n- make\n- Docker\n- Go (optional, to build the binary locally)\n- [GoReleaser](https://goreleaser.com/) (optional, to build the binaries and packages locally)\n\nTo build the binary locally, and only for the host architecture, run `make nginx-asg-sync`.\n\nTo build the binaries and packages for all the supported architectures, run `make build-goreleaser`.\n\nTo build the binaries and packages for all the supported architectures in Docker, run `make build-goreleaser-docker`.\n\n\u003e **Note**\n\u003e\n\u003e When building with GoReleaser the resulting binaries and packages are located in the `dist` folder.\n\n## Contacts\n\nWe’d like to hear your feedback! If you have any suggestions or experience issues with the NGINX Plus Integration with\nCloud Autoscaling, please create an issue or send a pull request on GitHub. You can contact us directly via\n\u003cintegrations@nginx.com\u003e or on the [NGINX Community Slack](https://nginxcommunity.slack.com).\n\n## Contributing\n\nIf you'd like to contribute to the project, please read our [Contributing guide](CONTRIBUTING.md).\n\n## Support\n\nSupport from the [NGINX Professional Services Team](https://www.nginx.com/services/) is available when using\nnginx-asg-sync.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnginx%2Fnginx-asg-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnginx%2Fnginx-asg-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnginx%2Fnginx-asg-sync/lists"}