diff --git a/plugins/README.md b/plugins/README.md new file mode 100644 index 0000000..1b4cd27 --- /dev/null +++ b/plugins/README.md @@ -0,0 +1,39 @@ +# KrakenD Plugin Examples + +This repository contains examples demonstrating how to build and inject custom plugins into the KrakenD API Gateway. These examples cover three types of plugins: HTTP Client, Handler/Server, and Request/Response Modifier. + +## Overview + +The repository is structured into three main directories, each containing a specific type of plugin: + +### 1. Client Plugin + +The client plugin demonstrates how to create a custom HTTP client that can be integrated into KrakenD. The plugin adds custom logic for handling HTTP requests. + +**More details and instructions can be found in the `client` directory.** + +### 2. Handler/Server Plugin + +The handler/server plugin shows how to create a custom HTTP handler. This plugin allows you to add custom logic to process HTTP requests before they reach the backend. + +**More details and instructions can be found in the `handler` directory.** + +### 3. Request/Response Modifier Plugin + +The request/response modifier plugin illustrates how to create custom request and response modifiers. This plugin can modify the request before it is sent to the backend and the response before it is returned to the client. + +**More details and instructions can be found in the `modifier` directory.** + +## Building the Plugins + +Each plugin directory contains the necessary code and a `Makefile` for building the plugin using Docker. Follow the instructions in each directory's README to build and integrate the plugins into your KrakenD setup. + +## Documentation + +For more information on extending KrakenD with plugins, refer to the official documentation: + +- [HTTP Client Plugins](https://www.krakend.io/docs/extending/http-client-plugins/) +- [HTTP Server Plugins](https://www.krakend.io/docs/extending/http-server-plugins/) +- [Request/Response Modifier Plugins](https://www.krakend.io/docs/extending/plugin-modifiers/) + +This repository aims to provide a starting point for creating your own plugins to extend the functionality of the KrakenD API Gateway. Happy coding! diff --git a/plugins/client/Makefile b/plugins/client/Makefile index 2aef834..afe7bf7 100644 --- a/plugins/client/Makefile +++ b/plugins/client/Makefile @@ -1,6 +1,6 @@ # KrakenD Version VERSION := latest -PLUGINAME := plugin +PLUGINAME := plugins/client # Build KrakenD plugin using the KrakenD docker builder (for running inside docker) amd64: diff --git a/plugins/client/README.md b/plugins/client/README.md new file mode 100644 index 0000000..539971e --- /dev/null +++ b/plugins/client/README.md @@ -0,0 +1,127 @@ +# KrakenD - HTTP Client Plugin Example + +This repository provides an example of how to build and inject a Client Plugin into the KrakenD API Gateway. Follow the steps below to understand how to set up and use the client plugin. + +## Overview + +The client plugin, named `my-client-plugin`, demonstrates how to create a custom HTTP client that can be integrated into KrakenD. The plugin replaces the default HTTP client by adding custom logic before and after the request is processed. + +## File Structure + +- `client.go`: The main plugin code that implements the `RegisterClient` interface. +- `go.mod`: The Go module file. +- `Makefile`: Instructions for building the plugin using Docker. + +## Prerequisites + +- [Go](https://golang.org/dl/) +- Docker +- KrakenD API Gateway (version 2.x) + +## Building the Plugin + +You should build the plugin using the KrakenD Docker builder image. The `Makefile` includes targets for different architectures. + +### Steps + +1. **Clone the Repository**: + + ```bash + git clone https://github.com/krakend/examples.git + cd examples/plugins/client + ``` + +2. **Build for Different Architectures**: + - For **amd64**: + + ```bash + make amd64 + ``` + + - For **arm64**: + + ```bash + make arm64 + ``` + + - For **linux_amd64** (non-docker): + + ```bash + make linux_amd64 + ``` + + - For **linux_arm64** (non-docker): + + ```bash + make linux_arm64 + ``` + + +## Plugin Configuration + +To use the plugin in your KrakenD configuration, add it under the `extra_config` section of your `krakend.json` file. + +### Example Configuration + +```json +{ + "version": 3, + "plugin": { + "pattern": ".so", + "folder": "/etc/krakend/plugins" + }, + "host": ["http://localhost:8080/"], + "debug_endpoint": true, + "endpoints": [ + { + "endpoint": "/example", + "backend": [ + { + "url_pattern": "/__debug/", + "extra_config": { + "plugin/http-client": { + "name": "my-client-plugin", + "my-client-plugin": { + "option": "/some-path" + } + } + } + } + ] + } + ] +} + +``` + +## Logger Interface + +The plugin supports a logger interface to help with debugging and logging messages. + +### Logger Methods + +- `Debug(v ...interface{})` +- `Info(v ...interface{})` +- `Warning(v ...interface{})` +- `Error(v ...interface{})` +- `Critical(v ...interface{})` +- `Fatal(v ...interface{})` + +## Custom Logic + +The `my-client-plugin` adds custom logic by wrapping the default HTTP client. It logs the request details and copies headers, status codes, and body from the backend response to the client response. + +## Usage + +1. **Build the plugin** using the appropriate make target. The plugin will be generated under the `plugins` folder. +2. **Test your KrakenD using Docker**, for instance: +```bash +docker run --rm -it --name krakend -p 8080:8080 -v "$PWD:/etc/krakend" devopsfaith/krakend +``` +3. **Send an example call** +```bash +curl -iG 'http://localhost:8080/example' +``` + + +For more details on client plugins and extending KrakenD, refer to the [official documentation](https://www.krakend.io/docs/extending/http-client-plugins/). diff --git a/plugins/client/client.go b/plugins/client/client.go index eb470f2..8ee4d73 100644 --- a/plugins/client/client.go +++ b/plugins/client/client.go @@ -107,7 +107,7 @@ func (registerer) RegisterLogger(v interface{}) { return } logger = l - logger.Debug(fmt.Sprintf("[PLUGIN: %s] Logger loaded", pluginName)) + logger.Debug(fmt.Sprintf("[PLUGIN: %s] Example client plugin loaded", pluginName)) } type Logger interface { diff --git a/plugins/client/krakend.json b/plugins/client/krakend.json new file mode 100644 index 0000000..fe7b964 --- /dev/null +++ b/plugins/client/krakend.json @@ -0,0 +1,27 @@ +{ + "version": 3, + "plugin": { + "pattern": ".so", + "folder": "/etc/krakend/plugins" + }, + "host": ["http://localhost:8080/"], + "debug_endpoint": true, + "endpoints": [ + { + "endpoint": "/example", + "backend": [ + { + "url_pattern": "/__debug/", + "extra_config": { + "plugin/http-client": { + "name": "my-client-plugin", + "my-client-plugin": { + "option": "/some-path" + } + } + } + } + ] + } + ] +} diff --git a/plugins/handler/Makefile b/plugins/handler/Makefile index 2aef834..e92fa0c 100644 --- a/plugins/handler/Makefile +++ b/plugins/handler/Makefile @@ -1,6 +1,6 @@ # KrakenD Version VERSION := latest -PLUGINAME := plugin +PLUGINAME := plugins/handler # Build KrakenD plugin using the KrakenD docker builder (for running inside docker) amd64: diff --git a/plugins/handler/README.md b/plugins/handler/README.md new file mode 100644 index 0000000..82bd480 --- /dev/null +++ b/plugins/handler/README.md @@ -0,0 +1,126 @@ +# KrakenD - HTTP Handler Plugin Example + +This repository provides an example of how to build and inject a Handler Plugin into the KrakenD API Gateway. Follow the steps below to understand how to set up and use the handler plugin. + +## Overview + +The handler plugin, named `my-handler-plugin`, demonstrates how to create a custom HTTP handler that can be integrated into KrakenD. The plugin replaces the default HTTP handler by adding custom logic before and after the request is processed. + +## File Structure + +- `handler.go`: The main plugin code that implements the `RegisterHandler` interface. +- `go.mod`: The Go module file. +- `Makefile`: Instructions for building the plugin using Docker. + +## Prerequisites + +- [Go](https://golang.org/dl/) +- Docker +- KrakenD API Gateway (version 2.x) + +## Building the Plugin + +You should build the plugin using the KrakenD Docker builder image. The `Makefile` includes targets for different architectures. + +### Steps + +1. **Clone the Repository**: + + ```bash + git clone https://github.com/krakend/examples.git + cd examples/plugins/handler + ``` + +2. **Build for Different Architectures**: + - For **amd64**: + + ```bash + make amd64 + ``` + + - For **arm64**: + + ```bash + make arm64 + ``` + + - For **linux_amd64** (non-docker): + + ```bash + make linux_amd64 + ``` + + - For **linux_arm64** (non-docker): + + ```bash + make linux_arm64 + ``` + + +## Plugin Configuration + +To use the plugin in your KrakenD configuration, add it under the `extra_config` section of your `krakend.json` file. + +### Example Configuration + +```json +{ + "version": 3, + "plugin": { + "pattern": ".so", + "folder": "/etc/krakend/plugins" + }, + "host": ["http://localhost:8080/"], + "debug_endpoint": true, + "endpoints": [ + { + "endpoint": "/example", + "backend": [ + { + "url_pattern": "/__debug/" + } + ] + } + ], + "extra_config": { + "plugin/http-server": { + "name": ["my-handler-plugin"], + "my-handler-plugin": { + "someOption": "some-value" + } + } + } +} + +``` + +## Logger Interface + +The plugin supports a logger interface to help with debugging and logging messages. + +### Logger Methods + +- `Debug(v ...interface{})` +- `Info(v ...interface{})` +- `Warning(v ...interface{})` +- `Error(v ...interface{})` +- `Critical(v ...interface{})` +- `Fatal(v ...interface{})` + +## Custom Logic + +The `my-handler-plugin` adds custom logic by wrapping the default HTTP handler. It logs the configuration option and then processes the request using the default handler. + +## Usage + +1. **Build the plugin** using the appropriate make target. The plugin will be generated under the `plugins` folder. +2. **Test your KrakenD using Docker**, for instance: +```bash +docker run --rm -it --name krakend -p 8080:8080 -v "$PWD:/etc/krakend" devopsfaith/krakend +``` +3. **Send an example call** +```bash +curl -iG 'http://localhost:8080/example' +``` + +For more details on handler plugins and extending KrakenD, refer to the [official documentation](https://www.krakend.io/docs/extending/http-server-plugins/). diff --git a/plugins/handler/handler.go b/plugins/handler/handler.go index 4a52b59..388948c 100644 --- a/plugins/handler/handler.go +++ b/plugins/handler/handler.go @@ -86,7 +86,7 @@ func (registerer) RegisterLogger(v interface{}) { return } logger = l - logger.Debug(fmt.Sprintf("[PLUGIN: %s] Logger loaded", pluginName)) + logger.Debug(fmt.Sprintf("[PLUGIN: %s] Example handler plugin loaded", pluginName)) } type Logger interface { diff --git a/plugins/handler/krakend.json b/plugins/handler/krakend.json new file mode 100644 index 0000000..b9f089f --- /dev/null +++ b/plugins/handler/krakend.json @@ -0,0 +1,27 @@ +{ + "version": 3, + "plugin": { + "pattern": ".so", + "folder": "/etc/krakend/plugins" + }, + "host": ["http://localhost:8080/"], + "debug_endpoint": true, + "endpoints": [ + { + "endpoint": "/example", + "backend": [ + { + "url_pattern": "/__debug/" + } + ] + } + ], + "extra_config": { + "plugin/http-server": { + "name": ["my-handler-plugin"], + "my-handler-plugin": { + "option": "some-value" + } + } + } +} diff --git a/plugins/modifier/Makefile b/plugins/modifier/Makefile index 2aef834..f047e91 100644 --- a/plugins/modifier/Makefile +++ b/plugins/modifier/Makefile @@ -1,6 +1,6 @@ # KrakenD Version VERSION := latest -PLUGINAME := plugin +PLUGINAME := plugins/modifier # Build KrakenD plugin using the KrakenD docker builder (for running inside docker) amd64: diff --git a/plugins/modifier/README.md b/plugins/modifier/README.md new file mode 100644 index 0000000..94c1733 --- /dev/null +++ b/plugins/modifier/README.md @@ -0,0 +1,129 @@ +# KrakenD - Request/Response Modifier Plugin Example + +This repository provides an example of how to build and inject a Request/Response Modifier Plugin into the KrakenD API Gateway. Follow the steps below to understand how to set up and use the modifier plugin. + +## Overview + +The modifier plugin, named `my-modifier`, demonstrates how to create custom request and response modifiers that can be integrated into KrakenD. The plugin allows you to intercept and modify the request before it reaches the backend and the response before it is returned to the client. + +## File Structure + +- `modifier.go`: The main plugin code that implements the request and response modifiers. +- `go.mod`: The Go module file. +- `Makefile`: Instructions for building the plugin using Docker. + +## Prerequisites + +- [Go](https://golang.org/dl/) +- Docker +- KrakenD API Gateway (version 2.x) + +## Building the Plugin + +You should build the plugin using the KrakenD Docker builder image. The `Makefile` includes targets for different architectures. + +### Steps + +1. **Clone the Repository**: + + ```bash + git clone https://github.com/krakend/examples.git + cd examples/plugins/modifier + ``` + +2. **Build for Different Architectures**: + - For **amd64**: + + ```bash + make amd64 + ``` + + - For **arm64**: + + ```bash + make arm64 + ``` + + - For **linux_amd64** (non-docker): + + ```bash + make linux_amd64 + ``` + + - For **linux_arm64** (non-docker): + + ```bash + make linux_arm64 + ``` + + +## Plugin Configuration + +To use the plugin in your KrakenD configuration, add it under the `extra_config` section of your `krakend.json` file. + +### Example Configuration + +```json +{ + "version": 3, + "plugin": { + "pattern": ".so", + "folder": "/etc/krakend/plugins" + }, + "host": ["http://localhost:8080/"], + "debug_endpoint": true, + "endpoints": [ + { + "endpoint": "/example", + "method": "GET", + "extra_config": { + "plugin/req-resp-modifier": { + "name": ["my-modifier-request", "my-modifier-response"], + "my-modifier-request": { + "option": "value" + }, + "my-modifier-response": { + "option": "value" + } + } + }, + "backend": [ + { + "url_pattern": "/__debug/" + } + ] + } + ] +} +``` + +## Logger Interface + +The plugin supports a logger interface to help with debugging and logging messages. + +### Logger Methods + +- `Debug(v ...interface{})` +- `Info(v ...interface{})` +- `Warning(v ...interface{})` +- `Error(v ...interface{})` +- `Critical(v ...interface{})` +- `Fatal(v ...interface{})` + +## Custom Logic + +The `my-modifier` plugin adds custom logic by intercepting and potentially modifying the request and response. The example plugin logs details about the request and response but does not modify them. + +## Usage + +1. **Build the plugin** using the appropriate make target. The plugin will be generated under the `plugins` folder. +2. **Test your KrakenD using Docker**, for instance: +```bash +docker run --rm -it --name krakend -p 8080:8080 -v "$PWD:/etc/krakend" devopsfaith/krakend +``` +3. **Send an example call** +```bash +curl -iG 'http://localhost:8080/example' +``` + +For more details on request/response modifier plugins and extending KrakenD, refer to the [official documentation](https://www.krakend.io/docs/extending/plugin-modifiers/). diff --git a/plugins/modifier/krakend.json b/plugins/modifier/krakend.json new file mode 100644 index 0000000..acda4f0 --- /dev/null +++ b/plugins/modifier/krakend.json @@ -0,0 +1,31 @@ +{ + "version": 3, + "plugin": { + "pattern": ".so", + "folder": "/etc/krakend/plugins" + }, + "host": ["http://localhost:8080/"], + "debug_endpoint": true, + "endpoints": [ + { + "endpoint": "/example", + "method": "GET", + "extra_config": { + "plugin/req-resp-modifier": { + "name": ["my-modifier-request", "my-modifier-response"], + "my-modifier-request": { + "option": "value" + }, + "my-modifier-response": { + "option": "value" + } + } + }, + "backend": [ + { + "url_pattern": "/__debug/" + } + ] + } + ] +} diff --git a/plugins/modifier/modifier.go b/plugins/modifier/modifier.go index d54f9fe..0ad2e68 100644 --- a/plugins/modifier/modifier.go +++ b/plugins/modifier/modifier.go @@ -121,7 +121,7 @@ type config struct { } // parseConfig parses the configuration marshaling and unmarshaling into a struct. -// you can also manually check for fields in the extra conffig map +// you can also manually check for fields in the extra config map func parseConfig(namespace string, extra map[string]interface{}) (*config, error) { ns := fmt.Sprintf("%s-%s", pluginName, namespace) cfgRaw, ok := extra[ns].(map[string]interface{}) @@ -222,7 +222,7 @@ func (registerer) RegisterLogger(v interface{}) { return } logger = l - logger.Debug(fmt.Sprintf("[PLUGIN: %s] Logger loaded", pluginName)) + logger.Debug(fmt.Sprintf("[PLUGIN: %s] Example modifier plugin loaded", pluginName)) } type Logger interface {