Deploy a custom plugin with Docker

In this example, we’ll use a Dockerfile to deploy our plugin, but there are other deployment options.

1. Create a file named Dockerfile at the root of the project:

   touch Dockerfile
   

2. Add the following content to the file:

   FROM kong/kong-gateway:latest
   
   # Ensure any patching steps are executed as root user
   USER root
   
   # Add custom plugin to the image
   COPY ./kong/plugins/my-plugin /usr/local/share/lua/5.1/kong/plugins/my-plugin
   ENV KONG_PLUGINS=bundled,my-plugin
   
   # Ensure kong user is selected for image execution
   USER kong
   
   # Run kong
   ENTRYPOINT ["/entrypoint.sh"]
   EXPOSE 8000 8443 8001 8444
   STOPSIGNAL SIGQUIT
   HEALTHCHECK --interval=10s --timeout=10s --retries=10 CMD kong health
   CMD ["kong", "docker-start"]
   

Use the following command to build the Docker image:

docker build -t kong-gateway_my-plugin:latest-0.0.1 .

When building a Docker image we suggest tagging the image to include information about the Kong Gateway version and a version for the plugin.

You can now use the Kong Gateway quickstart script to run the custom image and further test the plugin.

The quickstart script supports flags that allow you to override the Docker repository (-r), image (-i) and tag (-t).

Use the following command to run the quickstart with the custom image:

curl -Ls https://get.konghq.com/quickstart | \
  bash -s -- -r "" -i kong-gateway_my-plugin -t latest-0.0.1

Once the Kong Gateway is running with the custom image, you can manually test the plugin and validate the behavior.

1. Add a test Gateway Service:

   curl -X POST "http://localhost:8001/services" \
        --json '{
          "name": "example_service",
          "url": "https://httpbin.konghq.com"
        }'
   

2. Enable the plugin, this time with the configuration value:

   curl -X POST "http://localhost:8001/services/example_service/plugins" \
        --json '{
          "name": "my-plugin",
          "config": {
            "response_header_name": "X-CustomHeaderName"
          }
        }'
   

3. Add a Route:

   curl -X POST "http://localhost:8001/services/example_service/routes" \
        --json '{
          "name": "example_route",
          "paths": [
            "/mock"
          ]
        }'
   

4. Send a request to the Route:

   curl -i "http://localhost:8000/mock/anything"
   

   You should see the following response header:

   X-CustomHeaderName: http://httpbin.konghq.com/anything