Problem

You need NGINX Plus to make dynamic traffic management decisions based on input from applications.

Solution

Set up the cluster-aware key-value store and API, and then add keys and values:

keyval_zone zone=blacklist:1M;
keyval $remote_addr $num_failures zone=blacklist;

server {
    # ...
    location / {
        if ($num_failures) {
            return 403 'Forbidden';
        }
        return 200 'OK';
    }
}
server {
    # ...
    # Directives limiting access to the API
    # See chapter 6
    location /api {
        api write=on; 
    }
}

This NGINX Plus configuration uses the keyval_zone directory to build a key-value store shared memory zone named blacklist and sets a memory limit of 1 MB. The keyval directive then maps the value of the key matching the first parameter $remote_addr to a new variable named $num_failures from the zone. This new variable is then used to determine whether NGINX Plus should serve the request or return a 403 Forbidden code.

After starting the NGINX Plus server with this configuration, you can curl the local machine and expect to receive a 200 OK response.

$ curl 'http://127.0.0.1/'
OK

Now add the local machine’s IP address to the key-value store with a value of 1:

$ curl -X POST -d '{"127.0.0.1":"1"}' 
  'http://127.0.0.1/api/3/http/keyvals/blacklist'

This curl command submits an HTTP POST request with a JSON object containing a key-value object to be submitted to the blacklist shared memory zone. The key-value store API URI is formatted as follows:

/api/{version}/http/keyvals/{httpKeyvalZoneName}

The local machine’s IP address is now added to the key-value zone named blacklist with a value of 1. In the next request, NGINX Plus looks up the $remote_addr in the key-value zone, finds the entry, and maps the value to the variable $num_failures. This variable is then evaluated in the if statement. When the variable has a value, the if evaluates to True and NGINX Plus returns the 403 Forbidden return code:

$ curl 'http://127.0.0.1/'
Forbidden

You can update or delete the key by making a PATCH method request:

$ curl -X PATCH -d '{"127.0.0.1":null}' 
  'http://127.0.0.1/api/3/http/keyvals/blacklist'

NGINX Plus deletes the key if the value is null, and requests will again return 200 OK.

Discussion

The key-value store, an NGINX Plus exclusive feature, enables applications to inject information into NGINX Plus. In the example provided, the $remote_addr variable is used to create a dynamic blacklist. You can populate the key-value store with any key that NGINX Plus might have as a variable—a session cookie, for example—and provide NGINX Plus an external value. In NGINX Plus R16, the key-value store became cluster-aware, meaning that you have to provide your key-value update to only one NGINX Plus server, and all of them will receive the information.

Also See

Dynamic Bandwidth Limits

Problem

You need to install and configure NGINX with Puppet to manage NGINX configurations as code and conform with the rest of your Puppet configurations.

Solution

Create a module that installs NGINX, manages the files you need, and ensures that NGINX is running:

 class nginx {
    package {"nginx": ensure => 'installed',}
    service {"nginx": 
        ensure => 'true',
        hasrestart => 'true',
        restart => '/etc/init.d/nginx reload',
    }
    file { "nginx.conf":
        path    => '/etc/nginx/nginx.conf',
        require => Package['nginx'],
        notify  => Service['nginx'],
        content => template('nginx/templates/nginx.conf.erb'),
        user=>'root', 
        group=>'root', 
        mode='0644';
    }
}

This module uses the package management utility to ensure the NGINX package is installed. It also ensures NGINX is running and enabled at boot time. The configuration informs Puppet that the service has a restart command with the hasrestart directive, and we can override the restart command with an NGINX reload. The file resource will manage and template the nginx.conf file with the Embedded Ruby (ERB) templating language. The templating of the file will happen after the NGINX package is installed due to the require directive. However, the file resource will notify the NGINX service to reload because of the notify directive. The templated configuration file is not included. However, it can be simple to install a default NGINX configuration file, or very complex if using ERB or EPP templating language loops and variable substitution.

Discussion

