set $backend "app_a";
if ($http_x_canary = "1") {
    set $backend "app_b";
}
proxy_pass http://$backend;

Directive defines behavior.
Variable supplies request-specific values to that behavior.
map/geo defines lookup tables that produce variables.
Evaluation happens when a module/directive needs the value, not because the file is read top-to-bottom like code.

1. Parse time       : ketika nginx membaca config.
2. Reload time      : ketika config baru divalidasi dan worker baru dibuat.
3. Request time     : ketika request tertentu diproses worker.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    location /ws/ {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_pass http://websocket_backend;
    }
}

Variable name alone does not tell you whether the value is trustworthy.
You must know who supplied it, when it is evaluated, and whether it was normalized.

GET /a/../b/%63?id=1 HTTP/1.1

$request_uri  ≈ /a/../b/%63?id=1
$uri          ≈ /b/c
$args         ≈ id=1

# Jangan bangun filesystem path dari request_uri mentah.
try_files $request_uri =404;

proxy_set_header Host $host;

proxy_set_header Host $http_host;

proxy_cache_key "$scheme$host$request_uri";

map $host $tenant_id {
    default "";
    app-a.example.com app_a;
    app-b.example.com app_b;
}

server {
    if ($tenant_id = "") { return 444; }
    proxy_set_header X-Tenant-Id $tenant_id;
    proxy_pass http://tenant_router;
}

Header: X-Request-Id
Variable: $http_x_request_id

proxy_set_header X-Request-Id $http_x_request_id;

map $http_x_request_id $req_id {
    default $http_x_request_id;
    ""      $request_id;
}

proxy_set_header X-Request-Id $req_id;

proxy_set_header X-Request-Id $request_id;
proxy_set_header X-External-Request-Id $http_x_request_id;

map $source $target {
    default value_default;
    key1    value1;
    key2    value2;
}

map $http_upgrade $connection_upgrade {
    default upgrade;
    ""      close;
}

$connection_upgrade = upgrade

$connection_upgrade = close

map didefinisikan di context http.
map menghasilkan variable.
variable map dievaluasi ketika digunakan.
Deklarasi banyak map tidak otomatis menambah biaya request jika variablenya tidak dipakai.

set $cache_bypass 0;

if ($request_method = POST) {
    set $cache_bypass 1;
}

if ($http_authorization != "") {
    set $cache_bypass 1;
}

map $request_method $bypass_by_method {
    default 0;
    POST    1;
    PUT     1;
    PATCH   1;
    DELETE  1;
}

map $http_authorization $bypass_by_auth {
    default 1;
    ""      0;
}

map "$bypass_by_method:$bypass_by_auth" $cache_bypass {
    default 1;
    "0:0"   0;
}

proxy_cache_bypass $cache_bypass;
proxy_no_cache     $cache_bypass;

map $host $tenant {
    hostnames;

    default             "";
    example.com         main;
    api.example.com     api;
    *.internal.example.com internal;
    ~^(.+)\.customer\.example\.com$ customer_$1;
}

Letakkan exact key untuk domain penting.
Letakkan regex hanya setelah exact/wildcard yang lebih jelas.
Jangan biarkan default diam-diam mengarah ke tenant valid.

map $host $tenant {
    hostnames;
    default "";
    app-a.example.com app_a;
    app-b.example.com app_b;
}

server {
    if ($tenant = "") { return 444; }
    proxy_set_header X-Tenant $tenant;
    proxy_pass http://tenant_router;
}

map $host $tenant {
    default app_a;
    app-b.example.com app_b;
}

map $host $customer_slug {
    default "";
    ~^(?<slug>[a-z0-9-]+)\.customer\.example\.com$ $slug;
}

proxy_set_header X-Customer-Slug $customer_slug;

~^(?<slug>[a-z0-9][a-z0-9-]{0,62})\.customer\.example\.com$ $slug;

~^(.+)\.customer\.example\.com$ $1;

Regex map yang menghasilkan identifier internal harus sekaligus melakukan validation.

map $http_authorization $has_auth {
    default 1;
    ""      0;
}

"" 0;

null 0;

map "$request_method:$http_authorization" $cache_policy {
    default bypass;
    "GET:"  cache;
    "HEAD:" cache;
}

map $uri $route_class {
    volatile;
    default other;
    ~^/api/ api;
}

Default: map biasa.
Gunakan volatile hanya jika kamu dapat menjelaskan variable mana yang berubah, kapan berubah, dan directive mana yang membaca hasilnya.

geo $client_region {
    default ZZ;
    10.0.0.0/8 PRIVATE;
    192.168.0.0/16 PRIVATE;
    203.0.113.0/24 ID_TEST;
}

