This plugin invokes
OpenWhisk Action.
The Apache OpenWhisk plugin can be used in combination with other request plugins to secure, manage,
or extend the function.
Installation
You can either use the LuaRocks package manager to install the plugin
luarocks install kong-plugin-openwhisk
or install it from source.
For more information on plugin installation, see the documentation
Plugin Development - (un)Install your plugin.
Configuration Reference
This plugin is compatible with DB-less mode.
In DB-less mode, you configure Kong Gateway
declaratively.
Therefore, the Admin API is mostly read-only. The only tasks it can perform are all
related to handling the declarative config, including:
- Setting a target's health status in the load balancer
- Validating configurations against schemas
- Uploading the declarative configuration using the
/config
endpoint
Example plugin configuration
Enable on a service
Enable on a route
Enable on a consumer
Enable globally
The following examples provide some typical configurations for enabling
the openwhisk
plugin on a
service.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/services/SERVICE_NAME|SERVICE_ID/plugins \
--data "name=openwhisk" \
--data "config.host=<OPENWHISK_HOST>" \
--data "config.path=<PATH_TO_ACTION>" \
--data "config.action=<ACTION_NAME>" \
--data "config.service_token=<AUTHENTICATION_TOKEN>"
Replace SERVICE_NAME|SERVICE_ID
with the id
or name
of the service that this plugin configuration will target.
First, create a KongPlugin
resource:
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: openwhisk-example
config:
host: <OPENWHISK_HOST>
path: <PATH_TO_ACTION>
action: <ACTION_NAME>
service_token: <AUTHENTICATION_TOKEN>
plugin: openwhisk
Next, apply the KongPlugin resource to a
service by annotating the
service as follows:
apiVersion: v1
kind: Service
metadata:
name: SERVICE_NAME|SERVICE_ID
labels:
app: SERVICE_NAME|SERVICE_ID
annotations:
konghq.com/plugins: openwhisk-example
spec:
ports:
- port: 80
targetPort: 80
protocol: TCP
name: SERVICE_NAME|SERVICE_ID
selector:
app: SERVICE_NAME|SERVICE_ID
Replace SERVICE_NAME|SERVICE_ID
with the id
or name
of the service that this plugin configuration will target.
Note: The KongPlugin resource only needs to be defined once
and can be applied to any service, consumer, or route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin
instead of KongPlugin
.
Add this section to your declarative configuration file:
plugins:
- name: openwhisk
service: SERVICE_NAME|SERVICE_ID
config:
host: <OPENWHISK_HOST>
path: <PATH_TO_ACTION>
action: <ACTION_NAME>
service_token: <AUTHENTICATION_TOKEN>
Replace SERVICE_NAME|SERVICE_ID
with the id
or name
of the service that this plugin configuration will target.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- From the Services section, click View for the
service row.
- From the plugin section, click Add Plugin.
- Find and select the Apache OpenWhisk plugin.
- If the option is available, select Scoped.
- Add the service name and ID to the Service field if it
is not already pre-filled.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Host:
<OPENWHISK_HOST>
- Config.Path:
<PATH_TO_ACTION>
- Config.Action:
<ACTION_NAME>
- Click Create.
The following examples provide some typical configurations for enabling
the openwhisk
plugin on a
route.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/routes/ROUTE_NAME|ROUTE_ID/plugins \
--data "name=openwhisk" \
--data "config.host=<OPENWHISK_HOST>" \
--data "config.path=<PATH_TO_ACTION>" \
--data "config.action=<ACTION_NAME>" \
--data "config.service_token=<AUTHENTICATION_TOKEN>"
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route that this plugin configuration will target.
First, create a KongPlugin
resource:
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: openwhisk-example
config:
host: <OPENWHISK_HOST>
path: <PATH_TO_ACTION>
action: <ACTION_NAME>
service_token: <AUTHENTICATION_TOKEN>
plugin: openwhisk
Then, apply it to an ingress (route or routes)
by annotating the ingress as follows:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ROUTE_NAME|ROUTE_ID
annotations:
kubernetes.io/ingress.class: kong
konghq.com/plugins: openwhisk-example
spec:
rules:
- host: examplehostname.com
http:
paths:
- path: /bar
backend:
service:
name: echo
port:
number: 80
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route that this plugin configuration will target.
Note: The KongPlugin resource only needs to be defined once
and can be applied to any service, consumer, or route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin
instead of KongPlugin
.
Add this section to your declarative configuration file:
plugins:
- name: openwhisk
route: ROUTE_NAME
config:
host: <OPENWHISK_HOST>
path: <PATH_TO_ACTION>
action: <ACTION_NAME>
service_token: <AUTHENTICATION_TOKEN>
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route that this plugin configuration
will target.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- Open Routes from the menu, then click View for the
route row.
- From the plugin section, click Add Plugin.
- Find and select the Apache OpenWhisk plugin.
- If the option is available, select Scoped.
- Add the route ID if it is not already prefilled.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Host:
<OPENWHISK_HOST>
- Config.Path:
<PATH_TO_ACTION>
- Config.Action:
<ACTION_NAME>
- Click Create.
The following examples provide some typical configurations for enabling
the openwhisk
plugin on a
consumer.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/consumers/CONSUMER_NAME|CONSUMER_ID/plugins \
--data "name=openwhisk" \
--data "config.host=<OPENWHISK_HOST>" \
--data "config.path=<PATH_TO_ACTION>" \
--data "config.action=<ACTION_NAME>" \
--data "config.service_token=<AUTHENTICATION_TOKEN>"
Replace CONSUMER_NAME|CONSUMER_ID
with the id
or name
of the consumer that this plugin configuration will target.
You can combine consumer.id
, service.id
, or route.id
in the same request, to further narrow the scope of the plugin.
First, create a KongPlugin
resource:
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: openwhisk-example
config:
host: <OPENWHISK_HOST>
path: <PATH_TO_ACTION>
action: <ACTION_NAME>
service_token: <AUTHENTICATION_TOKEN>
plugin: openwhisk
Then, apply it to a consumer by
annotating the KongConsumer resource as follows:
apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
name: CONSUMER_NAME|CONSUMER_ID
annotations:
konghq.com/plugins: openwhisk-example
kubernetes.io/ingress.class: kong
Replace CONSUMER_NAME|CONSUMER_ID
with the id
or name
of the consumer that this plugin configuration will target.
Note: The KongPlugin resource only needs to be defined once
and can be applied to any service, consumer, or route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin
instead of KongPlugin
.
Add this section to your declarative configuration file:
plugins:
- name: openwhisk
consumer: CONSUMER_NAME|CONSUMER_ID
config:
host: <OPENWHISK_HOST>
path: <PATH_TO_ACTION>
action: <ACTION_NAME>
service_token: <AUTHENTICATION_TOKEN>
Replace CONSUMER_NAME|CONSUMER_ID
with the id
or name
of the consumer that this plugin configuration will target.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- From the Consumers section, click View for the consumer row.
- Select the Plugins tab, then click Add Plugin.
- Find and select the Apache OpenWhisk plugin.
- If the option is available, select Scoped.
- Add the consumer ID if it is not already prefilled.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Host:
<OPENWHISK_HOST>
- Config.Path:
<PATH_TO_ACTION>
- Config.Action:
<ACTION_NAME>
- Click Create.
A plugin which is not associated to any service, route, or consumer is
considered global, and will be run on every request. Read the
Plugin Reference and the Plugin Precedence
sections for more information.
The following examples provide some typical configurations for enabling
the openwhisk
plugin globally.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/plugins/ \
--data "name=openwhisk" \
--data "config.host=<OPENWHISK_HOST>" \
--data "config.path=<PATH_TO_ACTION>" \
--data "config.action=<ACTION_NAME>" \
--data "config.service_token=<AUTHENTICATION_TOKEN>"
Create a KongClusterPlugin
resource and label it as global:
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
name: <global-openwhisk>
annotations:
kubernetes.io/ingress.class: kong
labels:
global: \"true\"
config:
host: <OPENWHISK_HOST>
path: <PATH_TO_ACTION>
action: <ACTION_NAME>
service_token: <AUTHENTICATION_TOKEN>
plugin: openwhisk
Add a plugins
entry in the declarative
configuration file:
plugins:
- name: openwhisk
config:
host: <OPENWHISK_HOST>
path: <PATH_TO_ACTION>
action: <ACTION_NAME>
service_token: <AUTHENTICATION_TOKEN>
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- Open Plugins from the menu, then click New Plugin.
- Find and select the Apache OpenWhisk plugin.
- If the option is available, set the plugin scope to Global.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Host:
<OPENWHISK_HOST>
- Config.Path:
<PATH_TO_ACTION>
- Config.Action:
<ACTION_NAME>
- Click Create.
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
Form Parameter |
Description |
name
required
Type: string
|
The name of the plugin, in this case openwhisk . |
instance_name
optional
Type: string
|
An optional custom name to identify an instance of the plugin, for example openwhisk_my-service .
Useful when running the same plugin in multiple contexts, for example, on multiple services.
|
service.name or service.id
optional
Type: string
|
The name or ID of the service the plugin targets.
Set one of these parameters if adding the plugin to a service through the top-level /plugins endpoint.
Not required if using /services/SERVICE_NAME|SERVICE_ID/plugins . |
route.name or route.id
optional
Type: string
|
The name or ID of the route the plugin targets.
Set one of these parameters if adding the plugin to a route through the top-level /plugins endpoint.
Not required if using /routes/ROUTE_NAME|ROUTE_ID/plugins . |
consumer.name or consumer.id
optional
Type: string
|
The name or ID of the consumer the plugin targets.
Set one of these parameters if adding the plugin to a consumer through the top-level /plugins endpoint.
Not required if using /consumers/CONSUMER_NAME|CONSUMER_ID/plugins . |
enabled
optional
Type: boolean
Default value: true
|
Whether this plugin will be applied. |
config.host
required
Type: string
|
Host of the OpenWhisk server.
|
config.port
required
Type: integer
Default value: 443
|
Port of the OpenWhisk server.
|
config.path
required
Type: string
|
The path to Action resource.
|
config.action
required
Type: string
|
Name of the Action to be invoked by the plugin.
|
config.service_token
optional
Type: string
|
The service token to access Openwhisk resources.
|
config.https_verify
optional
Type: boolean
Default value: false
|
Set to true to authenticate Openwhisk server.
|
config.https
optional
Type: boolean
Default value: true
|
Option to use HTTPS to connect with the OpenWhisk server.
|
config.result
optional
Type: boolean
Default value: true
|
Return only the result of the invoked Action .
|
config.timeout
optional
Type: integer
Default value: 60000
|
Timeout in milliseconds before closing a connection to OpenWhisk server.
|
config.keepalive
optional
Type: integer
Default value: 60000
|
Time in milliseconds for which an idle connection to OpenWhisk server lives before being closed.
|
Note: If config.https_verify
is set to true
, then the server certificate
is verified according to the CA certificates specified by the
lua_ssl_trusted_certificate
directive in your Kong configuration.
Demonstration
For this demonstration, we are running Kong and
Openwhisk platform locally on a
Vagrant machine on a MacOS.
Step 1. Create a JavaScript Action
Create a JavaScript Action hello
with the following code snippet on the
Openwhisk platform using wsk cli
.
function main(params) {
var name = params.name || 'World';
return {payload: 'Hello, ' + name + '!'};
}
wsk action create hello hello.js
Step 2. Create a service or route
With a database
Without a database
Create a service:
curl -i -X POST http://localhost:8001/services/ \
--data "name=openwhisk-test" \
--data "url=http://example.com"
Response:
Create a route that uses the service:
curl -i -f -X POST http://localhost:8001/services/openwhisk-test/routes/ \
--data "paths[]=/"
Response:
Add a service and an associated route on the declarative config file:
services:
- name: openwhisk-test
url: http://example.com
routes:
- service: openwhisk-test
paths: ["/"]
Step 3. Enable the openwhisk
plugin on the route
With a database
Without a database
Plugins can be enabled on a service or a route (or globally). This example uses a service.
curl -i -X POST http://localhost:8001/services/openwhisk-test/plugins \
--data "name=openwhisk" \
--data "config.host=192.168.33.13" \
--data "config.service_token=username:key" \
--data "config.action=hello" \
--data "config.path=/api/v1/namespaces/guest"
Response:
Add an entry to the plugins:
declarative configuration yaml entry.
It can be associated to a service or route. This example uses a service:
plugins:
- name: openwhisk
config:
host: 192.168.33.13
service_token: username:key
action: hello
path: /api/v1/namespaces/guest
Step 4. Make a request to invoke the action
Without parameters:
curl -i -X POST http://localhost:8000/ -H "Host:example.com"
Response:
HTTP/1.1 200 OK
...
{
"payload": "Hello, World!"
}
Parameters as form-urlencoded:
curl -i -X POST http://localhost:8000/ -H "Host:example.com" --data "name=bar"
Response:
HTTP/1.1 200 OK
...
{
"payload": "Hello, bar!"
}
Parameters as JSON body:
curl -i -X POST http://localhost:8000/ -H "Host:example.com" \
-H "Content-Type:application/json" --data '{"name":"bar"}'
Response:
HTTP/1.1 200 OK
...
{
"payload": "Hello, bar!"
}
Parameters as multipart form:
curl -i -X POST http://localhost:8000/ -H "Host:example.com" -F name=bar
Response:
HTTP/1.1 100 Continue
HTTP/1.1 200 OK
...
{
"payload": "Hello, bar!"
}
Parameters as querystring:
curl -i -X POST http://localhost:8000/?name=foo -H "Host:example.com"
Response:
HTTP/1.1 200 OK
...
{
"payload": "Hello, foo!"
}
OpenWhisk metadata in response:
When Kong’s config.result
is set to false
, OpenWhisk’s metadata is
returned in the response.
curl -i -X POST http://localhost:8000/?name=foo -H "Host:example.com"
Response:
HTTP/1.1 200 OK
...
{
"duration": 4,
"name": "hello",
"subject": "guest",
"activationId": "50218ff03f494f62abbde5dfd2fcc68a",
"publish": false,
"annotations": [{
"key": "limits",
"value": {
"timeout": 60000,
"memory": 256,
"logs": 10
}
}, {
"key": "path",
"value": "guest/hello"
}],
"version": "0.0.4",
"response": {
"result": {
"payload": "Hello, foo!"
},
"success": true,
"status": "success"
},
"end": 1491855076125,
"logs": [],
"start": 1491855076121,
"namespace": "guest"
}
Limitations
Use a fake upstream service
When using the OpenWhisk plugin, the response is returned by the plugin
itself without proxying the request to any upstream service. This means that
a Service’s host
, port
, path
properties are ignored, but must still
be specified for the entity to be validated by Kong. The host
property in
particular must either be an IP address, or a hostname that gets resolved by
your nameserver.
Response plugins
There is a known limitation in the system that prevents some response plugins
from being executed. We are planning to remove this limitation in the future.