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"
jarfile.
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>
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>
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>
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.