Module ngx_http_api_module (original) (raw)

The ngx_http_api_module module (1.13.3) provides REST API for accessing various status information, configuring upstream server groups on-the-fly, and managingkey-value pairswithout the need of reconfiguring nginx.

The module supersedes thengx_http_status_module andngx_http_upstream_conf_modulemodules.

When using the PATCH or POST methods, make sure that the payload does not exceed thebuffer sizefor reading the client request body, otherwise, the 413 (Request Entity Too Large) error may be returned.

This module is available as part of ourcommercial subscription.

Example Configuration

http { upstream backend { zone http_backend 64k;

   server backend1.example.com weight=5;
   server backend2.example.com;

}

proxy_cache_path /data/nginx/cache_backend keys_zone=cache_backend:10m;

server { server_name backend.example.com;

   location / {
       proxy_pass  http://backend;
       proxy_cache cache_backend;

       health_check;
   }

   status_zone server_backend;

}

keyval_zone zone=one:32k state=one.keyval; keyval argtextarg_text argtexttext zone=one;

server { listen 127.0.0.1;

   location /api {
       **api** write=on;
       allow 127.0.0.1;
       deny all;
   }

} }

stream { upstream backend { zone stream_backend 64k;

   server backend1.example.com:12345 weight=5;
   server backend2.example.com:12345;

}

server { listen 127.0.0.1:12345; proxy_pass backend; status_zone server_backend; health_check; } }

All API requests include a supported API version in the URI. Examples of API requests with this configuration:

http://127.0.0.1/api/9/ http://127.0.0.1/api/9/nginx http://127.0.0.1/api/9/connections http://127.0.0.1/api/9/workers http://127.0.0.1/api/9/http/requests http://127.0.0.1/api/9/http/server_zones/server_backend http://127.0.0.1/api/9/http/caches/cache_backend http://127.0.0.1/api/9/http/upstreams/backend http://127.0.0.1/api/9/http/upstreams/backend/servers/ http://127.0.0.1/api/9/http/upstreams/backend/servers/1 http://127.0.0.1/api/9/http/keyvals/one?key=arg1 http://127.0.0.1/api/9/stream/ http://127.0.0.1/api/9/stream/server_zones/server_backend http://127.0.0.1/api/9/stream/upstreams/ http://127.0.0.1/api/9/stream/upstreams/backend http://127.0.0.1/api/9/stream/upstreams/backend/servers/1

Directives

Syntax: api[write=on|off];
Default:
Context: location

Turns on the REST API interface in the surrounding location. Access to this location should belimited.

The write parameter determines whether the API is read-only or read-write. By default, the API is read-only.

All API requests should contain a supported API version in the URI. If the request URI equals the location prefix, the list of supported API versions is returned. The current API version is “9”.

The optional “fields” argument in the request line specifies which fields of the requested objects will be output:

http://127.0.0.1/api/9/nginx?fields=version,build

Syntax: status_zone zone;
Default:
Context: server, location, if in location

This directive appeared in version 1.13.12.

Enables collection of virtualhttporstreamserver status information in the specified _zone_. Several servers may share the same zone.

Starting from 1.17.0, status information can be collected per location. The special value off disables statistics collection in nested location blocks. Note that the statistics is collected in the context of a location where processing ends. It may be different from the original location, if aninternal redirect happens during request processing.

Compatibility

Endpoints

/

Supported methods:

/nginx

Supported methods:

/processes

Supported methods:

/connections

Supported methods:

/slabs/

Supported methods:

/slabs/{slabZoneName}

Parameters common for all methods:

slabZoneName(string, required)

The name of the shared memory zone with slab allocator.

Supported methods:

/http/

Supported methods:

/http/requests

Supported methods:

/http/server_zones/

Supported methods:

/http/server_zones/{httpServerZoneName}

Parameters common for all methods:

httpServerZoneName(string, required)

The name of an HTTP server zone.

Supported methods:

/http/location_zones/

Supported methods:

/http/location_zones/{httpLocationZoneName}

Parameters common for all methods:

httpLocationZoneName(string, required)

The name of an HTTP location zone.

Supported methods:

/http/caches/

Supported methods:

/http/caches/{httpCacheZoneName}

Parameters common for all methods:

httpCacheZoneName(string, required)

The name of the cache zone.

Supported methods:

/http/limit_conns/

Supported methods:

/http/limit_conns/{httpLimitConnZoneName}

Parameters common for all methods:

httpLimitConnZoneName(string, required)

The name of a limit_conn zone.

Supported methods:

/http/limit_reqs/

Supported methods:

/http/limit_reqs/{httpLimitReqZoneName}

Parameters common for all methods:

httpLimitReqZoneName(string, required)

The name of a limit_req zone.

Supported methods:

/http/upstreams/

Supported methods:

/http/upstreams/{httpUpstreamName}/

Parameters common for all methods:

httpUpstreamName(string, required)

