Documentation Documentation

Plugin Bundles

A plugin bundle is a ZIP file that contains your custom middleware files and its associated configuration block (the custom_middleware block). The idea behind plugin bundles is to enhance the process of attaching and loading custom middleware.

Requirements

A plugin bundle must include a manifest file (called manifest.json). The manifest file contains important information like the configuration block and the list of files that will be included as part of the bundle file. If a file isn’t specified in the list, it won’t be included in the resulting file, even if it’s present in the current directory.

The manifest file

A sample manifest file looks like this:

    {
      "file_list": [
        "middleware.py",
        "mylib.py"
      ],
      "custom_middleware": {
        "pre": [
          {
            "name": "PreMiddleware"
          }
        ],
        "post": [
          {
            "name": "PostMiddleware"
          }
        ],
        "driver": "python"
      },
      "checksum": "",
      "signature": ""
    }

You may leave the checksum and signature fields empty, the bundler tool will fill these during the build process.

The custom_middleware block follows the standard syntax we use for Tyk plugins. In Tyk Community Edition, where file-based API configuration is used by default, a custom_middleware block is located/added to the API configuration file.

Bundler tool

The bundler tool is a CLI program that lets you generate these plugin bundles. Please note that the generated bundles must be served using your own web server, you may find more information in the last step of this guide.

Bundle security

The bundler tool enables you to sign a bundle using a private key. Tyk configuration may enforce or skip the validation of this signature, depending on the global configuration parameters.

Getting the bundler tool

After installing any of the Tyk Gateway packages, the program will be located in the following path:

  /opt/tyk-gateway/utils/tyk-cli

You may use the full path to call this program, feel free to create a symbolic link or attach its directory to your PATH.

Note for Go developers: If you happen to have a working Go environment setup, you can also fetch the bundler tool using go get:

$ go get github.com/TykTechnologies/tyk-cli

Using the bundler tool

This step will assume that you’re located in your plugin directory and a valid manifest file is present. The bundle tool provides a build command, the most basic usage/syntax looks like this:

  $ tyk-cli bundle build

The resulting file will contain all your specified files and a modified manifest.json with the right checksum and signature (if required), in ZIP format.

Note: By default, the bundles are signed, if no private key is specified, the program will prompt for a confirmation. Use -y to override this (see options below).

The following options are supported:

  • -output: Specifies the name of the bundle file e.g. -output bundle-latest.zip. If this flag is not specified, bundle.zip will be used.
  • -y: Force tool to create unsigned bundle without prompting e.g. $ tyk-cli bundle build -output bundle-latest.zip -y.
  • -key: Specifies the path to your private key which is used to generate signed bundle e.g. $ tyk-cli bundle build -output bundle-latest.zip -key mykey.pem.

Using a rich plugin bundle

Global parameters

To load a bundle plugin the following parameters must be specified in your tyk.conf:

    "enable_bundle_downloader": true,
    "bundle_base_url": "http://my-bundle-server.com/bundles/",
    "public_key_path": "/path/to/my/pubkey",
  • enable_bundle_downloader: Enables the bundle downloader.
  • bundle_base_url: Is a base URL that will be used to download the bundle, in this example we have bundle-latest.zip specified in the API settings, Tyk will fetch the following URL: http://my-bundle-server.com/bundles/bundle-latest.zip (see the next section for details).
  • public_key_path: Sets a public key, this is used for verifying signed bundles, you may omit this if unsigned bundles are used.

Per API / Local parameters

To use a bundle plugin on one of your specified APIs, you must add the following parameter to its configuration block:

  "custom_middleware_bundle": "bundle-latest.zip"

A complete API configuration would look like:

    {
        "name": "Tyk Test API",
        "api_id": "1",
        "org_id": "default",
        "definition": {
            "location": "header",
            "key": "version"
        },
        "auth": {
            "auth_header_name": "authorization"
        },
        "use_keyless": true,
        "version_data": {
            "not_versioned": true,
            "versions": {
                "Default": {
                    "name": "Default",
                    "expires": "3000-01-02 15:04",
                    "use_extended_paths": true,
                    "extended_paths": {
                        "ignored": [],
                        "white_list": [],
                        "black_list": []
                    }
                }
            }
        },
        "proxy": {
            "listen_path": "/quickstart/",
            "target_url": "http://httpbin.org",
            "strip_listen_path": true
        },
        "custom_middleware_bundle": "bundle-latest.zip",
    }

Tyk will fetch http://my-bundle-server.com/bundles/bundle-latest.zip on start. A plugin bundle will be cached after its initial download, if a Tyk reload event occurs, the same contents will be used. If you want to replace it, you must update your API configuration to use a different name and then trigger a reload.

As a suggestion, you may organize this using a Git commit reference or version number, e.g. bundle-e5e6044.zip, bundle-48714c8.zip, bundle-1.0.0.zip, bundle-1.0.1.zip, etc.

Note: Remember to set "enable_coprocess": true in your tyk.conf when using rich plugins!

The bundler tool is an open-source project which you can find on GitHub.