You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sp...@apache.org on 2022/05/20 08:24:19 UTC
[apisix] branch master updated: docs: update "Serverless" Plugins (#7076)
This is an automated email from the ASF dual-hosted git repository.
spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 2fb6e7b07 docs: update "Serverless" Plugins (#7076)
2fb6e7b07 is described below
commit 2fb6e7b070116ee547f628ae0d91a1e9fd91c7ed
Author: Navendu Pottekkat <na...@gmail.com>
AuthorDate: Fri May 20 13:54:14 2022 +0530
docs: update "Serverless" Plugins (#7076)
Signed-off-by: Navendu Pottekkat <na...@gmail.com>
---
docs/en/latest/plugins/aws-lambda.md | 99 ++++++++++++++++++-----------
docs/en/latest/plugins/azure-functions.md | 102 ++++++++++++++++++------------
docs/en/latest/plugins/openwhisk.md | 76 ++++++++++++++++------
docs/en/latest/plugins/serverless.md | 57 ++++++++++-------
4 files changed, 211 insertions(+), 123 deletions(-)
diff --git a/docs/en/latest/plugins/aws-lambda.md b/docs/en/latest/plugins/aws-lambda.md
index d56b5da30..563e997e3 100644
--- a/docs/en/latest/plugins/aws-lambda.md
+++ b/docs/en/latest/plugins/aws-lambda.md
@@ -1,5 +1,11 @@
---
title: aws-lambda
+keywords:
+ - APISIX
+ - Plugin
+ - AWS Lambda
+ - aws-lambda
+description: This document contains information about the Apache APISIX aws-lambda Plugin.
---
<!--
@@ -23,38 +29,40 @@ title: aws-lambda
## Description
-`aws-lambda` is a serverless plugin built into Apache APISIX for seamless integration with [AWS Lambda](https://aws.amazon.com/lambda/), a widely used serverless solution, as a dynamic upstream to proxy all requests for a particular URI to the AWS cloud - one of the highly 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 AWS lambda gateway uri (the new upstream) on beha [...]
-At present, the plugin supports authorization via AWS api key and AWS IAM Secrets.
+The `aws-lambda` Plugin is used for integrating APISIX with [AWS Lambda](https://aws.amazon.com/lambda/) as a dynamic upstream to proxy all requests for a particular URI to the AWS Cloud.
+
+When enabled, the Plugin terminates the ongoing request to the configured URI and initiates a new request to the AWS Lambda Gateway URI on behalf of the client with configured authorization details, request headers, body and parameters (all three passed from the original request). It returns back the response with headers, status code and the body to the client that initiated the request with APISIX.
+
+This Plugin supports authorization via AWS API key and AWS IAM secrets.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| ----------- | ------ | ----------- | ------- | ----- | ------------------------------------------------------------ |
-| function_uri | string | required | | | The AWS api gateway endpoint which triggers the lambda serverless function code. |
-| 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 of the AWS gateway. | |
-| authorization.iam | object | optional | | | Field inside _authorization_. AWS IAM role based authorization, performed via AWS v4 request signing. See schema details below ([here](#iam-authorization-schema)). | |
-| 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). |
+| Name | Type | Required | Default | Valid values | Description |
+|----------------------|---------|----------|---------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------|
+| function_uri | string | True | | | AWS API Gateway endpoint which triggers the lambda serverless function. |
+| authorization | object | False | | | Authorization credentials to access the cloud function. |
+| authorization.apikey | string | False | | | Generated API Key to authorize requests to the AWS Gateway endpoint. |
+| authorization.iam | object | False | | | Used for AWS IAM role based authorization performed via AWS v4 request signing. See [IAM authorization schema](#iam-authorization-schema). |
+| timeout | integer | False | 3000 | [100,...] | Proxy request timeout in milliseconds. |
+| ssl_verify | boolean | False | true | true/false | When set to `true` performs SSL verification. |
+| keepalive | boolean | False | true | true/false | When set to `true` keeps the connection alive for reuse. |
+| keepalive_pool | integer | False | 5 | [1,...] | Maximum number of requests that can be sent on this connection before closing it. |
+| keepalive_timeout | integer | False | 60000 | [1000,...] | Maximum number of requests that can be sent on this connection before closing it. |
### IAM Authorization Schema
-| Name | Type | Requirement | Default | Valid | Description |
-| ----------- | ------ | ----------- | ------- | ----- | ------------------------------------------------------------ |
-| accesskey | string | required | | | Generated access key ID from AWS IAM console. |
-| secret_key | string | required | | | Generated access key secret from AWS IAM console. |
-| aws_region | string | optional | "us-east-1" | | The AWS region where the request is being sent. |
-| service | string | optional | "execute-api" | | The service that is receiving the request (In case of Http Trigger it is "execute-api"). |
+| Name | Type | Required | Default | Description |
+|------------|--------|----------|---------------|-------------------------------------------------------------------------------------|
+| accesskey | string | True | | Generated access key ID from AWS IAM console. |
+| secret_key | string | True | | Generated access key secret from AWS IAM console. |
+| aws_region | string | False | "us-east-1" | AWS region where the request is being sent. |
+| service | string | False | "execute-api" | The service that is receiving the request. For HTTP trigger, it is `"execute-api"`. |
-## How To Enable
+## Enabling the Plugin
-The following is an example of how to enable the aws-lambda faas plugin for a specific route URI. Calling the APISIX route uri will make an invocation to the lambda function uri (the new upstream). We are assuming your cloud function is already up and running.
+The example below shows how you can configure the Plugin on a specific Route:
```shell
-# enable aws lambda for a route via api key authorization
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
@@ -70,10 +78,15 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-Now any requests (HTTP/1.1, HTTPS, HTTP2) to URI `/aws` 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 AWS lambda function just take the `name` query param and returns `Hello $name`) :
+Now, any requests (HTTP/1.1, HTTPS, HTTP2) to the endpoint `/aws` will invoke the configured AWS Functions URI and the response will be proxied back to the client.
+
+In the example below, AWS Lambda takes in name from the query and returns a message "Hello $name":
+
+```shell
+curl -i -XGET localhost:9080/aws\?name=APISIX
+```
```shell
-$ curl -i -XGET localhost:9080/aws\?name=APISIX
HTTP/1.1 200 OK
Content-Type: application/json
Connection: keep-alive
@@ -87,10 +100,13 @@ 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 `config-default.yaml`. You can do it by uncommenting the port 9081 from `apisix.node_listen` field ) :
+Another example of a request where the client communicates with APISIX via HTTP/2 is shown below (make sure you have configured `enable_http2: true` for a in your default configuration file (`config-default.yaml`). You can do this by uncommenting the port `9081` from the field `apisix.node_listen`):
+
+```shell
+curl -i -XGET --http2 --http2-prior-knowledge localhost:9081/aws\?name=APISIX
+```
```shell
-$ curl -i -XGET --http2 --http2-prior-knowledge localhost:9081/aws\?name=APISIX
HTTP/2 200
content-type: application/json
content-length: 16
@@ -103,10 +119,9 @@ server: APISIX/2.10.2
"Hello, APISIX!"
```
-Similarly, the lambda can be triggered via AWS API Gateway by using AWS `IAM` permissions to authorize access to your API via APISIX aws-lambda plugin. Plugin includes authentication signatures in their HTTP calls via AWS v4 request signing. Here is an example:
+Similarly the function can be triggered via AWS API Gateway by using AWS IAM permissions for authorization. The Plugin includes authentication signatures in HTTP calls via AWS v4 request signing. The example below shows this method:
```shell
-# enable aws lambda for a route via iam authorization
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
@@ -125,15 +140,23 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-**Note**: This approach assumes you already have an iam user with the programmatic access enabled and required permissions (`AmazonAPIGatewayInvokeFullAccess`) to access the endpoint.
+:::note
-### Plugin with Path Forwarding
+This approach assumes that you have already an IAM user with programmatic access enabled with the required permissions (`AmazonAPIGatewayInvokeFullAccess`) to access the endpoint.
-AWS Lambda plugin supports url path forwarding while proxying request to the modified upstream (AWS Gateway URI endpoint). With that being said, any extension to the path of the base request APISIX gateway URI gets "appended" (path join) to the `function_uri` specified in the plugin configuration.
+:::
-**Note**: APISIX route uri must be ended with an asterisk (`*`) for this feature to work properly. APISIX routes are strictly matched and the extra asterisk at the suffix means any subpath appended to the original parent path will use the same route object configurations.
+### Configuring path forwarding
-Here is an example:
+The `aws-lambda` Plugins also supports URL path forwarding while proxying requests to the AWS upstream. Extensions to the base request path gets appended to the `function_uri` specified in the Plugin configuration.
+
+:::info IMPORTANT
+
+The `uri` configured on a Route must end with `*` for this feature to work properly. APISIX Routes are matched strictly and the `*` implies that any subpath to this URI would be matched to the same Route.
+
+:::
+
+The example below configures this feature:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -151,10 +174,13 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-Now any request with path `aws/default/test-apisix` will invoke the aws api gateway endpoint. Here the extra path (where the magic character `*` has been used) up to the query params have been forwarded.
+Now, any requests to the path `aws/default/test-apisix` will invoke the AWS Lambda Function and the added path is forwarded:
```shell
curl -i -XGET http://127.0.0.1:9080/aws/default/test-apisix\?name\=APISIX
+```
+
+```shell
HTTP/1.1 200 OK
Content-Type: application/json
Connection: keep-alive
@@ -170,11 +196,10 @@ Server: APISIX/2.11.0
## Disable Plugin
-Remove the corresponding JSON configuration in the plugin configuration to disable the `aws-lambda` plugin and add the suitable upstream configuration.
-APISIX plugins are hot-reloaded, therefore no need to restart APISIX.
+To disable the `aws-lambda` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/aws",
"plugins": {},
diff --git a/docs/en/latest/plugins/azure-functions.md b/docs/en/latest/plugins/azure-functions.md
index 0fbaa72a9..a873211aa 100644
--- a/docs/en/latest/plugins/azure-functions.md
+++ b/docs/en/latest/plugins/azure-functions.md
@@ -1,7 +1,12 @@
---
title: azure-functions
+keywords:
+ - APISIX
+ - Plugin
+ - Azure Functions
+ - azure-functions
+description: This document contains information about the Apache APISIX azure-functions Plugin.
---
-
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
@@ -23,52 +28,53 @@ title: azure-functions
## Description
-`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 [...]
+The `azure-functions` Plugin is used to integrate APISIX 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.
+
+When enabled, the Plugin terminates the ongoing request to the configured URI and initiates a new request to Azure Functions on behalf of the client with configured authorization details, request headers, body and parameters (all three passed from the original request). It returns back the response with headers, status code and the body to the client that initiated the request with APISIX.
## 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). |
+| Name | Type | Required | Default | Valid values | Description |
+|------------------------|---------|----------|---------|--------------|---------------------------------------------------------------------------------------------------------------------------------------|
+| function_uri | string | True | | | Azure FunctionS endpoint which triggers the serverless function. For example, `http://test-apisix.azurewebsites.net/api/HttpTrigger`. |
+| authorization | object | False | | | Authorization credentials to access Azure Functions. |
+| authorization.apikey | string | False | | | Generated API key to authorize requests. |
+| authorization.clientid | string | False | | | Azure AD client ID to authorize requests. |
+| timeout | integer | False | 3000 | [100,...] | Proxy request timeout in milliseconds. |
+| ssl_verify | boolean | False | true | true/false | When set to `true` performs SSL verification. |
+| keepalive | boolean | False | true | true/false | When set to `true` keeps the connection alive for reuse. |
+| keepalive_pool | integer | False | 5 | [1,...] | Maximum number of requests that can be sent on this connection before closing it. |
+| keepalive_timeout | integer | False | 60000 | [1000,...] | Time is ms for connection to remain idle without closing. |
## 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 |
+| Name | Type | Required | Default | Description |
+|-----------------|--------|----------|---------|----------------------------------------------------------------------|
+| master_apikey | string | False | "" | API Key secret that could be used to access the Azure Functions URI. |
+| master_clientid | string | False | "" | Azure AD client ID that could be used to 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.
+Metadata can be used in the `azure-functions` Plugin for an authorization fallback. If there are no authorization details in the Plugin's attributes, the `master_apikey` and `master_clientid` configured in the metadata is used.
-The relative priority ordering is as follows:
+The relative order priority 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.
+1. Plugin looks for `x-functions-key` or `x-functions-clientid` key inside the header from the request to APISIX.
+2. If not found, the Plugin checks the configured attributes for authorization details. If present, it adds the respective header to the request sent to the Azure Functions.
+3. If authorization details are not configured in the Plugin's attributes, APISIX fetches the metadata 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:
+To add a new master API key, you can make a request to `/apisix/admin/plugin_metadata` with the required metadata as shown below:
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/azure-functions -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+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>"
+ "master_apikey" : "<Your Azure master access key>"
}'
```
-## How To Enable
+## Enabling the Plugin
-The following is an example of how to enable the azure-function faas plugin for a specific APISIX route URI. We are assuming your cloud function is already up and running.
+You can configure the Plugin on a specific Route as shown below assuming that you already have your Azure Functions 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": {
@@ -83,10 +89,15 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-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` ) :
+Now, any requests (HTTP/1.1, HTTPS, HTTP2) to the endpoint `/azure` will invoke the configured Azure Functions URI and the response will be proxied back to the client.
+
+In the example below, the Azure Function takes in name from the query and returns a message "Hello $name":
+
+```shell
+curl -i -XGET http://localhost:9080/azure\?name=APISIX
+```
```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
@@ -98,10 +109,13 @@ 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 `config-default.yaml`. You can do it by uncommenting the port 9081 from `apisix.node_listen` field ) :
+Another example of a request where the client communicates with APISIX via HTTP/2 is shown below (make sure you have configured `enable_http2: true` in your default configuration file (`config-default.yaml`). You can do this by uncommenting the port `9081` from the field `apisix.node_listen`):
+
+```shell
+curl -i -XGET --http2 --http2-prior-knowledge http://localhost:9081/azure\?name=APISIX
+```
```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
@@ -111,13 +125,17 @@ server: APISIX/2.10.2
Hello, APISIX
```
-### Plugin with Path Forwarding
+### Configuring path forwarding
+
+The `azure-functions` Plugins also supports URL path forwarding while proxying requests to the Azure Functions upstream. Extensions to the base request path gets appended to the `function_uri` specified in the Plugin configuration.
-Azure Faas plugin supports url path forwarding while proxying request to the modified upstream. With that being said, any extension to the path of the base request APISIX gateway URI gets "appended" (path join) to the `function_uri` specified in the plugin configuration.
+:::info IMPORTANT
-**Note**: APISIX route uri must be ended with an asterisk (`*`) for this feature to work properly. APISIX routes are strictly matched and the extra asterisk at the suffix means any subpath appended to the original parent path will use the same route object configurations.
+The `uri` configured on a Route must end with `*` for this feature to work properly. APISIX Routes are matched strictly and the `*` implies that any subpath to this URI would be matched to the same Route.
-Here is an example:
+:::
+
+The example below configures this feature:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -134,10 +152,13 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-Now any request with path `azure/HttpTrigger1` will invoke the azure function. Here the extra path (where the magic character `*` has been used) up to the query params have been forwarded.
+Now, any requests to the path `azure/HttpTrigger1` will invoke the Azure Function and the added path is forwarded:
+
+```shell
+curl -i -XGET http://127.0.0.1:9080/azure/HttpTrigger1\?name\=APISIX\
+```
```shell
-curl -i -XGET http://127.0.0.1:9080/azure/HttpTrigger1\?name\=APISIX
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
@@ -151,11 +172,10 @@ 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.
+To disable the `azure-functions` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/azure",
"plugins": {},
diff --git a/docs/en/latest/plugins/openwhisk.md b/docs/en/latest/plugins/openwhisk.md
index 8bed39b1e..fc60565ad 100644
--- a/docs/en/latest/plugins/openwhisk.md
+++ b/docs/en/latest/plugins/openwhisk.md
@@ -1,5 +1,11 @@
---
title: openwhisk
+keywords:
+ - APISIX
+ - Plugin
+ - OpenWhisk
+ - openwhisk
+description: This document contains information about the Apache openwhisk Plugin.
---
<!--
@@ -23,34 +29,36 @@ title: openwhisk
## Description
-The `openwhisk` plugin is used to support integration with the [Apache OpenWhisk](https://openwhisk.apache.org) serverless platform and can be set up on a route in place of Upstream, which will take over the request and send it to the OpenWhisk API endpoint.
+The `openwhisk` Plugin is used to integrate APISIX with [Apache OpenWhisk](https://openwhisk.apache.org) serverless platform.
-Users can call the OpenWhisk action via APISIX, pass the request parameters via JSON and get the response content.
+This Plugin can be configured on a Route and requests will be send to the configured OpenWhish API endpoint as the upstream.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| -- | -- | -- | -- | -- | -- |
-| api_host | string | required | | | OpenWhisk API host (eg. https://localhost:3233) |
-| ssl_verify | boolean | optional | true | | Whether to verify the certificate |
-| service_token | string | required | | | OpenWhisk ServiceToken (The format is `xxx:xxx`，Passed through Basic Auth when calling the API) |
-| namespace | string | required | | | OpenWhisk Namespace (eg. guest) |
-| action | string | required | | | OpenWhisk Action (eg. hello) |
-| result | boolean | optional | true | | Whether to get Action metadata (default to execute function and get response; false to get Action metadata but not execute Action, including runtime, function body, restrictions, etc.) |
-| timeout | integer | optional | 60000ms | [1, 60000]ms | OpenWhisk Action and HTTP call timeout. |
-| keepalive | boolean | optional | true | | HTTP keepalive |
-| keepalive_timeout | integer | optional | 60000ms | [1000,...] | keepalive idle timeout |
-| keepalive_pool | integer | optional | 5 | [1,...] | Connection pool limit |
+| Name | Type | Required | Default | Valid values | Description |
+| ----------------- | ------- | -------- | ------- | ------------ | ---------------------------------------------------------------------------------------------------------- |
+| api_host | string | True | | | OpenWhisk API host address. For example, `https://localhost:3233`. |
+| ssl_verify | boolean | False | true | | When set to `true` verifies the SSL certificate. |
+| service_token | string | True | | | OpenWhisk service token. The format is `xxx:xxx` and it is passed through basic auth when calling the API. |
+| namespace | string | True | | | OpenWhisk namespace. For example `guest`. |
+| action | string | True | | | OpenWhisk action. For example `hello`. |
+| result | boolean | False | true | | When set to `true` gets the action metadata (executes the function and gets response). |
+| timeout | integer | False | 60000ms | [1, 60000]ms | OpenWhisk action and HTTP call timeout in ms. |
+| keepalive | boolean | False | true | | When set to `true` keeps the connection alive for reuse. |
+| keepalive_timeout | integer | False | 60000ms | [1000,...]ms | Time is ms for connection to remain idle without closing. |
+| keepalive_pool | integer | False | 5 | [1,...] | Maximum number of requests that can be sent on this connection before closing it. |
:::note
-- The `timeout` property controls both the time taken by the OpenWhisk Action to execute and the timeout of the HTTP client in APISIX. OpenWhisk Action calls may consume time on pulling the runtime image and starting the container, so if you set the value too small, you may cause a large number of requests to fail. OpenWhisk supports timeouts ranging from 1ms to 60000ms, and we recommended to set at least 1000ms or more.
+The `timeout` attribute sets the time taken by the OpenWhisk action to execute, and the timeout for the HTTP client in APISIX. OpenWhisk action calls may take time to pull the runtime image and start the container. So, if the value is set too small, it may cause a large number of requests to fail.
+
+OpenWhisk supports timeouts in the range 1ms to 60000ms and it is recommended to set it to at least 1000ms.
:::
-## Example
+## Enabling the Plugin
-First, you need to run the OpenWhisk environment. Here is an example of using OpenWhisk standalone mode.
+Before configuring the Plugin, you need to have OpenWhisk running. The example below shows OpenWhisk in standalone mode:
```shell
docker run --rm -d \
@@ -61,14 +69,14 @@ docker run --rm -d \
docker exec openwhisk waitready
```
-Then, you need to create an Action for testing.
+You can then create an action to test:
```shell
wsk property set --apihost "http://localhost:3233" --auth "23bc46b1-71f6-4ed5-8c54-816aa4f8c502:123zO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP"
wsk action update test <(echo 'function main(){return {"ready":true}}') --kind nodejs:14
```
-Here is an example of creating a Route and enabling this plugin
+You can now configure the Plugin on a specific Route and point to this running OpenWhisk service:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -85,8 +93,34 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-Finally, you can send a request to this route and you will get the following response. And you can disable it by removing the openwhsik plugin from the route.
+## Example usage
+
+Once you have configured the Plugin, you can send a request to the Route and it will invoke the configured action:
+
+```shell
+curl -i http://127.0.0.1:9080/hello
+```
+
+This will give back the response from the action:
```json
-{"ready": true}
+{ "ready": true }
+```
+
+## Disable Plugin
+
+To disable the `openwhisk` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "methods": ["GET"],
+ "uri": "/index.html",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}'
```
diff --git a/docs/en/latest/plugins/serverless.md b/docs/en/latest/plugins/serverless.md
index e1d01a0b6..8bcc9d9aa 100644
--- a/docs/en/latest/plugins/serverless.md
+++ b/docs/en/latest/plugins/serverless.md
@@ -1,5 +1,11 @@
---
title: serverless
+keywords:
+ - APISIX
+ - Plugin
+ - Serverless
+ - serverless
+description: This document contains information about the Apache APISIX serverless Plugin.
---
<!--
@@ -23,20 +29,22 @@ title: serverless
## Description
-There are two plug-ins for serverless, namely `serverless-pre-function` and `serverless-post-function`.
+There are two `serverless` Plugins in APISIX: `serverless-pre-function` and `serverless-post-function`. The former runs at the beginning of the specified phase, while the latter runs at the end of the specified phase.
-The former runs at the beginning of the specified phase, while the latter runs at the end of the specified phase.
-
-Both plug-ins receive the same parameters.
+Both Plugins have the same attributes.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| --------- | ------------- | ----------- | ---------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| phase | string | optional | ["access"] | ["rewrite", "access", "header_filter", "body_filter", "log", "before_proxy"] | |
-| functions | array[string] | required | | | A list of functions that are specified to run is an array type, which can contain either one function or multiple functions, executed sequentially. |
+| Name | Type | Required | Default | Valid values | Description |
+|-----------|---------------|----------|------------|------------------------------------------------------------------------------|------------------------------------------------------------------|
+| phase | string | False | ["access"] | ["rewrite", "access", "header_filter", "body_filter", "log", "before_proxy"] | Phase before or after which the serverless function is executed. |
+| functions | array[string] | True | | | List of functions that are executed sequentially. |
+
+:::info IMPORTANT
-Note that only function is accepted here, not other types of Lua code. For example, anonymous functions are legal:<br />
+Only Lua functions are allowed here and not other Lua code.
+
+For example, anonymous functions are legal:
```lua
return function()
@@ -44,7 +52,7 @@ return function()
end
```
-Closure is also legal:
+Closures are also legal:
```lua
local count = 1
@@ -54,20 +62,26 @@ return function()
end
```
-But code that is not a function type is illegal:
+But code other than functions are illegal:
```lua
local count = 1
ngx.say(count)
```
-Since `v2.6`, we pass the `conf` and `ctx` as the first two arguments to the servelss function, like a regular plugin.
+:::
+
+:::note
-Prior to `v2.12.0`, the phase `before_proxy` used to be called `balancer`. Considering that this method actually runs after `access` and before the request goes upstream, and has nothing to do with `balancer`, the new naming would be more appropriate.
+From v2.6, `conf` and `ctx` are passed as the first two arguments to a serverless function like regular Plugins.
-## How To Enable
+Prior to v2.12.0, the phase `before_proxy` was called `balancer`. This was updated considering that this method would run after `access` and before the request goes Upstream and is unrelated to `balancer`.
-Here's an example, enable the serverless plugin on the specified route:
+:::
+
+## Enabling the Plugin
+
+The example below enables the Plugin on a specific Route:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -92,22 +106,19 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}'
```
-## Test Plugin
+## Example usage
-Use curl to access:
+Once you have configured the Plugin as shown above, you can make a request as shown below:
```shell
curl -i http://127.0.0.1:9080/index.html
```
-Then you will find the message 'serverless pre-function' and 'match uri /index.html' in the error.log,
-which indicates that the specified function is in effect.
+You will find a message "serverless pre-function" and "match uri /index.html" in the error.log.
## Disable Plugin
-When you want to disable the serverless plugin, it is very simple,
-you can delete the corresponding json configuration in the plugin configuration,
-no need to restart the service, it will take effect immediately:
+To disable the `serverless` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -122,5 +133,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}
}'
```
-
-The serverless plugin has been disabled now. It works for other plugins.