Need help with ngx_http_consul_backend_module?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

140 Stars 25 Forks Mozilla Public License 2.0 9 Commits 0 Opened issues


An nginx module for setting backends from Consul services.

Services available


Need anything else?

Contributors list

# 3,848
4 commits
# 12,146
2 commits
# 26,338
1 commit

nginx + Consul Backend

This repository contains an nginx module extension for dynamically choosing a healthy backend by communicating directly with HashiCorp Consul's API.

This code is for example purposes only. It demonstrates both the ability to call Go code from C and the ability to link nginx directly to Consul! It is not production ready and should be considered inspiration only.


This module installs a

directive inside the
block, and sets the resulting
variable to one of the healthy IP:PORT by the given service.
http {
  server {
    listen       80;

location /my-service {
  consul $backend service-name;
  proxy_pass http://$backend;

} }

In this example, when a request to "" comes to nginx, nginx invokes the

directive and looks for a healthy service named "service-name", returning a random entry from the list. Then it utilized nginx's built-in
to send traffic to that IP:PORT.

To put it another way, requests to "" are load-balanced among the instances registered in a Consul service, using Consul's health checks to remove unhealthy backends automatically.


Instead of re-inventing the wheel, this module uses Consul's existing Golang API client. The majority of the code is written in Go, with small glue pieces to wire it back into the required C code for nginx. This makes use of golang shared C libraries.

Positively, this gains all the benefits of using the official API client library, including configuration via familiar environment variables, connection pooling and multiplexing, and time-tested stability. This saves the need to write and maintain a new client library written in pure C, and allows us to showcase a really cool feature of Go - shared C libraries. Each request goes through Consul, meaning the probability of routing traffic to an unhealthy host is significantly lower than other solutions.

Negatively, this requires Golang to compile the dynamic library

file. In theory, this could be compiled in advance by a CI/CD system. There is no need for the Golang runtime, since the runtime is compiled into the dynamic library. Additionally, each request goes through Consul. Thus using a local agent is required for performance and latency reasons.

The general flow is as follows:

  1. A request comes into nginx that matches a defined

    block with a
  2. nginx calls the

    function with two arguments.
    1. The first argument is the variable in which to store the result (e.g.
    2. The second argument is the name of the Consul service to route to (e.g.
  3. The

    on the shared C library (the
    file mentioned above), and executes the Go function by calling its symbol.
  4. The Go function communicates with Consul using the official API client library, compiles a list of IP:PORT results, and then chooses a random result to return.

  5. The IP:PORT is returned to the

    function, which then sets the result as the defined variable (e.g.
  6. Usually the next step is to use the built-in

    directive to send traffic to that host.


This installation guide uses ubuntu/debian. Adapt as-needed for other platforms.


  • Golang >= 1.9
  • Standard build tools, including GCC


  1. Install the necessary build tools:

    $ apt-get -yqq install build-essential curl git libpcre3 libpcre3-dev libssl-dev zlib1g-dev
  2. Download and extract nginx source:

    $ cd /tmp
    $ curl -sLo nginx.tgz
    $ tar -xzvf nginx.tgz
  3. Download and extract the nginx development kit (ndk):

    $ cd /tmp
    $ curl -sLo ngx_devel_kit-0.3.0.tgz
    $ tar -xzvf ngx_devel_kit-0.3.0.tgz
  4. Download/clone this repository:

    $ git clone /go/src/
  5. Compile the Go code as a shared C library which nginx will dynamically load. This uses CGO and binds to the nginx development kit:

    $ cd /tmp/ngx_http_consul_backend_module/src
    $ mkdir -p /usr/local/nginx/ext
    $ CGO_CFLAGS="-I /tmp/ngx_devel_kit-0.3.0/src" \
        go build \
          -buildmode=c-shared \
          -o /usr/local/nginx/ext/ \

    This will compile the object file with symbols to

    . Note that the name and location of this file is important - it will be
    ed at runtime by nginx.
  6. Compile and install nginx with the modules:

    $ cd /tmp/nginx-1.12.2
    $ CFLAGS="-g -O0" \
        ./configure \
          --with-debug \
          --add-module=/tmp/ngx_devel_kit-0.3.0 \
    $ make
    $ make install
  7. Add the required nginx configuration and restart nginx:

    http {
      server {
        listen       80;
    location /my-service {
      consul $backend service-name;
      proxy_pass http://$backend;

    } }

    Unlike other solutions, you will not have to restart nginx each time a change happens in the Consul services. Instead, because each request delegates to Consul, you will get real-time results, and traffic will never be routed to an unhealthy host!


There is a sample Dockerfile and entrypoint which builds and runs this custom nginx installation with all required modules.


We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.