The name of an HTTP upstream server group.

Supported methods:

/http/upstreams/{httpUpstreamName}/servers/

Parameters common for all methods:

httpUpstreamName(string, required)

The name of an upstream server group.

Supported methods:

/http/upstreams/{httpUpstreamName}/servers/{httpUpstreamServerId}

Parameters common for all methods:

httpUpstreamName(string, required)

The name of the upstream server group.

httpUpstreamServerId(string, required)

The ID of the server.

Supported methods:

/http/keyvals/

Supported methods:

/http/keyvals/{httpKeyvalZoneName}

Parameters common for all methods:

httpKeyvalZoneName(string, required)

The name of an HTTP keyval shared memory zone.

Supported methods:

/stream/

Supported methods:

/stream/server_zones/

Supported methods:

/stream/server_zones/{streamServerZoneName}

Parameters common for all methods:

streamServerZoneName(string, required)

The name of a stream server zone.

Supported methods:

/stream/limit_conns/

Supported methods:

/stream/limit_conns/{streamLimitConnZoneName}

Parameters common for all methods:

streamLimitConnZoneName(string, required)

The name of a limit_conn zone.

Supported methods:

/stream/upstreams/

Supported methods:

/stream/upstreams/{streamUpstreamName}/

Parameters common for all methods:

streamUpstreamName(string, required)

The name of a stream upstream server group.

Supported methods:

/stream/upstreams/{streamUpstreamName}/servers/

Parameters common for all methods:

streamUpstreamName(string, required)

The name of an upstream server group.

Supported methods:

/stream/upstreams/{streamUpstreamName}/servers/{streamUpstreamServerId}

Parameters common for all methods:

streamUpstreamName(string, required)

The name of the upstream server group.

streamUpstreamServerId(string, required)

The ID of the server.

Supported methods:

/stream/keyvals/

Supported methods:

/stream/keyvals/{streamKeyvalZoneName}

Parameters common for all methods:

streamKeyvalZoneName(string, required)

The name of a stream keyval shared memory zone.

Supported methods:

/stream/zone_sync/

Supported methods:

/resolvers/

Supported methods:

/resolvers/{resolverZoneName}

Parameters common for all methods:

resolverZoneName(string, required)

The name of a resolver zone.

Supported methods:

/ssl

Supported methods:

/license

Supported methods:

/workers/

Supported methods:

/workers/{workerId}

Parameters common for all methods:

workerId(string, required)

The ID of the worker process.

Supported methods:

