Deploying a CDK connector using APIs

Overview

You can deploy connectors built through CDK using the Connector Deployment API.

Prerequisites - API token

In order to deploy a connector, you will need an RBAC (Role Based Access Control) API token, you can follow this guide on how to create one.

After deploying a connector using an API token, your connector will be owned by that token. This means you will need to use that same token to share that connector with yourself and any other users you want to issue access to.

The command to do this is tray-cdk permissions add. Check the reference here.

Deploying to different regions

Tray operates in 3 regions: US, EU and APAC. You will need to call the deployment API, using the region specific base URL and RBAC token, for each region you wish to use the connector in.

• US: https://api.tray.io/
• EU: https://api.eu1.tray.io/
• APAC: https://api.ap1.tray.io/

Deployment flow

You need to prepare the following two things:

• The endpoint path: https://api.tray.io/cdk/v1/deployments/connectors/${connector-name}/versions/${connector-version}/deploy-connector-from-source
  • The hyphenated connector name is included in the URL path .e.g my-connector-name
  • The connector version number is included in the URL path .e.g 1.0
• The connector itself:
  • has been built with tray-cdk connector build , this will generate a .tray/connector.zip
  • the connector.zip has been base64 encoded
  • the base64 encoded string is set as the value for the connectorSourceCode property in the JSON payload(

You can follow these steps to fulfil the above needs:

1. Build the connector

cd into your connector directory and build the connector, this will generate a `.tray/connector.zip'

cd my-connector
tray-cdk connector build

2. base64 encode the connector zip

base64 encode the connector.zip to a string, set that string as the value for the JSON key connectorSourceCode and write the JSON to a file called payload.json

printf '{"connectorSourceCode": "%s"}' "$(base64 -i .tray/connector.zip)" > payload.json

3. POST to the deployment URL

Make a curl POST request to the deployment URL, including:

• the connector name and version in the path,
• the Tray API token in the headers,
• and the payload.json in the body

curl --location 'https://api.tray.io/cdk/v1/deployments/connectors/{connector-name}/versions/{connector-version}/deploy-connector-from-source' \
--header 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
--header 'Content-Type: application/json' \
--data-binary "@payload.json"

Once your connector code has passed preliminary validation you should recieve a 200 response with a body similar to the one below, this means your connector is now deploying.

{
  "id": "3c5e4a2d-ad3a-58e9-8e2d-eff986f62387", // deployment-id
  "connectorName": "my-connector",
  "connectorVersion": "1.0",
  "deploymentStatus": "Deploying"
}

If you instead recieved a body that also includes "repeatDeployment": true this means a deployment for the same connector is already in progress. Once your current deployment has completed you will be able to deploy again.

{
  "id": "3c5e4a2d-ad3a-58e9-8e2d-eff986f62387", // deployment-id
  "connectorName": "my-connector",
  "connectorVersion": "1.0",
  "deploymentStatus": "Deploying",
  "repeatDeployment": true
}

5. Check deployment status

You can check the status of the ongoing deployment by polling the following GET request, including your Tray API token, the connector name, version and deployment ID (which you get in the response after calling the deployment API like in the above step)

curl --location 'https://api.tray.io/cdk/v1/deployments/connectors/{connector-name}/versions/{connector-version}/{deployment-id}' \
--header 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
--header 'Content-Type: application/json'

You should expect a response similar to the one below with "deploymentStatus": "Deploying" if your connector is currently deploying:

{
  "id": "3c5e4a2d-ad3a-58e9-8e2d-eff986f62387",
  "connectorName": "my-connector",
  "connectorVersion": "1.0",
  "deploymentStatus": "Deploying"
}

Or you will recieve a "deploymentStatus": "Deployed" if it has finished deploying:

{
  "id": "3c5e4a2d-ad3a-58e9-8e2d-eff986f62387",
  "connectorName": "my-connector",
  "connectorVersion": "1.0",
  "deploymentStatus": "Deployed"
}

6. Share connector with emails

Since you used a RBAC token of an API user to deploy the connector, it is technically owned by the API user.

The connector must be shared with you / anyone else before you / them can see it on Tray UI.

Run the following command after replacing the connector-name, connector-version, and the emails of Tray user accounts who need to use the connector:

curl -i -X POST \
  'https://api.tray.io/cdk/v1/permissions/connectors/{connector-name}/versions/{connector-version}/share-with-emails' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "emails": [
      "john.doe@domain.com",
      "jane.doe@domain.com"
    ]
  }'

In the example above, john.doe@domain.com, jane.doe@domain.com would be two users within the API user's Tray org.