Skip to main content
Version: Release 24.3

Build Custom Container Plugin using Go SDK

Digital.ai Release brings in the new integration SDK experience for you to run tasks as containers, using any language or third-party library.

This quick-start helps you learn how to build custom container plugins using the Go SDK.

Note: In this quick-start guide, you will learn how to use Docker Desktop with Kubernetes enabled to create a local Kubernetes cluster on your computer. This setup uses a local development environment for building, installing, and running your first container-based task. For production use, the steps to use the template repository, develop a plugin, build a plugin, and install the plugin will be the same. However, to run the container-based tasks, you will set up Digital.ai Release with the Runner in a Kubernetes cluster. For more information, see Run Digital.ai Release Runner on Kubernetes cluster.

Prerequisites​

  • A computer that runs Windows, macOS, or Linux. For macOS-based computers with the M1 or M2 chips, macOS Ventura is needed. Additionally, enable Rosetta in Docker Desktop from the Feature in development section.
  • Ensure that your internal memory meets the following requirements for running Docker effectively:
    • Minimum: 8GB of internal memory (RAM)
    • Recommended: 16GB of internal memory (RAM) for optimal performance
  • You must have Administrator privileges on your system, allowing you to edit the /etc/hosts file.
  • Docker Desktop
  • Digital.ai Release
  • GitHub as the repository that hosts the Digital.ai Release Integration Go SDK template to build the plugin
  • Go 1.21
  • Use an IDE of your choice.

Here's a detailed step-by-step.

Step 1 — Set up GitHub Project for Building Container Plugins​

In this step, you will set up a new Git project that will contain the project files for building container-based integration plugins.

Step 1.1 — Create a New Repository​

Create a duplicate of the Digital.ai Release Integration Go SDK template project to start developing your own container-based integration plugins.

  1. In GitHub, go to the Digital.ai Release Integration Go SDK template.
  2. Click Use this template > Create a new repository to create a new repository with the contents of this sample template.
  3. Provide a repository name, based on the naming convention.

The best practice is to use the following naming convention to develop container-based integration plugins:

[publisher]-release-[target]-integration

Sample:

acme-release-workshop-integration

For more details, see how to Create a Git repository.

Step 1.2 — Checkout the New Repository​

Open the terminal and navigate to a directory where you want to store your project, and run the following command:

git clone https://github.com/digital-ai/acme-release-workshop-integration.git

The repository is cloned in your local system.

Step 1.3 — Configure the project.properties file​

Navigate to the project.properties file in the repository, and update as follows:

PLUGIN=acme-release-workshop-integration

Note: This is the name of the repository you created in Step 1.1.

Step 2 — Run a Development Instance of Digital.ai Release​

In this step, you will learn how to set up a development environment with Release running on Docker using the Template repository.

  1. Navigate to the dev-environment folder in the cloned repository, and start the Release and Runner environments by running the following command:
docker compose up -d --build
  1. Once the docker command is executed, the containers will start. Go to Docker Desktop and check the logs of the dev-environment-digitalai-release-1 container for it to display the following lines:
2023-04-26 11:48:21 2023-04-26 09:48:21.377 [main] {activemq.broker=embedded-broker} INFO  c.x.x.s.jetty.JettyServerListener - Digital.ai Release has started.
2023-04-26 11:48:21 2023-04-26 09:48:21.378 [main] {activemq.broker=embedded-broker} INFO  c.x.x.s.jetty.JettyServerListener - You can now point your browser to http://host.docker.internal:5516/
  1. Open a browser, go to http://localhost:5516. The Digital.ai Release login screen opens.
  2. Log in with username=admin and password=admin.

At the end of this step, you would have started Release and Runner. Additionally, a container registry is created, which will be used in the next steps.

Step 3 — Configure your hosts file​

Note: This set up will vary for a production environment based on your container registry.

For all the containers to find each other, the easiest way is to use the hosts file.

Note: You need sudo or Admin privileges to perform this step based on the OS.

To allow the Release server to locate the container images of the integration being developed, a registry is set up within Docker for the development environment. You must include the address of this registry in your local machine's host's file.

For Unix / macOS

Add the following lines in the hosts file in the following location: /etc/hosts

127.0.0.1 digitalai.release.local
127.0.0.1 container-registry
127.0.0.1 host.docker.internal

For Windows

Add the following lines in the hosts file in the following location: C:\Windows\System32\drivers\etc\hosts

127.0.0.1 digitalai.release.local
127.0.0.1 container-registry
127.0.0.1 host.docker.internal

Step 4 — Import Go SDK into your Project​

To import the Go SDK, navigate to the project directory and run the following command:

go get github.com/digital-ai/release-integration-sdk-go

Step 5 — Set up IDE for Coding​