Response Objects

 "free" : 0,  
 "reqs" : 0,  
 "fails" : 0  

},
"16" : {
"used" : 0,
"free" : 0,
"reqs" : 0,
"fails" : 0
},
"32" : {
"used" : 0,
"free" : 0,
"reqs" : 0,
"fails" : 0
},
"64" : {
"used" : 1,
"free" : 63,
"reqs" : 1,
"fails" : 0
},
"128" : {
"used" : 0,
"free" : 0,
"reqs" : 0,
"fails" : 0
},
"256" : {
"used" : 18078,
"free" : 178,
"reqs" : 1635736,
"fails" : 0
}
}
}

 "301" : 4522,  
 "404" : 907,  
 "503" : 266  

},
"total" : 705177
},
"discarded" : 1513,
"received" : 172711587,
"sent" : 19415530115,
"ssl" : {
"handshakes" : 104303,
"handshakes_failed" : 1421,
"session_reuses" : 54645,
"no_common_protocol" : 4,
"no_common_cipher" : 2,
"handshake_timeout" : 0,
"peer_rejected_cert" : 0,
"verify_failures" : {
"no_cert" : 0,
"expired_cert" : 2,
"revoked_cert" : 1,
"other" : 1
}
}
}

 "301" : 4522,  
 "404" : 2504,  
 "503" : 266  

},
"total" : 705177
},
"discarded" : 1513,
"received" : 172711587,
"sent" : 19415530115
}

   "id" : 0,  
   "server" : "10.0.0.1:8088",  
   "name" : "10.0.0.1:8088",  
   "backup" : false,  
   "weight" : 5,  
   "state" : "up",  
   "active" : 0,  
   "ssl" : {  
     "handshakes" : 620311,  
     "handshakes_failed" : 3432,  
     "session_reuses" : 36442,  
     "no_common_protocol" : 4,  
     "handshake_timeout" : 0,  
     "peer_rejected_cert" : 0,  
     "verify_failures" : {  
       "expired_cert" : 2,  
       "revoked_cert" : 1,  
       "hostname_mismatch" : 2,  
       "other" : 1  
     }  
   },  
   "max_conns" : 20,  
   "requests" : 667231,  
   "header_time" : 20,  
   "response_time" : 36,  
   "responses" : {  
     "1xx" : 0,  
     "2xx" : 666310,  
     "3xx" : 0,  
     "4xx" : 915,  
     "5xx" : 6,  
     "codes" : {  
       "200" : 666310,  
       "404" : 915,  
       "503" : 6  
     },  
     "total" : 667231  
   },  
   "sent" : 251946292,  
   "received" : 19222475454,  
   "fails" : 0,  
   "unavail" : 0,  
   "health_checks" : {  
     "checks" : 26214,  
     "fails" : 0,  
     "unhealthy" : 0,  
     "last_passed" : true  
   },  
   "downtime" : 0,  
   "downstart" : "2022-06-28T11:09:21.602Z",  
   "selected" : "2022-06-28T15:01:25.000Z"  
 },  
 {  
   "id" : 1,  
   "server" : "10.0.0.1:8089",  
   "name" : "10.0.0.1:8089",  
   "backup" : true,  
   "weight" : 1,  
   "state" : "unhealthy",  
   "active" : 0,  
   "max_conns" : 20,  
   "requests" : 0,  
   "responses" : {  
     "1xx" : 0,  
     "2xx" : 0,  
     "3xx" : 0,  
     "4xx" : 0,  
     "5xx" : 0,  
     "codes" : {  
     },  
     "total" : 0  
   },  
   "sent" : 0,  
   "received" : 0,  
   "fails" : 0,  
   "unavail" : 0,  
   "health_checks" : {  
     "checks" : 26284,  
     "fails" : 26284,  
     "unhealthy" : 1,  
     "last_passed" : false  
   },  
   "downtime" : 262925617,  
   "downstart" : "2022-06-28T11:09:21.602Z",  
   "selected" : "2022-06-28T15:01:25.000Z"  
 }  

],
"keepalive" : 0,
"zombies" : 0,
"zone" : "upstream_backend"
}
}

 "4xx" : 0,  
 "5xx" : 0,  
 "total" : 155569  

},
"discarded" : 0,
"received" : 4200363,
"sent" : 20489184,
"ssl" : {
"handshakes" : 76455,
"handshakes_failed" : 432,
"session_reuses" : 28770,
"no_common_protocol" : 4,
"no_common_cipher" : 2,
"handshake_timeout" : 0,
"peer_rejected_cert" : 0,
"verify_failures" : {
"no_cert" : 0,
"expired_cert" : 2,
"revoked_cert" : 1,
"other" : 1
}
}
}
}

   "id" : 0,  
   "server" : "10.0.0.1:12347",  
   "name" : "10.0.0.1:12347",  
   "backup" : false,  
   "weight" : 5,  
   "state" : "up",  
   "active" : 0,  
   "ssl" : {  
     "handshakes" : 200,  
     "handshakes_failed" : 4,  
     "session_reuses" : 189,  
     "no_common_protocol" : 4,  
     "handshake_timeout" : 0,  
     "peer_rejected_cert" : 0,  
     "verify_failures" : {  
       "expired_cert" : 2,  
       "revoked_cert" : 1,  
       "hostname_mismatch" : 2,  
       "other" : 1  
     }  
   },  
   "max_conns" : 50,  
   "connections" : 667231,  
   "sent" : 251946292,  
   "received" : 19222475454,  
   "fails" : 0,  
   "unavail" : 0,  
   "health_checks" : {  
     "checks" : 26214,  
     "fails" : 0,  
     "unhealthy" : 0,  
     "last_passed" : true  
   },  
   "downtime" : 0,  
   "downstart" : "2022-06-28T11:09:21.602Z",  
   "selected" : "2022-06-28T15:01:25.000Z"  
 },  
 {  
   "id" : 1,  
   "server" : "10.0.0.1:12348",  
   "name" : "10.0.0.1:12348",  
   "backup" : true,  
   "weight" : 1,  
   "state" : "unhealthy",  
   "active" : 0,  
   "max_conns" : 50,  
   "connections" : 0,  
   "sent" : 0,  
   "received" : 0,  
   "fails" : 0,  
   "unavail" : 0,  
   "health_checks" : {  
     "checks" : 26284,  
     "fails" : 26284,  
     "unhealthy" : 1,  
     "last_passed" : false  
   },  
   "downtime" : 262925617,  
   "downstart" : "2022-06-28T11:09:21.602Z",  
   "selected" : "2022-06-28T15:01:25.000Z"  
 }  

],
"zombies" : 0,
"zone" : "dns"
}
}

 "records_total" : 260575  

},
"zone2" : {
"records_pending" : 0,
"records_total" : 14749
}
},
"status" : {
"bytes_in" : 1364923761,
"msgs_in" : 337236,
"msgs_out" : 346717,
"bytes_out" : 1402765472,
"nodes_online" : 15
}
}

 "srv" : 130,  
 "addr" : 2580  

},
"responses" : {
"noerror" : 26499,
"formerr" : 0,
"servfail" : 3,
"nxdomain" : 0,
"notimp" : 0,
"refused" : 0,
"timedout" : 243,
"unknown" : 478
}
}
}

 "current" : 1  

}
}
}