geo $arg_remote_addr $geo_from_arg {
    default 0;
    203.0.113.0/24 1;
}

Client -> CDN/LB -> NGINX
                 remote_addr = IP CDN/LB

set_real_ip_from 10.0.0.0/8;
real_ip_header X-Forwarded-For;
real_ip_recursive on;

geo $trusted_network {
    default 0;
    10.0.0.0/8 1;
    192.168.0.0/16 1;
}

geo is only as correct as the source IP variable it reads.

geo $is_private_network {
    default 0;
    10.0.0.0/8 1;
    172.16.0.0/12 1;
    192.168.0.0/16 1;
}

map "$is_private_network:$uri" $admin_policy {
    default deny;
    ~^1:/admin(?:/|$) allow;
}

server {
    location /admin/ {
        if ($admin_policy = deny) { return 403; }
        proxy_pass http://admin_app;
    }
}

geo classifies network.
map combines classifications into policy.
directive enforces policy.

proxy_set_header X-Request-Id $request_id;
add_header X-Cache-Status $upstream_cache_status always;
proxy_cache_key "$scheme$host$request_uri";
access_log /var/log/nginx/access.log main if=$loggable;

proxy_pass http://$backend;

Variable in a directive is not just string interpolation.
It may change module behavior.

set $app_env production;
proxy_set_header X-App-Env $app_env;

set $route app;

if ($http_x_admin = 1) {
    set $route admin;
}

if ($arg_debug = 1) {
    set $route debug;
}

proxy_pass http://$route;

map "$http_x_admin:$arg_debug" $route {
    default app;
    "1:"   admin;
    ":1"   debug;
}

`if` di context location bukan general-purpose control flow.
Gunakan untuk hal sederhana seperti `return`/`rewrite` yang dipahami efeknya.
Untuk decision table, gunakan `map`.

if ($host = "") { return 444; }
if ($request_method !~ ^(GET|HEAD|POST)$) { return 405; }

if ($condition) {
    proxy_pass http://a;
}

map $request_method $method_allowed {
    default 0;
    GET 1;
    HEAD 1;
    POST 1;
}

server {
    if ($method_allowed = 0) { return 405; }

    location / {
        proxy_pass http://app;
    }
}

log_format edge_json escape=json
  '{'
  '"time":"$time_iso8601",'
  '"request_id":"$request_id",'
  '"remote_addr":"$remote_addr",'
  '"host":"$host",'
  '"method":"$request_method",'
  '"uri":"$uri",'
  '"request_uri":"$request_uri",'
  '"tenant":"$tenant",'
  '"cache_bypass":"$cache_bypass",'
  '"status":$status,'
  '"upstream_status":"$upstream_status",'
  '"request_time":$request_time,'
  '"upstream_response_time":"$upstream_response_time"'
  '}';

access_log /var/log/nginx/edge.log edge_json;

Any variable that changes routing, caching, access, or rate limiting should be observable.

map $uri $loggable_uri {
    default 1;
    /healthz 0;
    /readyz 0;
}

map $status $loggable_status {
    default 1;
    204 0;
}

map "$loggable_uri:$loggable_status" $loggable {
    default 1;
    "0:0" 0;
}

access_log /var/log/nginx/access.log main if=$loggable;

proxy_cache_key "$scheme:$host:$request_uri";

map $http_authorization $has_auth {
    default 1;
    "" 0;
}

map $request_method $unsafe_method {
    default 1;
    GET 0;
    HEAD 0;
}

map "$has_auth:$unsafe_method" $cache_bypass {
    default 1;
    "0:0" 0;
}

proxy_cache_bypass $cache_bypass;
proxy_no_cache     $cache_bypass;

limit_req_zone $binary_remote_addr zone=per_ip:10m rate=10r/s;

map $host $tenant {
    default "unknown";
    api-a.example.com a;
    api-b.example.com b;
}

limit_req_zone $tenant zone=per_tenant:10m rate=100r/s;

limit_req_zone "$tenant:$binary_remote_addr" zone=per_tenant_ip:20m rate=10r/s;

Who pays for this request?
Who can abuse this endpoint?
Which identity is stable enough to be a key?

map $http_x_canary $backend_pool {
    default app_stable;
    "1"     app_canary;
}

upstream app_stable { server stable:8080; }
upstream app_canary { server canary:8080; }

server {
    location / {
        proxy_pass http://$backend_pool;
    }
}

location / {
    error_page 418 = @canary;

    if ($http_x_canary = "1") { return 418; }

    proxy_pass http://app_stable;
}

location @canary {
    proxy_pass http://app_canary;
}

