This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-website.git
The following commit(s) were added to refs/heads/master by this push:
new e19718d docs: add azure-function plugin blog (#784)
e19718d is described below
commit e19718d127d729007b371d3d12a5afacc9d943a5
Author: yilinzeng <36651058+yzen...@users.noreply.github.com>
AuthorDate: Thu Dec 2 16:21:59 2021 +0800
docs: add azure-function plugin blog (#784)
---
.../2021/12/01/apisix-supports-azure-functions.md | 184 +++++++++++++++++++++
.../2021/12/01/apisix-supports-azure-functions.md | 184 +++++++++++++++++++++
2 files changed, 368 insertions(+)
diff --git a/website/blog/2021/12/01/apisix-supports-azure-functions.md
b/website/blog/2021/12/01/apisix-supports-azure-functions.md
new file mode 100644
index 0000000..ac1101e
--- /dev/null
+++ b/website/blog/2021/12/01/apisix-supports-azure-functions.md
@@ -0,0 +1,184 @@
+---
+title: "Apache APISIX's intergration with Azure Serverless"
+author: "Bisakh Mondal"
+authorURL: "https://github.com/bisakhmondal";
+authorImageURL: "https://avatars.githubusercontent.com/u/41498427?v=4";
+keywords:
+- Apache APISIX
+- Azure Functions
+- Microsoft
+- Serverless
+description: This article talks about the recent addition of a new plugin
`azure-functions`, and gives detailed instructions on how to integrate Azure
Functions, which is a widely used serverless solution, into the Apache APISIX
serverless suite.
+tags: [Technology]
+---
+
+> This article talks about the recent addition of a new plugin
`azure-functions`, and gives detailed instructions on how to integrate Azure
Functions, which is a widely used serverless solution, into the Apache APISIX
serverless suite.
+
+<!--truncate-->
+
+
+
+Apache APISIX provides support for serverless frameworks for popular cloud
vendors (more coming on the way). Instead of hardcoding the function URL into
the application, Apache APISIX suggests defining a route with the serverless
plugin enabled. It gives the developers the flexibility to hot update the
function URI along with completely changing the faas vendor to a different
cloud provider with zero hassle. Also, this approach mitigates authorization
and authentication concerns from app [...]
+
+## How azure-functions plugin works
+
+The `azure-functions` plugin lets the users define an upstream to the azure
`HTTP Trigger` serverless function for a gateway URI. 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, sta [...]
+
+The plugin supports authorization to azure faas service via API keys and azure
active directory.
+
+## How to Use Azure Functions with Apache APISIX
+
+The primary goal of the plugin is to proxy the gateway route specified in the
route configuration to the azure functions URI. This section gives you a
hands-on how to configure and create a serverless HTTP Trigger on the azure
cloud.
+
+1. First sign up/in to Microsoft Azure and sets up a trial plan. Azure
Functions are forever free up to 1 million invocations. To know more about how
the pricing, visit
[here](https://azure.microsoft.com/en-us/services/functions/#pricing).
+
+1. Visit the [Azure Portal](https://portal.azure.com/#home) (FYI, azure
services can be accessed via the web portal, CLI & VSCode. for
user-friendliness we are using the web).
+ 1. First, create a resource group to logically partition your faas that's
you are going to create.
+ 
+ 1. Create a function app with the URL of your choice (I am going to pick
test-apisix).
+ 
+
+1. Install the [Azure Functions
extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions)
into VSCode editor. Upon installation, authenticate via extension and install
the azure function core tool for local development with:
+
+ ```shell
+ npm install -g azure-functions-core-tools@3 --unsafe-perm true
+ ```
+
+1. Deploy the following snippet to the same function app that we just created
via the Azure Functions extension panel in VSCode:
+
+ ```javascript
+ module.exports = async function (context, req) {
+ context.log('HTTP trigger invoked on Test-APISIX.')
+
+ const name = req.query.name || (req.body && req.body.name)
+ const responseMessage = name
+ ? 'Hello, ' + name
+ : 'This HTTP triggered function executed successfully. Pass a name in
the query string or in the request body to generate a personalized response.'
+
+ context.res = {
+ // status: 200, /* Defaults to 200 */
+ body: responseMessage,
+ }
+ }
+ ```
+
+> This snippet takes the name from query parameters (if present, else from the
request body) and greets the user.
+
+### Activate the azure-functions plugin
+
+The following is an example of how to enable the azure-functions plugin for a
specific route. We are assuming your HTTP Trigger is deployed and ready to be
served.
+
+```shell
+# enable plugin for a specific 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` on the Apache APISIX
gateway 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=Bisakh
+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, 19 Nov 2021 18:46:55 GMT
+Server: APISIX/2.10.2
+
+Hello, Bisakh
+```
+
+Considering, Apache APISIX is also running with `enable_http2: true` on
[config-default.yaml](https://github.com/apache/apisix/blob/master/conf/config-default.yaml#L26)
for port 9081 (say), any `HTTP/2` communication between client and APISIX
agent will be proxied to the azure faas similar to HTTP/1.1 and responses will
be proxied back to the client with proper headers. For example:
+
+```shell
+curl -i -XGET --http2 --http2-prior-knowledge
http://localhost:9081/azure\?name=Bisakh
+HTTP/2 200
+content-type: text/plain; charset=utf-8
+request-context: appId=cid-v1:38aae829-293b-43c2-82c6-fa94aec0a071
+Date: Wed, 19 Nov 2021 18:46:56 GMT
+server: APISIX/2.10.2
+
+Hello, Bisakh
+```
+
+### Deactivate the azure-functions plugin
+
+Now, to disable the plugin simply remove the corresponding JSON configuration
in the plugin configuration to disable the `azure-functions` plugin and add the
suitable upstream configuration. Apache APISIX plugins are hot-reloaded,
therefore is no need to restart Apache 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
+ }
+ }
+}'
+```
+
+## Custom Configuration
+
+In a minimal configuration while creating a new route with the
`azure-functions` plugin enabled, `function_uri` is the mandatory attribute of
the plugin config that points to the function URL. There is a lot of additional
options that can be tweaked with plugin schema and metadata schema.
+
+### Plugin Schema
+
+|Name|Type|Required|Default|Valid|Description|
+|----|----|--------|-------|-----|-----------|
+|function_uri|string|required|n/a|n/a|The azure function endpoint which
triggers the serverless function code (eg.
http://test-apisix.azurewebsites.net/api/HttpTrigger).|
+|authorization|object|optional|n/a|n/a|Authorization credentials to access the
cloud function.|
+|authorization.apikey|string|optional|n/a|n/a|Field inside authorization. The
generate API Key to authorize requests to that endpoint.|
+|authorization.clientid|string|optional|n/a|n/a|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|Whether 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).|
+
+This gives a whole lot of flexibility to tightly bind the behaviour of the
azure faas - from configuring the timeout to the keepalive pool and validating
the SSL certificate of the serverless faas. To be honest, this actually means a
lot when it comes to serverless as the services are event-driven and resources
are being allocated by the cloud provider on the fly.
+
+### Metadata Schema
+
+Similarly, there are a few attributes that can be tweaked by using the
metadata.
+
+|Name|Type|Required|Default|Valid|Description|
+|----|----|--------|-------|-----|-----------|
+|master_apikey|string|optional|""|n/a|The API KEY secret that could be used to
access the azure function URI.|
+|master_clientid|string|optional|""|n/a|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 Apache 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, Apache
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>"
+}'
+```
+
+## Summary
+
+The `azure-functions` plugin is Apache APISIX's second plugin designed for
serverless. We are developing other serverless plugins and will feature them
with the upcoming Apache APISIX releases. If you are interested, please don't
hesitate to [file an issue](https://github.com/apache/apisix/issues/new/choose)
to share your opinions. You can talk about your proposals of developing a new
plugin in our [mailing list](https://apisix.apache.org/docs/general/community)
as well!
diff --git
a/website/i18n/zh/docusaurus-plugin-content-blog/2021/12/01/apisix-supports-azure-functions.md
b/website/i18n/zh/docusaurus-plugin-content-blog/2021/12/01/apisix-supports-azure-functions.md
new file mode 100644
index 0000000..7d7f7ea
--- /dev/null
+++
b/website/i18n/zh/docusaurus-plugin-content-blog/2021/12/01/apisix-supports-azure-functions.md
@@ -0,0 +1,184 @@
+---
+title: "azure-functions 插件发布，Apache APISIX 支持 Azure Functions 集成"
+author: "Bisakh Mondal"
+authorURL: "https://github.com/bisakhmondal";
+authorImageURL: "https://avatars.githubusercontent.com/u/41498427?v=4";
+keywords:
+- Apache APISIX
+- Azure Functions
+- Microsoft
+- Serverless
+description: 本文介绍了最近新增的插件 `azure-functions`，并详细说明了如何将 Azure Functions（一种广泛使用的
serverless 解决方案）集成到 Apache APISIX 中。
+tags: [Technology]
+---
+
+> 本文介绍了 Apache APISIX 最近新增的插件 `azure-functions`，并详细说明了如何将 Azure Functions 集成到
Apache APISIX 中。
+
+<!--truncate-->
+
+
+
+Apache APISIX 为 Microsoft Azure Functions 提供了对 serverless 框架的支持。Apache APISIX
建议定义一个启用了无服务器插件的路由，而不是在应用程序中采用硬编码函数 URL。它使开发者能够灵活地热更新函数 URI。此外，因为 Apache APISIX
有非常强大的认证支持，这种方法还可以减轻应用逻辑中的授权和认证问题，可以用来识别和授权客户消费者访问带有 FAAS 的特定路由。本文介绍了 Apache
APISIX 最近新增的插件 `azure-functions`，并详细说明了如何将 Azure Functions（一种广泛使用的 serverless
解决方案）集成到 Apache APISIX 中。
+
+## azure-functions 插件工作原理
+
+`azure-functions` 插件让用户为网关 URI 定义一个上游的 azure `HTTP Trigger` serverless
功能。如果启用，该插件将终止正在进行的对该 URI 的请求，并代表客户向 azure
FAAS（新的上游）发起一个新的请求，其中包括用户设置的合适的授权细节、请求头、请求体、参数（这三个部分都是从原始请求中传递的），并将响应体、状态码和头返回给向
Apache APISIX 代理发出请求的原始客户。
+
+该插件支持通过 API 密钥和 azure active directory 对 azure FAAS 服务进行授权。
+
+## 如何在 Apache APISIX 中使用 azure-functions 插件
+
+该插件的主要目标是将路由配置中指定的网关路由代理到 azure function URI 上。本节为您介绍如何在 azure 云上配置和创建
serverless HTTP Trigger。
+
+1. 首先进入 Azure 并设置一个试用计划，最多可免费调用 100
万次。要了解更多关于定价的情况，请访问[这里](https://azure.microsoft.com/en-us/services/functions/#pricing)。
+
+1. 访问[Azure Portal](https://portal.azure.com/#home)。
+ 1. 首先，创建一个资源组，为 FAAS 创建逻辑分区。
+
+ 1. 用你选择的 URL 创建一个 function 应用。
+ 
+
+1. 在 VSCode 编辑器中安装 [Azure Functions
插件](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions)。安装后，通过插件认证，并安装
azure function core tool，用于本地开发。
+
+ ```shell
+ npm install -g azure-functions-core-tools@3 --unsafe-perm true
+ ```
+
+1. 将下面的代码段部署到我们刚才通过 VSCode 中的 Azure Functions 扩展面板创建的同一个function 应用中。
+
+ ```javascript
+ module.exports = async function (context, req) {
+ context.log('HTTP trigger invoked on Test-APISIX.')
+
+ const name = req.query.name || (req.body && req.body.name)
+ const responseMessage = name
+ ? 'Hello, ' + name
+ : 'This HTTP triggered function executed successfully. Pass a name in
the query string or in the request body to generate a personalized response.'
+
+ context.res = {
+ // status: 200, /* Defaults to 200 */
+ body: responseMessage,
+ }
+ }
+ ```
+
+> 这个代码段从查询参数中获取用户名字（如果不存在，则从请求体中获取）并向用户问好。
+
+### 启用 azure-functions 插件
+
+下面我们将通过一个示例为大家说明如何为一个特定的路由启用 `azure-functions` 插件。我们假设你的 HTTP Trigger
已经部署并准备好提供服务。
+
+```shell
+# enable plugin for a specific 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"
+}'
+```
+
+现在，任何对 Apache APISIX 网关上的 URI `/azure` 的请求（HTTP/1.1、HTTPS、HTTP2）都将触发对上述函数 URI
的 HTTP 调用，响应体与响应头和响应代码将被代理回给客户端。例如：
+
+```shell
+curl -i -XGET http://localhost:9080/azure\?name=Bisakh
+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, 19 Nov 2021 18:46:55 GMT
+Server: APISIX/2.10.2
+
+Hello, Bisakh
+```
+
+考虑到，Apache APISIX
也是在[config-default.yaml](https://github.com/apache/apisix/blob/master/conf/config-default.yaml#L26)上以
`enable_http2: true` 运行，端口为 9081，客户端和 Apache APISIX 代理之间的任何 `HTTP/2` 通信将被代理到
azure faas，类似于 HTTP/1.1，响应将被代理回给客户端，并有适当的标题，例如：
+
+```shell
+curl -i -XGET --http2 --http2-prior-knowledge
http://localhost:9081/azure\?name=Bisakh
+HTTP/2 200
+content-type: text/plain; charset=utf-8
+request-context: appId=cid-v1:38aae829-293b-43c2-82c6-fa94aec0a071
+Date: Wed, 19 Nov 2021 18:46:56 GMT
+server: APISIX/2.10.2
+
+Hello, Bisakh
+```
+
+### 停用 azure-functions 插件
+
+如果需要停用 azure-functions 该插件，只需在插件配置中删除相应的 JSON
配置，禁用`azure-functions`插件，并添加合适的上游配置。Apache APISIX 插件是热加载的，因此不需要重新启动 Apache
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
+ }
+ }
+}'
+```
+
+## 自定义配置
+
+在启用 `azure-functions` 插件创建新路由时，在最小的配置中，`function_uri` 是插件配置的强制性属性，指向函数的
URL。有很多额外的选项，可以通过插件参数和元数据参数进行调整。
+
+### 插件参数解释
+
+|名称|类型|必填|默认值|有效值|描述|
+|----|----|--------|-------|-----|-----------|
+|function_uri|string|是|n/a|n/a|触发 serverless functions 代码的 azure functions
端点（例如：http://test-apisix.azurewebsites.net/api/HttpTrigger）。|
+|authorization|object|否|n/a|n/a|访问云 functions 的授权凭证。|
+|authorization.apikey|string|否|n/a|n/a|授权内的字段。生成API密钥来授权对该端点的请求。|
+|authorization.clientid|string|否|n/a|n/a|授权内的字段。客户端ID（azure active
directory），用于授权对该端点的请求。|
+|timeout|integer|否|3000|[100,...]|代理请求超时，以毫秒为单位。|
+|ssl_verify|boolean|否|true|true/false|是否启用执行服务器的SSL验证。|
+|keepalive|boolean|否|true|true/false|是否重复使用同一个代理连接。设置为false则禁用keepalives并立即关闭连接。|
+|keepalive_pool|integer|否|5|[1,...]|池中的最大连接数。|
+|keepalive_timeout|integer|否|60000|[1000,...]|最大的空闲超时，以毫秒为单位。|
+
+这为严格约束 azure FAAS 的行为提供了很大的灵活性--从配置超时到 keepalive 池以及验证无服务器FAAS 的 SSL
证书。说实话，当涉及到无服务器时，这实际上意味着很多，因为服务是事件驱动的，而且资源是由云提供商即时分配的。
+
+### Metadata 参数解释
+
+同样，有一些属性可以通过使用元数据进行调整。
+
+|名称|类型|必填|默认值|有效值|描述|
+|----|----|--------|-------|-----|-----------|
+|master_apikey|string|否|""|n/a|可用于访问 azure functions URI 的 API KEY。|
+|master_clientid|string|否|""|n/a|可用于授权 function URI的客户ID（active directory）。|
+
+`azure-functions` 插件的元数据提供了授权回退的功能。它定义了 `master_apikey` 和 `master_clientid`
(azure active directory client id)，用户可以为关键任务的应用部署定义主 API 密钥或客户端
ID。因此，如果在插件属性中没有找到授权细节，元数据中的授权细节就会启动。
+
+优先级排序如下
+
+- 首先，该插件在 Apache APISIX 代理的请求头中寻找 `x-functions-key` 或 `x-functions-clientid` 键。
+
+- 如果没有找到，azure-functions 插件会检查插件属性中的授权细节。如果存在，它会将相应的标头添加到发送到 Azure cloud
function 的请求中。
+
+- 如果在插件属性中没有找到授权细节，Apache APISIX 将为该插件获取元数据配置并使用主密钥。
+
+要添加一个新的主 APIKEY，请用更新的元数据向 `/apisix/admin/plugin_metadata` 端点提出请求，如下所示：
+
+```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>"
+}'
+```
+
+## 总结
+
+`azure-functions` 插件是 Apache APISIX 为 serverless 设计的第二个插件。我们正在开发其他 serverless
插件，并会在即将发布的 Apache APISIX 版本中介绍这些插件。如果大家感兴趣，请[提交
Issue](https://github.com/apache/apisix/issues/new/choose)来分享你的意见，也可以在我们的[邮件列表](https://apisix.apache.org/docs/general/community)中分享开发新插件的建议!
