NGINX Instance Manager Tagging Documentation

This document explains how to use tagging with NGINX Instance Manager.

How it works

Tagging is a feature designed to help group larger number of instances within NGINX Instance Manager. Tagging serves three purposes:

  1. Provide labelling to groups of instances for similar configurations.
  2. Enable OpenID Connect users to limit access to groups of instances.
  3. Provide a way to group metrics based on a tag.

A tag is a free-form label that Instance Manager uses to group more than one instance. In addition, an instnace may contain more than one tag.

Adding a tag

There are two methods to add a tag to an instnace.

Configuration File

The nginx-agent.conf file can be used to add a tag to an instance. These tags will always show up during registration and won’t be removed from the UI (even if you attempt to remove them in the UI, the agent will add them back upon a restart). To add tags to the configuration, edit the nginx-agent.conf and include the tags in a list under the key tags:.

# /etc/nginx-agent/nginx-agent.conf

# Configuration file for NGINX Agent

# specify the server grpc port to connect to
server: nginx-manager.example.com:10443
metrics-mode: nim

# tls options
  # enable tls in the nginx-manager setup for grpcs
  enable: true
  # path to certificate
  cert: /etc/ssl/nginx-manager/agent.crt
  # path to certificate key
  key: /etc/ssl/nginx-manager/agent.key
  # path to CA cert
  ca: /etc/ssl/nginx-manager/ca.pem
  # set log level (panic, fatal, error, info, debug, trace; default: info) (default "info")
  level: info
  # set log path. if empty, don't log to file.
  path: /var/log/nginx-agent/
# (optional) tags for this specific instance / machine for inventory purposes
  location: unspecified
# instance tags
- web
- staging
# list of allowed config directories (comma-separated)
config_dirs: /etc/nginx,/usr/local/etc/nginx
# nginx configuration options
  # path of nginx to manage
  bin_path: /usr/sbin/nginx
  # specify stub status URL (see: nginx.org/r/stub_status)
  stub_status ""
  # specify plus status api url (see nginx.org/r/api)
  plus_api: ""
  # specify metrics poll interval
  metrics_poll_interval: 1000ms
  # specify access logs to exclude from metrics (comma separated)
  #exclude_logs: /var/log/nginx/skipthese*,/var/log/nginx/special-access.log

To have the tags take effect, restart the nginx-agent service.

Add tags using UI

The User Interface (“UI”) can also be used to add tags to instances.

Click on the instance row to open the slide out panel on the right side.

Slide Out Panel

You can then enter the tags you want to use or select an existing tag.

Tag Selection

You can also remove tags by selecting the “X” next to the tag, removing the tag from association with that particular instance.

Using a tag to push to multiple instances

NGINX Instance Manager can leverage tags to copy an nginx configuration to multiple instances tagged with the same tag.

To use this function in the UI, you can select the tags button in the inventory page, which opens a panel to copy the configuration from one instance to the other instances.

Tag Button

Select the instance you want to use as the source and the tag to push out.

Clone Selection

You can then clone the configuration to the other instances. This saves the configuration in the Instance Manager database but does not write the configuration to the instance disk yet. To write the configuration to the instance and publish the changes, select publish.

Using tags with access control

You can use tags to control or restrict access to tagged instances. This feature is currently in Tech Preview and is described in more detail on the authentication page.

Using tags with metrics

Tags can also be used with metrics. To prevent exponential growth, tags are provided as a comma separated list of tags that can be used to filter per instance. Labels can be added if desired but the effect does increase storage usage.