Canary routing must be easy to observe, easy to disable, and safe under partial failure.

location ~ ^/users/(\d+)/orders/(\d+)$ {
    proxy_set_header X-User-Id $1;
    proxy_set_header X-Order-Id $2;
    proxy_pass http://orders;
}

location ~ ^/users/(?<user_id>\d+)/orders/(?<order_id>\d+)$ {
    proxy_set_header X-User-Id $user_id;
    proxy_set_header X-Order-Id $order_id;
    proxy_pass http://orders;
}

map $host $known_host {
    hostnames;
    default 0;
    app.example.com 1;
    api.example.com 1;
    admin.example.com 1;
}

server {
    listen 443 ssl http2 default_server;
    server_name _;
    return 444;
}

server {
    listen 443 ssl http2;
    server_name app.example.com api.example.com admin.example.com;

    if ($known_host = 0) { return 444; }

    location / {
        proxy_pass http://app;
    }
}

server_name selects virtual server.
map validates/classifies host within policy.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ""      close;
}

server {
    location /ws/ {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_pass http://ws_backend;
    }
}

proxy_set_header Connection "upgrade";

map $request_method $method_allowed {
    default 0;
    GET     1;
    HEAD    1;
    POST    1;
}

server {
    if ($method_allowed = 0) {
        return 405;
    }

    location / {
        proxy_pass http://app;
    }
}

location ^~ /public/ {
    limit_except GET HEAD { deny all; }
    proxy_pass http://public_api;
}

location ^~ /commands/ {
    proxy_pass http://command_api;
}

map $host $backend {
    api.example.com api_backend;
}

location / {
    proxy_pass http://$backend;
}

map $host $backend {
    default "";
    api.example.com api_backend;
}

server {
    if ($backend = "") { return 444; }

    location / {
        proxy_pass http://$backend;
    }
}

map $host $tenant {
    default "";
    ~^(.+)\.example\.com$ $1;
}

admin.example.com
www.example.com
evil..example.com? tergantung Host normalization
unicode/punycode edge cases

map $host $tenant {
    default "";
    customer-a.example.com customer_a;
    customer-b.example.com customer_b;
}

map $host $tenant_slug {
    default "";
    ~^(?<slug>[a-z0-9][a-z0-9-]{2,40})\.customer\.example\.com$ $slug;
}

map $uri $route_class {
    default web;
    ~^/api/ api;
}

Choose variable source based on invariant:
- original request target?
- normalized current URI?
- selected host?
- trusted client identity?
- upstream result?

location = /__debug/vars {
    default_type application/json;
    return 200 '{
      "host":"$host",
      "http_host":"$http_host",
      "server_name":"$server_name",
      "uri":"$uri",
      "request_uri":"$request_uri",
      "tenant":"$tenant",
      "cache_bypass":"$cache_bypass",
      "remote_addr":"$remote_addr"
    }';
}

curl -sk https://app.example.test/__debug/vars \
  -H 'Host: app.example.com'

curl -sk 'https://app.example.test/__debug/vars?x=1' \
  -H 'Host: unknown.example.com'

curl -sk https://app.example.test/api/users \
  -H 'Authorization: Bearer test'

Every derived variable should have:
- source variable;
- valid values;
- default behavior;
- consumer directive;
- log visibility;
- test cases.

[ ] Setiap `map` punya `default` eksplisit.
[ ] Default untuk security/tenant/routing tidak mengarah ke resource valid tanpa sengaja.
[ ] Header client mentah `$http_*` tidak dipercaya tanpa validasi.
[ ] `$host`, `$http_host`, dan `$server_name` digunakan sesuai makna.
[ ] `$uri` dan `$request_uri` tidak tertukar.
[ ] Query arg memakai `$arg_name`, bukan location matching.
[ ] `geo` membaca IP yang benar setelah realip chain dipahami.
[ ] `map` dipakai untuk decision table, bukan banyak `if + set`.
[ ] Regex map di-anchor dan membatasi karakter output.
[ ] Variable yang memengaruhi routing/cache/security/rate limit dilog.
[ ] Dynamic `proxy_pass` dengan variable dihindari kecuali resolver/semantiknya dipahami.
[ ] Variable source dipilih berdasarkan invariant: original URI, normalized URI, host, IP, header, atau upstream result.
[ ] Debug endpoint/header hanya ada di environment aman.

NGINX variables are request-time values, not ordinary program variables.
map and geo are declarative lookup tables.
Evaluation happens when values are used.
The source variable determines trust and timing.
The consumer directive determines operational meaning.

source -> classification -> derived variable -> enforcement directive -> log evidence