API unified registration module

The open source China community team made its first live broadcast, telling the story behind the open source China community in the name of sharing."

NGINX evolves to cloud native, All in OpenNJet

1.Demand

Control plane configuration With the increase of dynamic modules, each dynamic module (declarative API uses /config) originally provided a location configuration method. With more and more configuration items, it is necessary to provide a unified API module entrance, which is controlled by each dynamic module. The module registers with the api module, and at runtime calls the registered handler for processing according to the actual function request.

2. Existing dynamic api module

2.1 Existing API separate modules

njet-config-api-module
njet-http-sendmsg-module
njet-http-cache-quick-module
njet-health-check-helper
njet-http-dyn-server-api-module
njet-http-location-api-module
njet-http-range-api-module
njet-http-ssl-api-module
njet-http-upstream-api-module

2.2 Existing dynamic module configuration (declarative API and imperative API):

server {
        listen       8081;
        
         //声明式api入口
        location /config {
            config_api;
        }       

        location /hc {
            health_check_api;
        }

        //upstream api
        location /api {
             api write=on;
        }

        location /kv {
            dyn_sendmsg_kv;
        }

        location /ssl {
            dyn_ssl_api;
        }

        location /range {
            dyn_range_api;
        }

        location /cache {
            cache_quick_api;
        }

        location /dyn_loc {
           dyn_location_api;
        }

        location /dyn_srv {
           dyn_server_api;
        }
  }

3. Unified registration module solution

3.1 Unified configuration entrance (using /api)


    server {
        listen       8081;
        
         #api 统一入口
        location /api {
            dyn_module_api;         #用于解析设置clcf->handler为统一入口handler
            
            #权限校验
            api_limit_except  /v1/dyn_loc {method};
            api_limit_except  /v1/range {method};
        }
        
        location /doc {
            doc_api;
        }
    }

3.2 The api module provides registration interface

•The api module is compiled using static modules and initialized in the ctrl helper process

•api_module provides a registration interface similar to the kv module and saves the key and handler of each module.

• Each module registers the handler of each module according to /v{version}/{module_name} as the key. The first version is version 1. The registration key of each api module is as follows:

njet-config-api-module
    /v1/config

njet-http-sendmsg-module
    /v1/kv

njet-http-cache-quick-module
    /v1/cache

njet-health-check-helper
    /v1/hc

njet-http-dyn-server-api-module
    /v1/dyn_srv

njet-http-location-api-module
    /v1/dyn_loc

njet-http-range-api-module
   /v1/range

njet-http-ssl-api-module
   /v1/ssl

njet-http-upstream-api-module
   /v1/upstream_api

3.3 api module content processing stage process

• When the http request comes, the key (/v{version}/{module_name}) is parsed according to the url: /api/v{version}/{module_name}/{other}

•Check whether there is a registered handler based on the key, without returning 404 directly; if found, call the handler for processing

4. api_limit_except scheme

4.1 Introduction to limit_except directive


Syntax:	limit_except method…{…}
Default	-
Context:	location

Limits allowed HTTP methods inside a location. The method parameter can be one of the following: GET, HEAD, POST, PUT, DELETE, MKCOL, COPY, MOVE, OPTIONS, PROPFIND, PROPPATCH, LOCK, UNLOCK, or PATCH. Allowing the GET method makes the HEAD method also allowed. Access to other methods can be limited using the ngx_http_access_module, ngx_http_auth_basic_module, and ngx_http_auth_jwt_module (1.13.10) modules directives:

limit_except GET {
    allow 192.168.1.0/32;
    deny  all;
}

Please note that this will limit access to all methods except GET and HEAD.

4.2 api_limit_except instruction scheme

4.2.1 Requirements

Target:

•For api module, add api_limit_except directive (multiple can be configured to set restrictions for different api modules)

limit_except features:

•The limit_except directive can control permissions for the configured location. Each location function is configured with a limit_except. This directive will register a handler for permission verification in the access phase. Only after the verification is passed can the subsequent content processing phase be carried out.

•The limit_except directive will also generate a noname location structure in memory

Therefore, a new api_limit_except directive needs to be implemented to achieve two goals:

•Multiple items can be configured, and a limit_except can be configured for module URLs with different configurations

•The api location must be able to generate location structures that support multiple nonames in memory at the same time, and be able to call the correct limit_except configured permission access control based on the actual URL when there is an http request.

NOTES：

If limit_except is configured, double-layer verification will be performed. The rules are as follows:

•limit_except verification takes precedence

•limit_except If authentication is required, use password authentication with limit_except

•limit_except If allowed, it will enter the permission verification of api_limit_except configuration

4.2.2 Introduction to api_limit_except directive


Syntax:	api_limit_except module_key method…{…}
Default	-
Context:	location

Add a module_key parameter for limit_except. This parameter is the url prefix format of each api module: starting with /api/v{version}/{module_name}

声明式api 模块前缀： /api/v1/config

kv模块： /api/v1/kv

cache加速：/api/v1/cache

健康检查： /api/v1/hc

动态VS: /api/v1/dyn_srv

动态location: /api/v1/dyn_loc

动态range: /api/v1/range

动态ssl: /api/v1/ssl

动态upstream： /api/v1/upstream_api

4.2.3 Configuration example