You can set up an IDE of your choice. However, we have provided some additional setup information on VS Code to ease the setup.

Step 5.1 — Enable Schema on VS Code​

Before running the type-definitions.yaml file, learn how to configure VS Code to have code completion on type-definitions.yaml. The JSON schema is available in the following location: type-definition-schema-23.1.x.json.

Since the new schema is not in the Schema store, you must register it on VS Code.

  1. Open VS Code and go to the Extensions view.
  2. Search for the YAML extension that provides the schema you want to use and install it.
  3. Go to File > Preferences > Settings to open the Settings page and search for YAML: Schemas.
  4. Click Edit in settings.json. The settings.json file opens. Tip: If the yaml.schemas object does not exist, you have to create one.
  5. This property represents a key-value pair. The key is the absolute path to the schema file on your system. The value is a global expression that specifies the files that the schema will be applied to.

Here's an example:

    "yaml.schemas": {
        "/Users/demo/Code/xl-platform/engine/local-booter/src/main/resources/type-definition-schema-23.1.x.json": "type-definitions.yaml"
    },
  1. Save this file and reopen VS Code to complete the process.

Step 6 — Develop a Custom Container Plugin​

Define and code a new task, based on the Hello example task.

Step 6.1 — Define a Type in type-definitions.yaml​

Firstly, you will define the name and properties of the task, so that Digital.ai Release can handle it.

Note: The type-definitions.yaml file is newly introduced to replace synthetic.xml for creating plugins. This quick-start is explained using type-definitions.yaml.

  1. Navigate to the type-definitions.yaml file.
  2. Add a task type to type-definitions.yaml file.
  3. Add a task structure with input parameters to cmd/commands.go file.
  4. Add a task type to constants and command factory in cmd/factory.go file.
  5. Add the FetchResult() implementation of the command in the cmd/executors.go file and add the task logic.

Note: Although, the task logic is the FetchResult() method, the best practice is to create a new file for each new task.

Step 6.2 — Add Logic to the Task​

Based on type-definitions.yaml file, the Go SDK will scan the src directory for Go classes with the same name as the type definition.

To add abort logic for a task:

  1. Define the abort command for a task in cmd/factory.go file. Use the following syntax:
command.AbortCommand(NAME_OF_EXISTING_COMMAND): func...

For better understanding, see cmd/example/Hello.go. 2. In the cmd/commands.go file, define a structure that will hold the necessary data for abort execution. 3. In the cmd/executors.go file, define a method on the newly created structure, which implements the FetchResult() method.

Note: Make sure to include context.Context in your methods as it is required because of the changes made to support the abort functionality.

Step 7 — Build and Run Container-based Plugin​

A Container-based integration plugin consists of two parts:

  • The metadata in the plugin zip file. You will install this file into Digital.ai Release.
  • The container image containing the code that will be executed when a task runs.

Learn how to package a plugin and publish the image.

  1. Configure the plugin and registry details in the project.properties file.
  2. Open the terminal and navigate to the root directory of project, and run the required command:

For Unix/mac OS run the following commands:

  • Builds the zip, image and pushes the image to the configured registry 
    sh build.sh
  • Builds the zip 
    sh build.sh --zip
  • Builds the image and pushes the image to the configured registry 
    sh build.sh --image

For Windows run the following commands:

  • Builds the zip, image and pushes the image to the configured registry 
    build.bat
  • Builds the zip 
    build.bat --zip
  • Builds the image and pushes the image to the configured registry 
    build.bat --image

Step 8 — Install Plugin zip into Release​

There are two ways to install the plugin into Release.

Install plugin via commandline​

Update the Release server details in .xebialabs/config.yaml

Run the command for Unix / macOS:

sh build.sh --upload

Run the command for Windows:

build.bat --upload

The above command builds the zip and image and uploads the zip to the release server.

Install plugin via Release server UI​

In the Release UI, use the Plugin Manager interface to upload the zip from build. The zip takes the name of the project, for example release-integration-template-go-0.0.1.zip.

  1. On the top-right corner, click Settings > Manage plugins.
  2. In the left-navigation pane, click Installed plugins.
  3. Click Upload to upload the plugin file from your local machine.

Note: Browse the build directory of the acme-release-workshop-integration project in your local system. The plugin zip takes the name of the project specified in project.properties file. For example, acme-release-workshop-integration-0.0.1.zip.

  1. Select the required file and click Upload. The plugin is now available in your Release instance.

Step 9 — Run your First Custom Container Plugin​

  1. Create a template in Release.
  2. Select the newly built Go Container Example: Hello container task and add to the template.
  3. Start a Release to run the task.

Note: If you change the task logic in Go files, just run the build script with --image flag to update the plugin image. If you change type-definitions.yaml, run the plugin script with --upload flag to update plugin types on Release. No restart is required.