{"id":13560508,"url":"https://github.com/weibocom/nginx-upsync-module","last_synced_at":"2025-05-15T12:03:36.584Z","repository":{"id":2258590,"uuid":"42633340","full_name":"weibocom/nginx-upsync-module","owner":"weibocom","description":"For http protocol. nginx-upsync-module, sync upstreams from consul or etcd and so on, dynamiclly modify backend-servers attributes(weight, max_fails, down...), needn't reload nginx","archived":false,"fork":false,"pushed_at":"2023-04-07T11:45:25.000Z","size":1382,"stargazers_count":1836,"open_issues_count":73,"forks_count":393,"subscribers_count":144,"default_branch":"master","last_synced_at":"2025-04-14T19:59:32.369Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/weibocom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-09-17T03:47:38.000Z","updated_at":"2025-03-25T02:52:57.000Z","dependencies_parsed_at":"2023-07-06T12:46:02.343Z","dependency_job_id":null,"html_url":"https://github.com/weibocom/nginx-upsync-module","commit_stats":{"total_commits":160,"total_committers":23,"mean_commits":6.956521739130435,"dds":"0.32499999999999996","last_synced_commit":"579bc8f66094f002d33a79ad7bc273ffdfb7d7ed"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weibocom%2Fnginx-upsync-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weibocom%2Fnginx-upsync-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weibocom%2Fnginx-upsync-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weibocom%2Fnginx-upsync-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/weibocom","download_url":"https://codeload.github.com/weibocom/nginx-upsync-module/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254337612,"owners_count":22054253,"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":"2024-08-01T13:00:45.423Z","updated_at":"2025-05-15T12:03:36.560Z","avatar_url":"https://github.com/weibocom.png","language":"C","funding_links":[],"categories":["C","Modules","Upstreams, rate limiting and access control","Projects"],"sub_categories":["Load Balancing"],"readme":"nginx-upsync-module\n===================\n\nNginx C module, which can sync upstreams from Consul or others. It dynamically modifies backend-servers attributes (weight, max_fails,...), without need to reload NGINX.\n\nIt may not always be convenient to modify configuration files and restart NGINX. For example, if you are experiencing large amounts of traffic and high load, restarting NGINX and reloading the configuration at that point further increases load on the system and can temporarily degrade performance.\n\nThe module allows to expand and scale down without affecting performance.\n\nAnother module, [nginx-stream-upsync-module](https://github.com/xiaokai-wang/nginx-stream-upsync-module) supports NGINX stream module (TCP protocol), please be noticed.\n\nTable of Contents\n=================\n\n* [Name](#name)\n* [Status](#status)\n* [Synopsis](#synopsis)\n* [Description](#description)\n* [Directives](#directives)\n    * [upsync](#upsync)\n        * [upsync_interval](#upsync_interval)\n        * [upsync_timeout](#upsync_timeout)\n        * [upsync_type](#upsync_type)\n        * [strong_dependency](#strong_dependency)\n    * [upsync_dump_path](#upsync_dump_path)\n    * [upsync_lb](#upsync_lb)\n    * [upstream_show](#upstream_show)\n* [Consul_interface](#consul_interface)\n* [Etcd_interface](#etcd_interface)\n* [Check_module](#check_module_support)\n* [TODO](#todo)\n* [Compatibility](#compatibility)\n* [Installation](#installation)\n* [Code style](#code-style)\n* [Author](#author)\n* [Copyright and License](#copyright-and-license)\n* [See Also](#see-also)\n* [Source Dependency](#source-dependency)\n\nStatus\n======\n\nThis module is still under active development and is considered production ready.\n\nSynopsis\n========\n\nnginx-consul:\n```nginx-consul\nhttp {\n    upstream test {\n        upsync 127.0.0.1:8500/v1/kv/upstreams/test/ upsync_timeout=6m upsync_interval=500ms upsync_type=consul strong_dependency=off;\n        upsync_dump_path /usr/local/nginx/conf/servers/servers_test.conf;\n\n        include /usr/local/nginx/conf/servers/servers_test.conf;\n    }\n\n    upstream bar {\n        server 127.0.0.1:8090 weight=1 fail_timeout=10 max_fails=3;\n    }\n\n    server {\n        listen 8080;\n\n        location = /proxy_test {\n            proxy_pass http://test;\n        }\n\n        location = /bar {\n            proxy_pass http://bar;\n        }\n\n        location = /upstream_show {\n            upstream_show;\n        }\n\n    }\n}\n```\nnginx-etcd:\n```nginx-etcd\nhttp {\n    upstream test {\n        upsync 127.0.0.1:2379/v2/keys/upstreams/test upsync_timeout=6m upsync_interval=500ms upsync_type=etcd strong_dependency=off;\n        upsync_dump_path /usr/local/nginx/conf/servers/servers_test.conf;\n\n        include /usr/local/nginx/conf/servers/servers_test.conf;\n    }\n\n    upstream bar {\n        server 127.0.0.1:8090 weight=1 fail_timeout=10 max_fails=3;\n    }\n\n    server {\n        listen 8080;\n\n        location = /proxy_test {\n            proxy_pass http://test;\n        }\n\n        location = /bar {\n            proxy_pass http://bar;\n        }\n\n        location = /upstream_show {\n            upstream_show;\n        }\n\n    }\n}\n```\nupsync_lb:\n```upsync_lb\nhttp {\n    upstream test {\n        least_conn; //hash $uri consistent;\n\n        upsync 127.0.0.1:8500/v1/kv/upstreams/test/ upsync_timeout=6m upsync_interval=500ms upsync_type=consul strong_dependency=off;\n        upsync_dump_path /usr/local/nginx/conf/servers/servers_test.conf;\n        upsync_lb least_conn; //hash_ketama;\n\n        include /usr/local/nginx/conf/servers/servers_test.conf;\n    }\n\n    upstream bar {\n        server 127.0.0.1:8090 weight=1 fail_timeout=10 max_fails=3;\n    }\n\n    server {\n        listen 8080;\n\n        location = /proxy_test {\n            proxy_pass http://test;\n        }\n\n        location = /bar {\n            proxy_pass http://bar;\n        }\n\n        location = /upstream_show {\n            upstream_show;\n        }\n\n    }\n}\n```\n\nNOTE: recommending strong_dependency is configed off and the first time included file include all the servers.\n\nDescription\n======\n\nThis module provides a method to discover backend servers. Supporting dynamicly adding or deleting backend server through consul or etcd and dynamically adjusting backend servers weight, module will timely pull new backend server list from consul or etcd to upsync nginx ip router. Nginx needn't reload. Having some advantages than others:\n\n* timely\n\n      module send key to consul/etcd with index, consul/etcd will compare it with its index, if index doesn't change connection will hang five minutes, in the period any operation to the key-value, will feed back rightaway.\n\n* performance\n\n      Pulling from consul/etcd equal a request to nginx, updating ip router nginx needn't reload, so affecting nginx performance is little.\n\n* stability\n\n      Even if one pulling failed, it will pull next upsync_interval, so guarantying backend server stably provides service. And support dumping the latest config to location, so even if consul/etcd hung up, and nginx can be reload anytime. \n\n* health_check\n\n      nginx-upsync-module support adding or deleting servers health check, needing nginx_upstream_check_module. Recommending nginx-upsync-module + nginx_upstream_check_module.\n\nDirectives\n======\n\nupsync\n-----------\n```\nsyntax: upsync $consul/etcd.api.com:$port/v1/kv/upstreams/$upstream_name/ [upsync_type=consul/etcd] [upsync_interval=second/minutes] [upsync_timeout=second/minutes] [strong_dependency=off/on]\n```\ndefault: none, if parameters omitted, default parameters are upsync_interval=5s upsync_timeout=6m strong_dependency=off\n\ncontext: upstream\n\ndescription: Pull upstream servers from consul/etcd... .\n\nThe parameters' meanings are:\n\n* upsync_interval\n\n    pulling servers from consul/etcd interval time.\n\n* upsync_timeout\n\n    pulling servers from consul/etcd request timeout.\n\n* upsync_type\n\n    pulling servers from conf server type.\n\n* strong_dependency\n\n    when strong_dependency is on, nginx will pull servers from consul/etcd every time when nginx start up or reload.\n\n[Back to TOC](#table-of-contents)       \n\nupsync_dump_path\n-----------\n`syntax: upsync_dump_path $path`\n\ndefault: /tmp/servers_$host.conf\n\ncontext: upstream\n\ndescription: dump the upstream backends to the $path.\n\n[Back to TOC](#table-of-contents)       \n\nupsync_lb\n-----------\n`syntax: upsync_lb $load_balance`\n\ndefault: round_robin/ip_hash/hash modula\n\ncontext: upstream\n\ndescription: mainly for least_conn and hash consistent, when using one of them, you must point out using upsync_lb.\n\n[Back to TOC](#table-of-contents)       \n\nupstream_show\n-----------\n`syntax: upstream_show`\n\ndefault: none\n\ncontext: upstream\n\ndescription: Show specific upstream all backend servers.\n\n```configure\n     location /upstream_list {\n         upstream_show;\n     }\n```\n\n```request1\ncurl http://127.0.0.1:8500/upstream_list?test;\n```\n\n```request2\ncurl http://127.0.0.1:8500/upstream_list;\n\nshow all upstreams.\n```\n\n[Back to TOC](#table-of-contents)       \n\nConsul_interface\n======\n\nData can be taken from key/value store or service catalog. In the first case parameter upsync_type of directive must be *consul*. For example\n\n```nginx-consul\n        upsync 127.0.0.1:8500/v1/kv/upstreams/test upsync_timeout=6m upsync_interval=500ms upsync_type=consul strong_dependency=off;\n```\n\nIn the second case it must be *consul_services*.\n\n```nginx-consul\n        upsync 127.0.0.1:8500/v1/catalog/service/test upsync_timeout=6m upsync_interval=500ms upsync_type=consul_services strong_dependency=off;\n```\n\nIn the third case, it must be *consul_health*:\n\n```nginx-consul\n        upsync 127.0.0.1:8500/v1/health/service/test upsync_timeout=6m upsync_interval=500ms upsync_type=consul_health strong_dependency=off;\n```\n\nServices with failing health checks are marked as down with the health api.\n\nYou can add or delete backend server through consul_ui or http_interface. Below are examples for key/value store.\n\nhttp_interface example:\n\n* add\n```\n    curl -X PUT http://$consul_ip:$port/v1/kv/upstreams/$upstream_name/$backend_ip:$backend_port\n```\n    default: weight=1 max_fails=2 fail_timeout=10 down=0 backup=0;\n\n```\n    curl -X PUT -d \"{\\\"weight\\\":1, \\\"max_fails\\\":2, \\\"fail_timeout\\\":10}\" http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port\nor\n    curl -X PUT -d '{\"weight\":1, \"max_fails\":2, \"fail_timeout\":10}' http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port\n```\n    value support json format.\n\n* delete\n```\n    curl -X DELETE http://$consul_ip:$port/v1/kv/upstreams/$upstream_name/$backend_ip:$backend_port\n```\n\n* adjust-weight\n```\n    curl -X PUT -d \"{\\\"weight\\\":2, \\\"max_fails\\\":2, \\\"fail_timeout\\\":10}\" http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port\nor\n    curl -X PUT -d '{\"weight\":2, \"max_fails\":2, \"fail_timeout\":10}' http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port\n```\n\n* mark server-down\n```\n    curl -X PUT -d \"{\\\"weight\\\":2, \\\"max_fails\\\":2, \\\"fail_timeout\\\":10, \\\"down\\\":1}\" http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port\nor\n    curl -X PUT -d '{\"weight\":2, \"max_fails\":2, \"fail_timeout\":10, \"down\":1}' http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port\n```\n\n* check\n```\n    curl http://$consul_ip:$port/v1/kv/upstreams/$upstream_name?recurse\n```\n\n[Back to TOC](#table-of-contents)       \n\nEtcd_interface\n======\n\nyou can add or delete backend server through http_interface.\n\nmainly like etcd, http_interface example:\n\n* add\n```\n    curl -X PUT http://$etcd_ip:$port/v2/keys/upstreams/$upstream_name/$backend_ip:$backend_port\n```\n    default: weight=1 max_fails=2 fail_timeout=10 down=0 backup=0;\n\n```\n    curl -X PUT -d value=\"{\\\"weight\\\":1, \\\"max_fails\\\":2, \\\"fail_timeout\\\":10}\" http://$etcd_ip:$port/v2/keys/$dir1/$upstream_name/$backend_ip:$backend_port\n```\n    value support json format.\n\n* delete\n```\n    curl -X DELETE http://$etcd_ip:$port/v2/keys/upstreams/$upstream_name/$backend_ip:$backend_port\n```\n\n* adjust-weight\n```\n    curl -X PUT -d \"{\\\"weight\\\":2, \\\"max_fails\\\":2, \\\"fail_timeout\\\":10}\" http://$etcd_ip:$port/v2/keys/$dir1/$upstream_name/$backend_ip:$backend_port\n```\n\n* mark server-down\n```\n    curl -X PUT -d value=\"{\\\"weight\\\":2, \\\"max_fails\\\":2, \\\"fail_timeout\\\":10, \\\"down\\\":1}\" http://$etcd_ip:$port/v2/keys/$dir1/$upstream_name/$backend_ip:$backend_port\n```\n\n* check\n```\n    curl http://$etcd_ip:$port/v2/keys/upstreams/$upstream_name\n```\n\n[Back to TOC](#table-of-contents)       \n\nCheck_module\n======\n\ncheck module support.\n\ncheck-conf:\n```check-conf\nhttp {\n    upstream test {\n        upsync 127.0.0.1:8500/v1/kv/upstreams/test/ upsync_timeout=6m upsync_interval=500ms upsync_type=consul strong_dependency=off;\n        upsync_dump_path /usr/local/nginx/conf/servers/servers_test.conf;\n\n        check interval=1000 rise=2 fall=2 timeout=3000 type=http default_down=false;\n        check_http_send \"HEAD / HTTP/1.0\\r\\n\\r\\n\";\n        check_http_expect_alive http_2xx http_3xx;\n\n    }\n\n    upstream bar {\n        server 127.0.0.1:8090 weight=1 fail_timeout=10 max_fails=3;\n    }\n\n    server {\n        listen 8080;\n\n        location = /proxy_test {\n            proxy_pass http://test;\n        }\n\n        location = /bar {\n            proxy_pass http://bar;\n        }\n\n        location = /upstream_show {\n            upstream_show;\n        }\n\n        location = /upstream_status {\n            check_status;\n            access_log off;\n        }\n\n    }\n}\n```\n\n[Back to TOC](#table-of-contents)       \n\nTODO\n====\n\n* support zookeeper and so on\n\n[Back to TOC](#table-of-contents)\n\nCompatibility\n=============\n\nMaster branch is compatible with nginx-1.9.8+.\n\nThe branch of nginx-upsync-1.8.x is compatible with Nginx-1.8.x and with tengine-2.2.0.\n\n[Back to TOC](#table-of-contents)\n\nInstallation\n============\n\nThis module can be used independently, can be download[Github](https://github.com/weibocom/nginx-upsync-module.git).\n\nGrab the nginx source code from [nginx.org](http://nginx.org/), for example, the version 1.8.0 (see nginx compatibility), and then build the source with this module:\n\n```bash\nwget 'http://nginx.org/download/nginx-1.8.0.tar.gz'\ntar -xzvf nginx-1.8.0.tar.gz\ncd nginx-1.8.0/\n```\n\n```bash\n./configure --add-module=/path/to/nginx-upsync-module\nmake\nmake install\n```\n\nif you support nginx-upstream-check-module\n```bash\npatch -p1 \u003c /path/to/nginx-upstream-check-module/check_1.7.5+.patch\n./configure --add-module=/path/to/nginx-upstream-check-module --add-module=/path/to/nginx-upsync-module\nmake\nmake install\n```\n\n[Back to TOC](#table-of-contents)\n\nCode style\n======\n\nCode style is mainly based on [style](http://tengine.taobao.org/book/appendix_a.html)\n\n[Back to TOC](#table-of-contents)\n\nAuthor\n======\n\nXiaokai Wang (王晓开) \u003cxiaokai.wang@live.com\u003e, Weibo Inc.\n\n[Back to TOC](#table-of-contents)\n\nCopyright and License\n=====================\n\nThis README template copy from agentzh.\n\nThis module is licensed under the BSD license.\n\nCopyright (C) 2014 by Xiaokai Wang \u003cxiaokai.wang@live.com\u003e\u003c/xiaokai.wang@live.com\u003e\n\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:\n\n* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n\n* 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.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT HOLDER 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.\n\n[Back to TOC](#table-of-contents)\n\nsee also\n========\n* the nginx_upstream_check_module: https://github.com/alibaba/tengine/blob/master/src/http/ngx_http_upstream_check_module.c\n* the nginx_upstream_check_module patch: https://github.com/yaoweibin/nginx_upstream_check_module\n* or based on https://github.com/xiaokai-wang/nginx_upstream_check_module\n\n[back to toc](#table-of-contents)\n\nsource dependency\n========\n* Cjson: https://github.com/kbranigan/cJSON\n* http-parser: https://github.com/nodejs/http-parser\n\n[back to toc](#table-of-contents)\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweibocom%2Fnginx-upsync-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweibocom%2Fnginx-upsync-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweibocom%2Fnginx-upsync-module/lists"}