NGINX Instance Manager Tagging Documentation
You are not viewing the latest documentation for Instance Manager. Visit https://docs.nginx.com/nginx-management-suite/nim to read the latest content.
This document explains how to use tagging with NGINX Instance Manager.
Tagging is a feature designed to help group a larger number of instances within NGINX Instance Manager. Tagging serves three purposes:
- Provide labeling 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 instance may contain more than one tag.
There are two methods to add a tag to an instance.
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.
You can also use the web interface to add tags to instances.
Select the instance row to open the slide-out panel.
Enter the tags you want to use or select an existing tag.
Select the “X” next to the tag to remove its association with an instance.
NGINX Instance Manager can use tags to copy an nginx configuration to multiple instances with the same tag in common.
Select the Tags button on the inventory page to use this function in the web interface. Then, in the panel that’s displayed, 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.