Skip to content

label: Global key-value labels for dynamic configuration

Installation

You can install this module in any RHEL-based distribution, including, but not limited to:

  • RedHat Enterprise Linux 7, 8, 9 and 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 and Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm 
dnf -y install nginx-module-label

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm 
yum -y install nginx-module-label

Enable the module by adding the following at the top of /etc/nginx/nginx.conf:

load_module modules/ngx_http_label_module.so;

This document describes nginx-module-label v0.1.0 released on Jan 06 2026.

Synopsis

http {
    label environment production;
    label cluster_id my_cluster_id;
    label server_region us-east-1;
    label server_id my_server_id;
    label ...

    server {
        listen 80;
        server_name example.com;
        location / {
            add_header Server-Id $label_server_id;
            add_header Cluster-Id $label_cluster_id;
            add_header All-Labels $labels;
            return 204;
        }
    }
}

Directives

label

Syntax: label key value;

Default: none

Context: http

Defines a global key-value label that can be accessed via variables. The label key is only allowed to be letters, numbers, and _. The same key cannot be defined repeatedly. The label value does not allow the use of & and =.

Example: 

label environment production;
label region us-east-1;

labels_hash_max_size

Syntax: labels_hash_max_size number;

Default: labels_hash_max_size 512;

Context: http

Sets the maximum size of the hash table for storing labels.

labels_hash_bucket_size

Syntax: labels_hash_bucket_size number;

Default: labels_hash_bucket_size 32|64|128;

Context: http

Sets the bucket size of the hash table for labels. Default value depends on the processor’s cache line size. The details of setting up hash tables are provided in a separate document.

Variables

$label_name

Accesses the value of a specific label by its key.

$labels

Returns all defined labels in the format key1=value1&key2=value2, like $args. All label keys will be printed in lowercase letters.

GitHub

You may find additional configuration tips and documentation for this module in the GitHub repository for nginx-module-label.