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

• ngx_http_label_module
• Name
• Table of Content
• Status
• Synopsis
• Installation
• Directives
• label
• labels_hash_max_size
• labels_hash_bucket_size
• Variables
• $label_name
• $labels
• Author
• License

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.