From d1536955c91dbd473a54c58ab4ed2f7705176be0 Mon Sep 17 00:00:00 2001 From: Igor Petrov <108870003+igpetrov@users.noreply.github.com> Date: Wed, 28 Aug 2024 10:30:14 +0300 Subject: [PATCH] Guide for DB interceptor plugins (#4171) * docs: added ES/OS plugin doc * docs: added entry to sidebars * fix: fixed tab * restructure page organization, move to guides * chore: updated final properties examples * revert: config * docs: added troubleshooting guide * style/grammar edits --------- Co-authored-by: Cole Garbo --- .../guides/configure-db-custom-headers.md | 215 ++++++++++++++++++ optimize_sidebars.js | 5 +- sidebars.js | 1 + 3 files changed, 220 insertions(+), 1 deletion(-) create mode 100644 docs/self-managed/setup/guides/configure-db-custom-headers.md diff --git a/docs/self-managed/setup/guides/configure-db-custom-headers.md b/docs/self-managed/setup/guides/configure-db-custom-headers.md new file mode 100644 index 0000000000..0d591393e8 --- /dev/null +++ b/docs/self-managed/setup/guides/configure-db-custom-headers.md @@ -0,0 +1,215 @@ +--- +id: configure-db-custom-headers +title: "Configure custom headers" +sidebar_label: "Configure custom headers" +description: "Learn how to configure DB client custom headers" +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +Custom HTTP headers can be added to a component's Elasticsearch and OpenSearch HTTP clients by creating a new Java plugin, and adding the plugin to your Camunda 8 Self-Managed installation. Using custom HTTP headers may be helpful for adding authentication, tracking, or debugging to your database requests. + +## Create the Java plugin + +### Add the dependency + +Add the following dependency to a new Java project: + + + + + +```xml + + io.camunda + camunda-search-plugins + ${version.camunda-search-plugins} + +``` + + + + + +```yml +implementation "io.camunda:camunda-search-plugins:${version.camunda-search-plugins}" +``` + + + + +### Write your custom header + +Once the dependency is added to your project, write your plugin by implementing the `DatabaseCustomHeaderSupplier` interface (provided by the +`camunda-search-plugins` package). + +The following example implements the `DatabaseCustomHeaderSupplier` interface, and uses it to return a custom authentication token and UUID: + +```java +package com.myplugin; + +import io.camunda.plugin.search.header.CustomHeader; +import io.camunda.plugin.search.header.DatabaseCustomHeaderSupplier; +import java.util.UUID; + +public class MyCustomHeaderPlugin implements DatabaseCustomHeaderSupplier { + + public static final String CUSTOM_TOKEN_PLUGIN = "X-Custom-Auth-Token"; + + @Override + public CustomHeader getElasticsearchCustomHeader() { + return new CustomHeader(CUSTOM_TOKEN_PLUGIN, UUID.randomUUID().toString()); + } + +} +``` + +### Build your project + +Build your project with all dependencies included, and copy the resulting JAR file somewhere it can be easily accessed. This JAR file will be required by your Camunda installation. + +## Add the plugin to your self-managed installation + +To use your new plugin, it must be added to your Camunda 8 Self-Managed installation. + +### Mount the plugin + +For each container, mount your plugin's JAR file inside the container's file system. For more information, see the +[Docker](https://docs.docker.com/engine/storage/volumes/) or [Kubernetes](https://kubernetes.io/docs/concepts/storage/volumes/) documentation. + +### Configure components + +Include the plugin parameters in each component's `application.yaml`, or pass them to the component as environment variables. For more information, see how to [configure components using Helm charts](/self-managed/operational-guides/application-configs.md). + +The following examples add the new `my-plugin` JAR to the `application.yaml` for Zeebe, Operate, and Tasklist: + +#### Configure Zeebe Exporter + + + + + +```yaml +- ZEEBE_BROKER_EXPORTERS_ELASTICSEARCH_ARGS_INTERCEPTORPLUGINS_PLG1_ID=my-plugin +- ZEEBE_BROKER_EXPORTERS_ELASTICSEARCH_ARGS_INTERCEPTORPLUGINS_PLG1_CLASSNAME=com.myplugin.MyCustomHeaderPlugin +- ZEEBE_BROKER_EXPORTERS_ELASTICSEARCH_ARGS_INTERCEPTORPLUGINS_PLG1_JARPATH=/usr/local/plugin/plg.jar +``` + + + + + +```yaml +- ZEEBE_BROKER_EXPORTERS_OPENSEARCH_ARGS_INTERCEPTORPLUGINS_PLG1_ID=my-plugin +- ZEEBE_BROKER_EXPORTERS_OPENSEARCH_ARGS_INTERCEPTORPLUGINS_PLG1_CLASSNAME=com.myplugin.MyCustomHeaderPlugin +- ZEEBE_BROKER_EXPORTERS_OPENSEARCH_ARGS_INTERCEPTORPLUGINS_PLG1_JARPATH=/usr/local/plugin/plg.jar +``` + + + + +#### Configure Operate Importer + + + + + +```yaml +- CAMUNDA_OPERATE_ZEEBEELASTICSEARCH_INTERCEPTORPLUGINS_PLG1_ID=my-plugin +- CAMUNDA_OPERATE_ZEEBEELASTICSEARCH_INTERCEPTORPLUGINS_PLG1_CLASSNAME=com.myplugin.MyCustomHeaderPlugin +- CAMUNDA_OPERATE_ZEEBEELASTICSEARCH_INTERCEPTORPLUGINS_PLG1_JARPATH=/usr/local/plugin/plg.jar +- CAMUNDA_OPERATE_ELASTICSEARCH_INTERCEPTORPLUGINS_PLG1_ID=my-plugin +- CAMUNDA_OPERATE_ELASTICSEARCH_INTERCEPTORPLUGINS_PLG1_CLASSNAME=com.myplugin.MyCustomHeaderPlugin +- CAMUNDA_OPERATE_ELASTICSEARCH_INTERCEPTORPLUGINS_PLG1_JARPATH=/usr/local/plugin/plg.jar +``` + + + + + +```yaml +- CAMUNDA_OPERATE_ZEEBEOPENSEARCH_INTERCEPTORPLUGINS_PLG1_ID=my-plugin +- CAMUNDA_OPERATE_ZEEBEOPENSEARCH_INTERCEPTORPLUGINS_PLG1_CLASSNAME=com.myplugin.MyCustomHeaderPlugin +- CAMUNDA_OPERATE_ZEEBEOPENSEARCH_INTERCEPTORPLUGINS_PLG1_JARPATH=/usr/local/plugin/plg.jar +- CAMUNDA_OPERATE_OPENSEARCH_INTERCEPTORPLUGINS_PLG1_ID=my-plugin +- CAMUNDA_OPERATE_OPENSEARCH_INTERCEPTORPLUGINS_PLG1_CLASSNAME=com.myplugin.MyCustomHeaderPlugin +- CAMUNDA_OPERATE_OPENSEARCH_INTERCEPTORPLUGINS_PLG1_JARPATH=/usr/local/plugin/plg.jar +``` + + + + +#### Configure Tasklist Importer + + + + + +```yaml +- CAMUNDA_TASKLIST_ZEEBEELASTICSEARCH_INTERCEPTORPLUGINS_PLG1_ID=my-plugin +- CAMUNDA_TASKLIST_ZEEBEELASTICSEARCH_INTERCEPTORPLUGINS_PLG1_CLASSNAME=com.myplugin.MyCustomHeaderPlugin +- CAMUNDA_TASKLIST_ZEEBEELASTICSEARCH_INTERCEPTORPLUGINS_PLG1_JARPATH=/usr/local/plugin/plg.jar +- CAMUNDA_TASKLIST_ELASTICSEARCH_INTERCEPTORPLUGINS_PLG1_ID=my-plugin +- CAMUNDA_TASKLIST_ELASTICSEARCH_INTERCEPTORPLUGINS_PLG1_CLASSNAME=com.myplugin.MyCustomHeaderPlugin +- CAMUNDA_TASKLIST_ELASTICSEARCH_INTERCEPTORPLUGINS_PLG1_JARPATH=/usr/local/plugin/plg.jar +``` + + + + + +```yaml +- CAMUNDA_TASKLIST_ZEEBEOPENSEARCH_INTERCEPTORPLUGINS_PLG1_ID=my-plugin +- CAMUNDA_TASKLIST_ZEEBEOPENSEARCH_INTERCEPTORPLUGINS_PLG1_CLASSNAME=com.myplugin.MyCustomHeaderPlugin +- CAMUNDA_TASKLIST_ZEEBEOPENSEARCH_INTERCEPTORPLUGINS_PLG1_JARPATH=/usr/local/plugin/plg.jar +- CAMUNDA_TASKLIST_OPENSEARCH_INTERCEPTORPLUGINS_PLG1_ID=my-plugin +- CAMUNDA_TASKLIST_OPENSEARCH_INTERCEPTORPLUGINS_PLG1_CLASSNAME=com.myplugin.MyCustomHeaderPlugin +- CAMUNDA_TASKLIST_OPENSEARCH_INTERCEPTORPLUGINS_PLG1_JARPATH=/usr/local/plugin/plg.jar +``` + + + + +## Troubleshooting + +### Exception: Unknown type of interceptor plugin or wrong class specified + +This exception means that the incorrect class was specified in the `CLASSNAME` property. There are several causes that +might lead to this exception: + +1. The class with such name or package does not exist +2. The class does not implement the required SDK interface +3. The class is inner, `static`, or `final` + +To solve this, make sure: + +1. You use the latest Search Plugins SDK +2. Your classes implement correct SDK interfaces +3. The plugin class is `public` and not `final` + +### Exception: Failed to load interceptor plugin due to exception + +Usually related to incorrect JAR loading. Please make sure that the path to your plugin JAR file is correct, and +the application has access to read it. Also check that the JAR is correct and contains the required dependencies. To check the +content of the JAR file, you can use the following command: `jar xf .jar`. diff --git a/optimize_sidebars.js b/optimize_sidebars.js index 18c0173a86..48f5842874 100644 --- a/optimize_sidebars.js +++ b/optimize_sidebars.js @@ -2246,6 +2246,10 @@ module.exports = { "Using AWS managed OpenSearch", "self-managed/setup/guides/using-existing-opensearch/" ), + docsLink( + "Configure DB client custom headers", + "self-managed/setup/guides/configure-db-custom-headers/" + ), docsLink( "Connect to an OpenID Connect provider", "self-managed/setup/guides/connect-to-an-oidc-provider/" @@ -2328,7 +2332,6 @@ module.exports = { "Configure multi-tenancy", "self-managed/operational-guides/configure-multi-tenancy/" ), - { "Backup and restore": [ docsLink( diff --git a/sidebars.js b/sidebars.js index 623f32670c..12c3542239 100644 --- a/sidebars.js +++ b/sidebars.js @@ -948,6 +948,7 @@ module.exports = { "self-managed/setup/guides/using-existing-keycloak", "self-managed/setup/guides/using-existing-elasticsearch", "self-managed/setup/guides/using-existing-opensearch", + "self-managed/setup/guides/configure-db-custom-headers", "self-managed/setup/guides/connect-to-an-oidc-provider", "self-managed/setup/guides/air-gapped-installation", "self-managed/setup/guides/running-custom-connectors",