Puppet is a configuration management tool based in the Ruby programming language. Modules are built in a domain-specific language and called via a manifest file that defines the configuration for a given server. Puppet can be run in a master-slave or masterless configuration. With Puppet, the manifest is run on the master and then sent to the slave. This is important because it ensures that the slave is only delivered the configuration meant for it and no extra configurations meant for other servers. There are a lot of extremely advanced public modules available for Puppet. Starting from these modules will help you get a jump-start on your configuration. A public NGINX module from voxpupuli on GitHub will template out NGINX configurations for you.

Also See

Puppet Documentation
Puppet Package Documentation
Puppet Service Documentation
Puppet File Documentation
Puppet Templating Documentation
Voxpupuli NGINX Module

Problem

You need to install and configure NGINX with Chef to manage NGINX configurations as code and conform with the rest of your Chef configurations.

Solution

Create a cookbook with a recipe to install NGINX and configure configuration files through templating, and ensure NGINX reloads after the configuration is put in place. The following is an example recipe:

package 'nginx' do
  action :install
end

service 'nginx' do
  supports :status => true, :restart => true, :reload => true
  action   [ :start, :enable ]
end

template 'nginx.conf' do
  path   "/etc/nginx.conf"
  source "nginx.conf.erb"
  owner  'root'
  group  'root'
  mode   '0644'
  notifies :reload, 'service[nginx]', :delayed
end

The package block installs NGINX. The service block ensures that NGINX is started and enabled at boot, then declares to the rest of Chef what the nginx service will support as far as actions. The template block templates an ERB file and places it at /etc/nginx.conf with an owner and group of root. The template block also sets the mode to 644 and notifies the nginx service to reload, but waits until the end of the Chef run declared by the :delayed statement. The templated configuration file is not included. However, it can be as simple as a default NGINX configuration file or very complex with ERB templating language loops and variable substitution.

Discussion

Chef is a configuration management tool based in Ruby. Chef can be run in a master-slave, or solo configuration, now known as Chef Zero. Chef has a very large community with many public cookbooks called the Supermarket. Public cookbooks from the Supermarket can be installed and maintained via a command-line utility called Berkshelf. Chef is extremely capable, and what we have demonstrated is just a small sample. The public NGINX cookbook in the Supermarket is extremely flexible and provides the options to easily install NGINX from a package manager or from source, and the ability to compile and install many different modules as well as template out the basic configurations.

Also See

Chef documentation
Chef Package
Chef Service
Chef Template
Chef Supermarket for NGINX

Problem

You need to install and configure NGINX with Ansible to manage NGINX configurations as code and conform with the rest of your Ansible configurations.

Solution

Create an Ansible playbook to install NGINX and manage the nginx.conf file. The following is an example task file for the playbook to install NGINX. Ensure it’s running and template the configuration file:

- name: NGINX | Installing NGINX
  package: name=nginx state=present
 
- name: NGINX | Starting NGINX
  service:
    name: nginx
    state: started
    enabled: yes

- name: Copy nginx configuration in place.
  template:
    src: nginx.conf.j2
    dest: "/etc/nginx/nginx.conf"
    owner: root
    group: root
    mode: 0644
  notify:
    - reload nginx

The package block installs NGINX. The service block ensures that NGINX is started and enabled at boot. The template block templates a Jinja2 file and places the result at /etc/nginx.conf with an owner and group of root. The template block also sets the mode to 644 and notifies the nginx service to reload. The templated configuration file is not included. However, it can be as simple as a default NGINX configuration file or very complex with Jinja2 templating language loops and variable substitution.

Discussion

Ansible is a widely used and powerful configuration management tool based in Python. The configuration of tasks is in YAML, and you use the Jinja2 templating language for file templating. Ansible offers a master named Ansible Tower on a subscription model. However, it’s commonly used from local machines or to build servers directly to the client or in a masterless model. Ansible bulk SSHes into its servers and runs the configurations. Much like other configuration management tools, there’s a large community of public roles. Ansible calls this the Ansible Galaxy. You can find very sophisticated roles to utilize in your playbooks.

Also See

Ansible Documentation
Ansible Packages
Ansible Service
Ansible Template
Ansible Galaxy

