Skip to main content
Version: 8.2

Host custom Connectors

This guide explains how to host your own Connectors developed with Connector SDK.

Prerequisites

  • Ensure you have to have a working Camunda cluster in SaaS or Self-Managed.
  • Ensure you have a distribution version of your Connector in the form of "fat" jar file.

For the purpose of this guide, we will be using a generic Connector template as a reference. Clone the repository, and execute mvn clean verify package. This will produce a file called target/connector-template-0.1.0-SNAPSHOT-with-dependencies.jar. In this guide, we will refer this file as connector.jar.

Wiring your Connector with a Camunda cluster

This approach is equivalent to the hybrid mode, except you don't need to override existing Connectors and instead add a new one. You need to have a running Camunda cluster, and a pair of Client ID/Client Secret with Zeebe and Operate scopes. Learn more about how to obtain required credentials.

Run the following command:

docker run --rm --name=CustomConnectorInSaaS \
-v $PWD/connector.jar:/opt/app/connector.jar \
-e ZEEBE_CLIENT_SECURITY_PLAINTEXT=false \
-e ZEEBE_CLIENT_CLOUD_CLUSTER-ID='<YOUR_CLUSTER_ID>' \
-e ZEEBE_CLIENT_CLOUD_CLIENT-ID='<YOUR_CLIENT_ID>' \
-e ZEEBE_CLIENT_CLOUD_CLIENT-SECRET='<YOUR_CLIENT_SECRET>' \
-e ZEEBE_CLIENT_CLOUD_REGION='<YOUR_CLUSTER_REGION>' \
-e CAMUNDA_OPERATE_CLIENT_URL='https://<region>.operate.camunda.io/<cluster-id>' \
camunda/connectors-bundle:<desired-version>

The line -v $PWD/connector.jar:/opt/app/connector.jar binds a volume with your Connector at the path $PWD/connector.jar of you local machine.

Wiring your Connector with Camunda Docker instance (without Keycloak)

This option is applicable if you launch your cluster in a Self-Managed version with Camunda Docker Compose variant without Keycloak.

Run the following command:

docker run --rm --name=CustomConnectorInSMCore \
-v $PWD/connector.jar:/opt/app/connector.jar \
--network=camunda-platform_camunda-platform \
-e ZEEBE_CLIENT_BROKER_GATEWAY-ADDRESS=zeebe:26500 \
-e ZEEBE_CLIENT_SECURITY_PLAINTEXT=true \
-e CAMUNDA_OPERATE_CLIENT_URL=http://operate:8080 \
-e CAMUNDA_OPERATE_CLIENT_USERNAME=demo \
-e CAMUNDA_OPERATE_CLIENT_PASSWORD=demo \
camunda/connectors-bundle:<desired-version>
note

Exact values of the environment variables related to Zeebe, Operate, or network may depend on your own configuration.

Wiring your Connector with Camunda Docker instance (with Keycloak)

This option is applicable if you launch your cluster in a Self-Managed version with Camunda Docker Compose variant with Keycloak.

Run the following command:

docker run --rm --name=CustomConnectorInSMWithKeyCloak \
-v $PWD/connector.jar:/opt/app/connector.jar \
--network=camunda-platform_camunda-platform \
-e ZEEBE_CLIENT_BROKER_GATEWAY-ADDRESS=zeebe:26500 \
-e ZEEBE_CLIENT_SECURITY_PLAINTEXT=true \
-e ZEEBE_CLIENT_ID=<YOUR_ZEEBE_CLIENT_ID> \
-e ZEEBE_CLIENT_SECRET=<YOUR_ZEEBE_CLIENT_SECRET> \
-e ZEEBE_TOKEN_AUDIENCE=zeebe-api \
-e ZEEBE_AUTHORIZATION_SERVER_URL=http://keycloak:8080/auth/realms/camunda-platform/protocol/openid-connect/token \
-e CAMUNDA_OPERATE_CLIENT_KEYCLOAK-URL=http://keycloak:8080 \
-e CAMUNDA_OPERATE_CLIENT_CLIENT-ID=connectors \
-e CAMUNDA_OPERATE_CLIENT_CLIENT-SECRET=<YOUR_OPERATE_CLIENT_SECRET> \
-e CAMUNDA_OPERATE_CLIENT_KEYCLOAK-REALM=<YOUR_KEYCLOAK_OPERATE_REALM> \
-e CAMUNDA_OPERATE_CLIENT_URL=http://operate:8080 \
camunda/connectors-bundle:<desired-version>
note

Exact values of the environment variables related to Zeebe, Operate, Keycloak, or network may depend on your own configuration.

Wiring your Connector with Camunda Helm charts

There are multiple ways to configure a Helm/Kubernetes Self-Managed cluster. Refer to the official guide to learn more.

For the purpose of this section, imagine you installed Helm charts with helm install dev camunda/camunda-platform, and forwarded Zeebe, Operate, and Keycloak ports:

  • kubectl port-forward svc/dev-zeebe-gateway 26500:26500
  • kubectl port-forward svc/dev-operate 8081:80
  • kubectl port-forward svc/dev-keycloak 18080:80

Now, you need to obtain both Zeebe and Connectors' Operate OAuth clients. You can do it with kubectl get secret dev-zeebe-identity-secret -o jsonpath="{.data.*}" | base64 --decode and kubectl get secret dev-connectors-identity-secret -o jsonpath="{.data.*}" | base64 --decode respectively.

Run the following command:

docker run --rm --name=CustomConnectorInSMWithHelm \
-v $PWD/connector.jar:/opt/app/connector.jar \
-e ZEEBE_CLIENT_BROKER_GATEWAY-ADDRESS=host.docker.internal:26500 \
-e ZEEBE_CLIENT_SECURITY_PLAINTEXT=true \
-e ZEEBE_CLIENT_ID=zeebe \
-e ZEEBE_CLIENT_SECRET=<YOUR_ZEEBE_CLIENT_SECRET> \
-e ZEEBE_TOKEN_AUDIENCE=zeebe-api \
-e ZEEBE_AUTHORIZATION_SERVER_URL=http://host.docker.internal:18080/auth/realms/camunda-platform/protocol/openid-connect/token \
-e CAMUNDA_OPERATE_CLIENT_KEYCLOAK-URL=http://host.docker.internal:18080 \
-e CAMUNDA_OPERATE_CLIENT_CLIENT-ID=connectors \
-e CAMUNDA_OPERATE_CLIENT_CLIENT-SECRET=<YOUR_OPERATE_CLIENT_SECRET> \
-e CAMUNDA_OPERATE_CLIENT_KEYCLOAK-REALM=camunda-platform \
-e CAMUNDA_OPERATE_CLIENT_URL=http://host.docker.internal:8081 \
camunda/connectors-bundle:<desired-version>
note

Exact values of the environment variables related to Zeebe, Operate, Keycloak, or network may depend on your own configuration.