NGINX Instance Manager Tagging Documentation
This document explains how to use tagging with NGINX Instance Manager.
Tagging is a feature designed to help group larger number of instances within NGINX Instance Manager. Tagging serves three purposes:
- Provide labelling to groups of instances for similar configurations.
- Enable OpenID Connect users to limit access to groups of instances.
- 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.
There are two methods to add a tag to an instnace.
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
# # /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 tls: # 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 log: # 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 metadata: location: unspecified # instance tags tags: - web - staging # list of allowed config directories (comma-separated) config_dirs: /etc/nginx,/usr/local/etc/nginx # nginx configuration options nginx: # path of nginx to manage bin_path: /usr/sbin/nginx # specify stub status URL (see: nginx.org/r/stub_status) stub_status "http://127.0.0.1:80/nginx_status" # specify plus status api url (see nginx.org/r/api) plus_api: "http://127.0.0.1:8080/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.
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.
You can then enter the tags you want to use or select an existing tag.
You can also remove tags by selecting the “X” next to the tag, removing the tag from association with that particular instance.
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.
Select the instance you want to use as the source and the tag to push out.
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.
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.
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.