Skip to content

label: Global key-value labels for dynamic configuration

Debian/Ubuntu installation

These docs apply to the APT package nginx-module-label provided by the GetPageSpeed Extras repository.

  1. Configure the APT repository as described in APT repository setup.
  2. Install the module:
sudo apt-get update
sudo apt-get install nginx-module-label
Show suites and architectures 
| Distro   | Suite             | Component   | Architectures   |
|----------|-------------------|-------------|-----------------|
| debian   | bookworm          | main        | amd64, arm64    |
| debian   | bookworm-mainline | main        | amd64, arm64    |
| debian   | trixie            | main        | amd64, arm64    |
| debian   | trixie-mainline   | main        | amd64, arm64    |
| ubuntu   | focal             | main        | amd64, arm64    |
| ubuntu   | focal-mainline    | main        | amd64, arm64    |
| ubuntu   | jammy             | main        | amd64, arm64    |
| ubuntu   | jammy-mainline    | main        | amd64, arm64    |
| ubuntu   | noble             | main        | amd64, arm64    |
| ubuntu   | noble-mainline    | main        | amd64, arm64    |

Name

ngx_http_label_module allows defining global key-value labels in Nginx configuration. These labels can be used in variables for request processing, logging, or dynamic configuration.

Table of Content

Status

This Nginx module is currently considered experimental. Issues and PRs are welcome if you encounter any problems.

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.