feat(plugin): azure serverless functions (#5479)

Co-authored-by: 罗泽轩 <spacewanderlzx@gmail.com>

apisix/plugins/azure-functions.lua

@@ -0,0 +1,137 @@
+--
+-- Licensed to the Apache Software Foundation (ASF) under one or more
+-- contributor license agreements.  See the NOTICE file distributed with
+-- this work for additional information regarding copyright ownership.
+-- The ASF licenses this file to You under the Apache License, Version 2.0
+-- (the "License"); you may not use this file except in compliance with
+-- the License.  You may obtain a copy of the License at
+--
+--     http://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS,
+-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+-- See the License for the specific language governing permissions and
+-- limitations under the License.
+
+local core = require("apisix.core")
+local http = require("resty.http")
+local plugin = require("apisix.plugin")
+local ngx  = ngx
+local plugin_name = "azure-functions"
+
+local schema = {
+    type = "object",
+    properties = {
+        function_uri = {type = "string"},
+        authorization = {
+            type = "object",
+            properties = {
+                apikey = {type = "string"},
+                clientid = {type = "string"}
+            }
+        },
+        timeout = {type = "integer", minimum = 100, default = 3000},
+        ssl_verify = {type = "boolean", default = true},
+        keepalive = {type = "boolean", default = true},
+        keepalive_timeout = {type = "integer", minimum = 1000, default = 60000},
+        keepalive_pool = {type = "integer", minimum = 1, default = 5}
+    },
+    required = {"function_uri"}
+}
+
+local metadata_schema = {
+    type = "object",
+    properties = {
+        master_apikey = {type = "string", default = ""},
+        master_clientid = {type = "string", default = ""}
+    }
+}
+
+local _M = {
+    version = 0.1,
+    priority = -1900,
+    name = plugin_name,
+    schema = schema,
+    metadata_schema = metadata_schema
+}
+
+function _M.check_schema(conf, schema_type)
+    if schema_type == core.schema.TYPE_METADATA then
+        return core.schema.check(metadata_schema, conf)
+    end
+    return core.schema.check(schema, conf)
+end
+
+function _M.access(conf, ctx)
+    local uri_args = core.request.get_uri_args(ctx)
+    local headers = core.request.headers(ctx) or {}
+    local req_body, err = core.request.get_body()
+
+    if err then
+        core.log.error("error while reading request body: ", err)
+        return 400
+    end
+
+    -- set authorization headers if not already set by the client
+    -- we are following not to overwrite the authz keys
+    if not headers["x-functions-key"] and
+            not headers["x-functions-clientid"] then
+        if conf.authorization then
+            headers["x-functions-key"] = conf.authorization.apikey
+            headers["x-functions-clientid"] = conf.authorization.clientid
+        else
+            -- If neither api keys are set with the client request nor inside the plugin attributes
+            -- plugin will fallback to the master key (if any) present inside the metadata.
+            local metadata = plugin.plugin_metadata(plugin_name)
+            if metadata then
+                headers["x-functions-key"] = metadata.value.master_apikey
+                headers["x-functions-clientid"] = metadata.value.master_clientid
+            end
+        end
+    end
+
+    headers["host"] = nil
+    local params = {
+        method = ngx.req.get_method(),
+        body = req_body,
+        query = uri_args,
+        headers = headers,
+        keepalive = conf.keepalive,
+        ssl_verify = conf.ssl_verify
+    }
+
+    -- Keepalive options
+    if conf.keepalive then
+        params.keepalive_timeout = conf.keepalive_timeout
+        params.keepalive_pool = conf.keepalive_pool
+    end
+
+    local httpc = http.new()
+    httpc:set_timeout(conf.timeout)
+
+    local res, err = httpc:request_uri(conf.function_uri, params)
+
+    if not res or err then
+        core.log.error("failed to process azure function, err: ", err)
+        return 503
+    end
+
+    -- According to RFC7540 https://datatracker.ietf.org/doc/html/rfc7540#section-8.1.2.2, endpoint
+    -- must not generate any connection specific headers for HTTP/2 requests.
+    local response_headers = res.headers
+    if ngx.var.http2 then
+        response_headers["Connection"] = nil
+        response_headers["Keep-Alive"] = nil
+        response_headers["Proxy-Connection"] = nil
+        response_headers["Upgrade"] = nil
+        response_headers["Transfer-Encoding"] = nil
+    end
+
+    -- setting response headers
+    core.response.set_header(response_headers)
+
+    return res.status, res.body
+end
+
+return _M

conf/config-default.yaml

@@ -354,6 +354,7 @@ plugins:                          # plugin list (sorted by priority)
   # <- recommend to use priority (0, 100) for your custom plugins
   - example-plugin                 # priority: 0
   #- skywalking                    # priority: -1100
+  - azure-functions                # priority: -1900
   - serverless-post-function       # priority: -2000
   - ext-plugin-post-req            # priority: -3000
 

docs/en/latest/config.json

@@ -127,7 +127,8 @@
           "type": "category",
           "label": "Serverless",
           "items": [
-            "plugins/serverless"
+            "plugins/serverless",
+            "plugins/azure-functions"
           ]
         },
         {

docs/en/latest/plugins/azure-functions.md

@@ -0,0 +1,140 @@
+---
+title: azure-functions
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## Summary
+
+- [Summary](#summary)
+- [Name](#name)
+- [Attributes](#attributes)
+- [Metadata](#metadata)
+- [How To Enable](#how-to-enable)
+- [Disable Plugin](#disable-plugin)
+
+## Name
+
+`azure-functions` is a serverless plugin built into Apache APISIX for seamless integration with [Azure Serverless Function](https://azure.microsoft.com/en-in/services/functions/) as a dynamic upstream to proxy all requests for a particular URI to the Microsoft Azure cloud, one of the most used public cloud platforms for production environment. If enabled, this plugin terminates the ongoing request to that particular URI and initiates a new request to the azure faas (the new upstream) on behalf of the client with the suitable authorization details set by the users, request headers, request body, params ( all these three components are passed from the original request ) and returns the response body, status code and the headers back to the original client that has invoked the request to the APISIX agent.
+
+## Attributes
+
+| Name             | Type   | Requirement  | Default      | Valid       | Description                                                                                |
+| -----------      | ------ | -----------  | -------      | -----       | ------------------------------------------------------------                               |
+| function_uri      | string | required    |          |   | The azure function endpoint which triggers the serverless function code (eg. http://test-apisix.azurewebsites.net/api/HttpTrigger).   |
+| authorization   | object | optional    |         |     |  Authorization credentials to access the cloud function.                                                             |
+| authorization.apikey | string | optional    |             |     | Field inside _authorization_. The generate API Key to authorize requests to that endpoint. |                         |
+| authorization.clientid | string | optional    |             |     | Field inside _authorization_. The Client ID ( azure active directory ) to authorize requests to that endpoint. |                         |
+| timeout  | integer | optional    | 3000           | [100,...]     | Proxy request timeout in milliseconds.   |
+| ssl_verify  | boolean | optional    | true           | true/false     | If enabled performs SSL verification of the server.                     |
+| keepalive  | boolean | optional    | true           | true/false     | To reuse the same proxy connection in near future. Set to false to disable keepalives and immediately close the connection.                    |
+| keepalive_pool  | integer | optional    | 5          | [1,...]     | The maximum number of connections in the pool.              |
+| keepalive_timeout  | integer | optional    | 60000           | [1000,...]     |  The maximal idle timeout (ms).                     |
+
+## Metadata
+
+| Name                  | Type    | Requirement |     Default     | Valid         | Description                                                            |
+| -----------           | ------  | ----------- |      -------    | -----         | ---------------------------------------------------------------------- |
+| master_apikey         | string  | optional    |  ""             |               | The API KEY secret that could be used to access the azure function uri.                                     |
+| master_clientid       | string  | optional    |   ""            |               | The Client ID (active directory) that could be used the authorize the function uri                                         |
+
+Metadata for `azure-functions` plugin provides the functionality for authorization fallback. It defines `master_apikey` and `master_clientid` (azure active directory client id) where users (optionally) can define the master API key or Client ID for mission-critical application deployment. So if there are no authorization details found inside the plugin attribute the authorization details present in the metadata kicks in.
+
+The relative priority ordering is as follows:
+
+- First, the plugin looks for `x-functions-key` or `x-functions-clientid` keys inside the request header to the APISIX agent.
+- If they are not found, the azure-functions plugin checks for the authorization details inside plugin attributes. If present, it adds the respective header to the request sent to the Azure cloud function.
+- If no authorization details are found inside plugin attributes, APISIX fetches the metadata config for this plugin and uses the master keys.
+
+To add a new Master APIKEY, make a request to _/apisix/admin/plugin_metadata_ endpoint with the updated metadata as follows:
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/azure-functions -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+    "master_apikey" : "<Your azure master access key>"
+}'
+```
+
+## How To Enable
+
+The following is an example of how to enable the azure-function faas plugin for a specific route URI. We are assuming your cloud function is already up and running.
+
+```shell
+# enable azure function for a route
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+    "plugins": {
+        "azure-functions": {
+            "function_uri": "http://test-apisix.azurewebsites.net/api/HttpTrigger",
+            "authorization": {
+                "apikey": "<Generated API key to access the Azure-Function>"
+            }
+        }
+    },
+    "uri": "/azure"
+}'
+```
+
+Now any requests (HTTP/1.1, HTTPS, HTTP2) to URI `/azure` will trigger an HTTP invocation to the aforesaid function URI and response body along with the response headers and response code will be proxied back to the client. For example ( here azure cloud function just take the `name` query param and returns `Hello $name` ) :
+
+```shell
+$ curl -i -XGET http://localhost:9080/azure\?name=apisix
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Request-Context: appId=cid-v1:38aae829-293b-43c2-82c6-fa94aec0a071
+Date: Wed, 17 Nov 2021 14:46:55 GMT
+Server: APISIX/2.10.2
+
+Hello, apisix
+```
+
+For requests where the mode of communication between the client and the Apache APISIX gateway is HTTP/2, the example looks like ( make sure you are running APISIX agent with `enable_http2: true` for a port in conf.yaml or uncomment port 9081 of `node_listen` field inside [config-default.yaml](../../../../conf/config-default.yaml) ) :
+
+```shell
+$ curl -i -XGET --http2 --http2-prior-knowledge http://localhost:9081/azure\?name=apisix
+HTTP/2 200
+content-type: text/plain; charset=utf-8
+request-context: appId=cid-v1:38aae829-293b-43c2-82c6-fa94aec0a071
+date: Wed, 17 Nov 2021 14:54:07 GMT
+server: APISIX/2.10.2
+
+Hello, apisix
+```
+
+## Disable Plugin
+
+Remove the corresponding JSON configuration in the plugin configuration to disable the `azure-functions` plugin and add the suitable upstream configuration.
+APISIX plugins are hot-reloaded, therefore no need to restart APISIX.
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+    "uri": "/azure",
+    "plugins": {},
+    "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "127.0.0.1:1980": 1
+        }
+    }
+}'
+```

t/admin/plugins.t

@@ -40,7 +40,7 @@ __DATA__
 --- request
 GET /apisix/admin/plugins/list
 --- response_body_like eval
-qr/\["real-ip","client-control","ext-plugin-pre-req","zipkin","request-id","fault-injection","serverless-pre-function","batch-requests","cors","ip-restriction","ua-restriction","referer-restriction","uri-blocker","request-validation","openid-connect","authz-casbin","wolf-rbac","ldap-auth","hmac-auth","basic-auth","jwt-auth","key-auth","consumer-restriction","authz-keycloak","proxy-mirror","proxy-cache","proxy-rewrite","api-breaker","limit-conn","limit-count","limit-req","gzip","server-info","traffic-split","redirect","response-rewrite","grpc-transcode","prometheus","datadog","echo","http-logger","skywalking-logger","sls-logger","tcp-logger","kafka-logger","syslog","udp-logger","example-plugin","serverless-post-function","ext-plugin-post-req"\]/
+qr/\["real-ip","client-control","ext-plugin-pre-req","zipkin","request-id","fault-injection","serverless-pre-function","batch-requests","cors","ip-restriction","ua-restriction","referer-restriction","uri-blocker","request-validation","openid-connect","authz-casbin","wolf-rbac","ldap-auth","hmac-auth","basic-auth","jwt-auth","key-auth","consumer-restriction","authz-keycloak","proxy-mirror","proxy-cache","proxy-rewrite","api-breaker","limit-conn","limit-count","limit-req","gzip","server-info","traffic-split","redirect","response-rewrite","grpc-transcode","prometheus","datadog","echo","http-logger","skywalking-logger","sls-logger","tcp-logger","kafka-logger","syslog","udp-logger","example-plugin","azure-functions","serverless-post-function","ext-plugin-post-req"\]/
 --- no_error_log
 [error]
 

t/lib/test_admin.lua

@@ -197,11 +197,11 @@ function _M.test(uri, method, body, pattern, headers)
     end
 
     if res.status >= 300 then
-        return res.status, res.body
+        return res.status, res.body, res.headers
     end
 
     if pattern == nil then
-        return res.status, "passed", res.body
+        return res.status, "passed", res.body, res.headers
     end
 
     local res_data = json.decode(res.body)
@@ -210,7 +210,7 @@ function _M.test(uri, method, body, pattern, headers)
         return 500, "failed, " .. err, res_data
     end
 
-    return 200, "passed", res_data
+    return 200, "passed", res_data, res.headers
 end