{"id":28448377,"url":"https://github.com/quiq/lua-consul-balancer","last_synced_at":"2025-09-17T11:55:21.807Z","repository":{"id":53198434,"uuid":"521256691","full_name":"Quiq/lua-consul-balancer","owner":"Quiq","description":"Consul balancer for Openresty/Nginx","archived":false,"fork":false,"pushed_at":"2024-11-12T15:22:11.000Z","size":17,"stargazers_count":7,"open_issues_count":1,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-07-01T02:39:29.701Z","etag":null,"topics":["balancer","consul","lua","nginx","openresty"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Quiq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-08-04T12:24:46.000Z","updated_at":"2024-11-12T15:23:19.000Z","dependencies_parsed_at":"2022-09-15T01:53:52.743Z","dependency_job_id":null,"html_url":"https://github.com/Quiq/lua-consul-balancer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Quiq/lua-consul-balancer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Quiq%2Flua-consul-balancer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Quiq%2Flua-consul-balancer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Quiq%2Flua-consul-balancer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Quiq%2Flua-consul-balancer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Quiq","download_url":"https://codeload.github.com/Quiq/lua-consul-balancer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Quiq%2Flua-consul-balancer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275591115,"owners_count":25492265,"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","status":"online","status_checked_at":"2025-09-17T02:00:09.119Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["balancer","consul","lua","nginx","openresty"],"created_at":"2025-06-06T13:08:17.979Z","updated_at":"2025-09-17T11:55:21.801Z","avatar_url":"https://github.com/Quiq.png","language":"Lua","readme":"# lua-consul-balancer\n\nConsul balancer for Openresty/Nginx.\n\n* consul-balancer.lua - a lua file ready to copy/paste\n* nginx.conf - the minimal Nginx config as an example\n\n## Features\n\n* Discover services from one or multiple Consul endpoints and stores their addresses for load balancing\n* Periodically refresh addresses\n* By default it picks up only non-critical services based on the Consul native healthcheck\n* Optionally, you can enable an additional custom healthcheck against the service URL or allow services in warning state\n* Traffic throttling for new instances of the services as configured by service_warmup_period\n* Last address standing - in case no addresses are available from Consul you will still get the latest one\n* Bonus: extra logic to sleep for 5s every 10 retries on error if `set $delayed_retry 1;` is defined on nginx location\n\n## Description\n\nYou can configure service discovery refresh interval. There are also a couple of hardcoded settings in the lua file.\n\nTraffic throttling means that a new service will receive less traffic proportionally within service_warmup_period.\nFor example, if service_warmup_period is 60s then a new service instance will receive 10% of the traffic on 10th second, 50% on 30th second and so on until full on 60th second. It will be visible from the status page\n(see percentage in the end of this page as an example).\n\nWe are using this lua code at Quiq for 4 years or so and it is very fast with even 50 services in total\nand multiple addresses per each one. It doesn't produce much load on Openresty/Nginx if any at all.\n\n## Openresty required modules\n\n* lua-resty-http\n* lunajson\n\nThey can be installed via luarocks:\n\n    /usr/local/openresty/luajit/bin/luarocks install lua-resty-http\n    /usr/local/openresty/luajit/bin/luarocks install lunajson\n\n## Test with docker\n\nAssuming you have added certificates to the folder, updated nginx.conf according to your needs\nyou can run a test as follow:\n\n    $ ls -la\n    total 80\n    -rw-r--r--  1 weber  staff   1830 Aug  3 16:38 bundle-crt.pem\n    -rw-r--r--  1 weber  staff   3940 Aug  3 16:42 ca-certificates.crt\n    -rw-r--r--  1 weber  staff  12459 Aug  4 15:20 consul-balancer.lua\n    -rw-r--r--  1 weber  staff   3243 Aug  3 16:38 key.pem\n    -rw-r--r--  1 weber  staff   1956 Aug  4 15:21 nginx.conf\n    $\n    $ docker run --rm -d -p 443:443 -v $PWD:/usr/local/openresty/nginx/conf:ro quiq/openresty:1.21.4.1-alpine\n\n    $ curl -k https://localhost/status\n    * Consul SD\n      Last refresh time:        Thu Aug  4 12:21:51 2022\n      foobar-service:           10.0.7.71:8081\n      another-service:          10.0.7.74:8082 10.0.7.75:8082[50%]\n\n`quiq/openresty` is our docker image built with everything required and available from Docker Hub.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquiq%2Flua-consul-balancer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquiq%2Flua-consul-balancer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquiq%2Flua-consul-balancer/lists"}