For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.9

Host custom connectors

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

The environment variables in this guide are the environment variable form of camunda.client.* properties from the Camunda Spring Boot Starter. For all connection and authentication properties, see Connectors configuration.

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 produces two JAR files in the target/ directory. Use connector-template-0.1.0-SNAPSHOT.jar (the JAR that bundles all dependencies). Ignore original-connector-template-0.1.0-SNAPSHOT.jar (the JAR without dependencies).

In this guide, we will refer to connector-template-0.1.0-SNAPSHOT.jar 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/custom/connector.jar \
-e LOADER_PATH=/opt/custom \
-e CAMUNDA_CLIENT_CLOUD_CLUSTERID='<YOUR_CLUSTER_ID>' \
-e CAMUNDA_CLIENT_AUTH_CLIENTID='<YOUR_CLIENT_ID>' \
-e CAMUNDA_CLIENT_AUTH_CLIENTSECRET='<YOUR_CLIENT_SECRET>' \
-e CAMUNDA_CLIENT_CLOUD_REGION='<YOUR_CLUSTER_REGION>' \
camunda/connectors-bundle:<desired-version>

The line -v $PWD/connector.jar:/opt/custom/connector.jar binds a volume with your connector at the path $PWD/connector.jar of your 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 \
-e CAMUNDA_CLIENT_MODE=self-managed \
-e CAMUNDA_CLIENT_GRPCADDRESS=http://orchestration:26500 \
-e CAMUNDA_CLIENT_RESTADDRESS=http://orchestration:8080 \
camunda/connectors-bundle:<desired-version>
note

Exact values of the environment variables related to the Orchestration Cluster 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 Platform Docker Compose variant with Keycloak. The connectors client and its secret (CONNECTORS_CLIENT_SECRET) are defined in the .env file of the Docker Compose distribution.

Run the following command:

docker run --rm --name=CustomConnectorInSMWithKeyCloak \
-v $PWD/connector.jar:/opt/app/connector.jar \
--network=camunda-platform \
--add-host=host.docker.internal:host-gateway \
-e CAMUNDA_CLIENT_MODE=self-managed \
-e CAMUNDA_CLIENT_GRPCADDRESS=http://orchestration:26500 \
-e CAMUNDA_CLIENT_RESTADDRESS=http://orchestration:8080 \
-e CAMUNDA_CLIENT_AUTH_METHOD=oidc \
-e CAMUNDA_CLIENT_AUTH_CLIENTID=connectors \
-e CAMUNDA_CLIENT_AUTH_CLIENTSECRET=<YOUR_CONNECTORS_CLIENT_SECRET> \
-e CAMUNDA_CLIENT_AUTH_TOKENURL=http://host.docker.internal:18080/auth/realms/camunda-platform/protocol/openid-connect/token \
-e CAMUNDA_CLIENT_AUTH_AUDIENCE=orchestration-api \
camunda/connectors-bundle:<desired-version>
note

Exact values of the environment variables related to the Orchestration Cluster, 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 camunda camunda/camunda-platform --version $HELM_CHART_VERSION, and forwarded the Orchestration Cluster gRPC and REST ports. If you use Keycloak deployed via the Keycloak Operator, also forward the Keycloak port:

kubectl port-forward svc/camunda-zeebe-gateway 26500:26500
kubectl port-forward svc/camunda-zeebe-gateway 8080:8080
# Only if using Keycloak
kubectl port-forward svc/keycloak-service 18080:18080

Now, you need to obtain the secret of the connectors OAuth client. You can do it with kubectl get secret camunda-connectors-identity-secret -o jsonpath="{.data.*}" | base64 --decode.

Run the following command:

docker run --rm --name=CustomConnectorInSMWithHelm \
-v $PWD/connector.jar:/opt/app/connector.jar \
-e CAMUNDA_CLIENT_MODE=self-managed \
-e CAMUNDA_CLIENT_GRPCADDRESS=http://host.docker.internal:26500 \
-e CAMUNDA_CLIENT_RESTADDRESS=http://host.docker.internal:8080 \
-e CAMUNDA_CLIENT_AUTH_METHOD=oidc \
-e CAMUNDA_CLIENT_AUTH_CLIENTID=connectors \
-e CAMUNDA_CLIENT_AUTH_CLIENTSECRET=<YOUR_CONNECTORS_CLIENT_SECRET> \
-e CAMUNDA_CLIENT_AUTH_TOKENURL=http://host.docker.internal:18080/auth/realms/camunda-platform/protocol/openid-connect/token \
-e CAMUNDA_CLIENT_AUTH_AUDIENCE=orchestration-api \
camunda/connectors-bundle:<desired-version>
note

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

Interested in creating a custom connector? Review the related Camunda Academy courses on creating a custom inbound connector or creating a custom outbound connector.