This plugin invokes Azure Functions. It can be used in combination with other request plugins to secure, manage or extend the function.


Terminology

  • plugin: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.
  • Service: the Kong entity representing an external upstream API or microservice.
  • Route: the Kong entity representing a way to map downstream requests to upstream services.
  • Consumer: the Kong entity representing a developer or machine using the API. When using Kong, a Consumer only communicates with Kong which proxies every call to the said upstream API.
  • Credential: a unique string associated with a Consumer, also referred to as an API key.
  • upstream service: this refers to your own API/service sitting behind Kong, to which client requests are forwarded.
  • API: a legacy entity used to represent your upstream services. Deprecated in favor of Services since CE 0.13.0 and EE 0.32.

Configuration

Enabling the plugin on a Service

Configure this plugin on a Service by making the following request:

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=azure-functions"  \
    --data "config.functionname=" \
    --data "config.appname=AZURE_APPNAME" \
    --data "config.apikey=AZURE_APIKEY"

  • service: the id or name of the Service that this plugin configuration will target.

Enabling the plugin on a Route

Configure this plugin on a Route with:

$ curl -X POST http://kong:8001/routes/{route_id}/plugins \
    --data "name=azure-functions"  \
    --data "config.functionname=" \
    --data "config.appname=AZURE_APPNAME" \
    --data "config.apikey=AZURE_APIKEY"

  • route_id: the id of the Route that this plugin configuration will target.

Enabling the plugin on a Consumer

You can use the http://localhost:8001/plugins endpoint to enable this plugin on specific Consumers:

$ curl -X POST http://kong:8001/plugins \
    --data "name=azure-functions" \
    --data "consumer_id={consumer_id}"  \
    --data "config.functionname=" \
    --data "config.appname=AZURE_APPNAME" \
    --data "config.apikey=AZURE_APIKEY"

Where consumer_id is the id of the Consumer we want to associate with this plugin.

You can combine consumer_id and service_id

in the same request, to furthermore narrow the scope of the plugin.

Enabling the plugin on an API

If you are using an older version of Kong with the legacy API entity (deprecated in favor of Services since CE 0.13.0 and EE 0.32.), you can configure this plugin on top of such an API by making the following request:

$ curl -X POST http://kong:8001/apis/{api}/plugins \
    --data "name=azure-functions"  \
    --data "config.functionname=" \
    --data "config.appname=AZURE_APPNAME" \
    --data "config.apikey=AZURE_APIKEY"

  • api: either id or name of the API that this plugin configuration will target.

Global plugins

All plugins can be configured using the http://kong:8001/plugins/ endpoint. A plugin which is not associated to any Service, Route or Consumer (or API, if you are using an older version of Kong) is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

form parameterdefaultdescription
nameThe name of the plugin to use, in this case azure-functions
service_idThe id of the Service which this plugin will target.
route_idThe id of the Route which this plugin will target.
enabledtrueWhether this plugin will be applied.
consumer_idThe id of the Consumer which this plugin will target.
api_idThe id of the API which this plugin will target. Note: The API Entity is deprecated in favor of Services since CE 0.13.0 and EE 0.32.
config.functionname

Name of the Azure function to invoke.

config.appname

The Azure app name.

config.hostdomain
optional

azurewebsites.net

The domain where the function resides.

config.routeprefix
optional

/api

Route prefix to use.

config.apikey
optional

The apikey to access the Azure resources. If provided it will be injected as the x-functions-key header.

config.clientid
optional

The clientid to access the Azure resources. If provided it will be injected as the x-functions-clientid header.

config.https_verify
optional

false

Set it to true to authenticate the Azure Functions server.

config.https
optional

true

Use of HTTPS to connect with the Azure Functions server.

config.timeout
optional

600000

Timeout in milliseconds before aborting a connection to Azure Functions server.

config.keepalive
optional

60000

Time in milliseconds for which an idle connection to the Azure Functions server will live before being closed.

Note: If config.https_verify is set as true then the server certificate will be verified according to the CA certificates specified by the lua_ssl_trusted_certificate directive in your Kong configuration.

Demonstration

To demonstrate the plugin, set up the Azure Functions “hello world” function.

  1. In this example we’ll consider the following settings/placeholders, insert your own values here:

     - `<appname>` for the Functions appname
     - `<functionname>` for the function name
     - `<apikey>` for the api key
    
  2. Test your function to make sure it works before adding it to Kong

     curl -i -X GET https://<appname>.azurewebsites.net/api/<functionname>?name=Kong \
          -H "x-functions-key:<apikey>"
    
     HTTP/1.1 200 OK
     ...
     "Hello Kong!"
    
  3. Create a Service on Kong

     $ curl -i -X  POST http://localhost:8001/services/ \
       --data "name=plugin-testing" \
       --data "url=http://dead.end.com"
    
     HTTP/1.1 201 Created
     ...
    
  4. Add a Route to the Service on Kong

     $ curl -i -X  POST http://localhost:8001/services/plugin-testing/routes \
       --data "paths[]=/mytest"
    
     HTTP/1.1 201 Created
     ...
    
  5. Apply the Azure-functions plugin

     $ curl -i -X POST http://localhost:8001/services/plugin-testing/plugins \
         --data "name=azure-functions" \
         --data "config.appname=<appname>" \
         --data "config.functionname=<functionname>" \
         --data "config.apikey=<apikey>"
    
     HTTP/1.1 201 Created
     ...
    
    
  6. Test the Azure Function through Kong (same result as step 2)

     curl -i -X GET http://localhost:8000/mytest?name=Kong
    
     HTTP/1.1 200 OK
     ...
     "Hello Kong!"
    

In this example we’re only passing a query parameter name to the Azure Function. Besides query parameters, also the HTTP method, path parameters, headers, and body will be passed to the Azure Function if provided.


Limitations

Use a fake upstream_url

When using the this plugin, the response will be returned by the plugin itself without proxying the request to any upstream service. This means that whatever url has been set on the Service it will never be used. Although url will never be used, it’s currently a mandatory field in Kong’s data model, so feel free to set a fake value (ie, http://dead.end.com as per the example above) if you are planning to use this plugin. In the future, we will provide a more intuitive way to deal with similar use cases.

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.