Problem

You need to install and configure NGINX with SaltStack to manage NGINX configurations as code and conform with the rest of your SaltStack configurations.

Solution

Install NGINX through the package management module and manage the configuration files you desire. The following is an example state file (sls) that will install the nginx package and ensure the service is running, enabled at boot, and reload if a change is made to the configuration file:

nginx:
  pkg:
    - installed
  service:
    - name: nginx
    - running
    - enable: True
    - reload: True
    - watch:
      - file: /etc/nginx/nginx.conf

/etc/nginx/nginx.conf:
  file:
    - managed
    - source: salt://path/to/nginx.conf
    - user: root
    - group: root
    - template: jinja
    - mode: 644
    - require:
      - pkg: nginx

This is a basic example of installing NGINX via a package management utility and managing the nginx.conf file. The NGINX package is installed and the service is running and enabled at boot. With SaltStack you can declare a file managed by Salt as seen in the example and templated by many different templating languages. The templated configuration file is not included. However, it can be as simple as a default NGINX configuration file or very complex with the Jinja2 templating language loops and variable substitution. This configuration also specifies that NGINX must be installed prior to managing the file because of the require statement. After the file is in place, NGINX is reloaded because of the watch directive on the service and reloads as opposed to restarts because the reload directive is set to True.

Discussion

SaltStack is a powerful configuration management tool that defines server states in YAML. Modules for SaltStack can be written in Python. Salt exposes the Jinja2 templating language for states as well as for files. However, for files there are many other options, such as Mako, Python itself, and others. Salt works in a master-slave configuration as well as a masterless configuration. Slaves are called minions. The master-slave transport communication, however, differs from others and sets SaltStack apart. With Salt you’re able to choose ZeroMQ, TCP, or Reliable Asynchronous Event Transport (RAET) for transmissions to the Salt agent; or you can not use an agent, and the master can SSH instead. Because the transport layer is by default asynchronous, SaltStack is built to be able to deliver its message to a large number of minions with low load to the master server.

Also See

SaltStack
Installed Packages
Managed Files
Templating with Jinja

Problem

You need to automate your NGINX configuration to respond to changes in your environment through use of Consul.

Solution

Use the consul-template daemon and a template file to template out the NGINX configuration file of your choice:

upstream backend { {{range service "app.backend"}}
    server {{.Address}};{{end}}
}

This example is a Consul Template file that templates an upstream configuration block. This template will loop through nodes in Consul identified as app.backend. For every node in Consul, the template will produce a server directive with that node’s IP address.

The consul-template daemon is run via the command line and can be used to reload NGINX every time the configuration file is templated with a change:

# consul-template -consul consul.example.internal -template 
 template:/etc/nginx/conf.d/upstream.conf:"nginx -s reload"

This command instructs the consul-template daemon to connect to a Consul cluster at consul.example.internal and to use a file named template in the current working directory to template the file and output the generated contents to /etc/nginx/conf.d/upstream.conf, then to reload NGINX every time the templated file changes. The -template flag takes a string of the template file, the output location, and the command to run after the templating process takes place; these three variables are separated by a colon. If the command being run has spaces, make sure to wrap it in double quotes. The -consul flag tells the daemon what Consul cluster to connect to.

Discussion

Consul is a powerful service discovery tool and configuration store. Consul stores information about nodes as well as key-value pairs in a directory-like structure and allows for restful API interaction. Consul also provides a DNS interface on each client, allowing for domain name lookups of nodes connected to the cluster. A separate project that utilizes Consul clusters is the consul-template daemon; this tool templates files in response to changes in Consul nodes, services, or key-value pairs. This makes Consul a very powerful choice for automating NGINX. With consul-template you can also instruct the daemon to run a command after a change to the template takes place. With this, we can reload the NGINX configuration and allow your NGINX configuration to come alive along with your environment. With Consul you’re able to set up health checks on each client to check the health of the intended service. With this failure detection, you’re able to template your NGINX configuration accordingly to only send traffic to healthy hosts.

Also See

Consul Home Page
Introduction to Consul Template
Consul Template GitHub