Azure Functions

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: an entity that makes requests for Kong to proxy; it represents either a user or an external service.
• 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.

Configuration

This plugin is compatible with requests with the following protocols:

• http
• https

This plugin is compatible with DB-less mode.

Enabling the plugin on a Service

$ 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"

plugins:
- name: azure-functions
  service: {service}
  config: 
    functionname: 
    appname: AZURE_APPNAME
    apikey: AZURE_APIKEY

{service} is the id or name of the Service that this plugin configuration will target.

Enabling the plugin on a Route

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

plugins:
- name: azure-functions
  route: {route}
  config: 
    functionname: 
    appname: AZURE_APPNAME
    apikey: AZURE_APIKEY

{route} is the id or name of the Route that this plugin configuration will target.

Enabling the plugin on a Consumer

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

plugins:
- name: azure-functions
  consumer: {consumer}
  config: 
    functionname: 
    appname: AZURE_APPNAME
    apikey: AZURE_APIKEY

{consumer} is the id or username of the Consumer that this plugin configuration will target.

You can combine consumer.id and service.id in the same request, to further narrow the scope of the plugin.

Global plugins

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.

• Using a database, all plugins can be configured using the http://kong:8001/plugins/ endpoint.
• Without a database, all plugins can be configured via the plugins: entry on the declarative configuration file.

Parameters

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

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.