•How to use htpasswd command:

centos：
yum install -y httpd

ubuntu:
apt install -y apache2-utils

密码文件/root/bug/njet1.0/htpasswd 新增用户test 密码是123456
htpasswd -bc /root/bug/njet1.0/htpasswd test 123456

密码文件/root/bug/njet1.0/htpasswd_ssl 新增用户test2 密码是test2
htpasswd -bc /root/bug/njet1.0/htpasswd_ssl test2 test2

 server {
       listen       8081;
       
        #api 统一入口
       location /api {
           dyn_module_api;
           
           #dyn_loc 权限校验， 非GET请求需要校验
           api_limit_except  /v1/ssl GET {
              auth_basic "OpenNJet SSL API";
              auth_basic_user_file /root/bug/njet1.0/htpasswd_ssl;
           }
           
           #range 权限校验， 非PUT请求需要校验
           api_limit_except  /v1/range PUT {
              auth_basic "OpenNJet RANGE API";
              auth_basic_user_file /root/bug/njet1.0/htpasswd;
           }
           
           #其他url请求，不做权限校验
       }
       
       location /doc {
           doc_api;
       }

       location /metrics {
           vhost_traffic_status_display;
           vhost_traffic_status_display_format html;
       }

       location /adc {
           #return 200 "ok";
           content_by_lua_file scripts/http_register.lua;
       }
   }

5. Test

The interface prefixes of all declarative APIs and imperative APIs are unified

5.1 ctrl configuration file

server {
    listen       8081;
    #api 统一入口
    location /api {
        dyn_module_api;
    }
    
    location /doc {
        doc_api;
    }
}

5.2 Module test (the function remains unchanged, the only change is the URL change of all api modules)

The interface prefix of all declarative APIs and imperative APIs is changed to start with /api/v{version}/{module_name}

声明式api 模块前缀： /api/v1/config
kv模块： /api/v1/kv
cache加速：/api/v1/cache
健康检查： /api/v1/hc
动态VS: /api/v1/dyn_srv
动态location: /api/v1/dyn_loc
动态range: /api/v1/range
动态ssl: /api/v1/ssl
动态upstream|： /api/v1/upstream_api

5.2.1 Dynamic ssl certificate:/api/v1/ssl

5.2.2 Health check: /api/v1/hc

5.2.3 Dynamic range: /api/v1/range

5.2.4 cache acceleration: /api/v1/cache

5.2.5 sq: /api/v1/sq

5.2.6 Config API: /api/v1/config

5.3 api_limit_except permission verification test

5.3.1 Example of generating verification password file:

centos：
yum install -y httpd

ubuntu:
apt install -y apache2-utils

密码文件/root/bug/njet1.0/htpasswd 新增用户test 密码是123456
htpasswd -bc /root/bug/njet1.0/htpasswd test 123456

密码文件/root/bug/njet1.0/htpasswd_ssl 新增用户test2 密码是test2
htpasswd -bc /root/bug/njet1.0/htpasswd_ssl test2 test2

5.3.2 Configuration (taking testing ssl and range as an example):

server {
        listen       8081;

        location /api {
            dyn_module_api;

            #针对 ssl 添加校验，用户名密码使用test2/test2
            api_limit_except  /v1/ssl GET {
               auth_basic "OpenNJet API";
               auth_basic_user_file /root/bug/njet1.0/htpasswd_ssl;
            }

            #针对 range 添加校验，用户名密码使用test/123456
            api_limit_except  /v1/range PUT {
               auth_basic "OpenNJet API";
               auth_basic_user_file /root/bug/njet1.0/htpasswd;
            }
            
            #如果同时配置了limit_except, 则优先判断limit_except权限配置，
            #如果limit_except 不检查，则会进入到api_limit_except 权限配置检查
            #limit_except GET{
            #   auth_basic "OpenNJet API";
            #   auth_basic_user_file /root/bug/njet1.0/htpasswd;
            #}
        }
   }

5.3.3 Test:

5.3.3.1 SSL verification test

For ssl, the GET method does not verify, other methods verify, so calling the get interface will not allow you to enter the password, calling the put interface will allow you to enter the password. Only test2/test2 with the correct password will pass.

5.3.3.1.1 Get test: Return the result directly

5.3.3.1.2 PUT test: You need to enter a password. The result will be returned after the password is correct.

Enter the correct password and enter the content processing stage.

5.3.3.2 range verification test

For range, the PUT method does not verify, other methods verify, so calling the put interface will not allow the password to be entered, calling the get interface will require the password to be entered. Only test/123456 with the correct password will pass.

5.3.3.2.1 GET test: Password required

GET requires the password test/123456

Enter the correct password and return the result

5.3.3.2.2 PUT test: No need to enter a password, go directly to the content processing stage

The NJet application engine achieves unique runtime dynamic configuration loading capabilities through kernel reconstruction and is a new generation of high-performance Web application engine . NJet has high-performance data plane processing capabilities and schedules multiple auxiliary functions such as clustering, high availability, active health checks, and declarative APIs through NJet's unique co-pilot CoPilot service framework to facilitate function expansion and isolate management/control function pairs. Due to the impact on the data plane, the performance of the NJet application engine exceeds three times that of the Envoy application engine recommended by CNCF. Mail group official website