In Cloud Native Build, a plugin is essentially a Docker image. Here we'll demonstrate how to develop an image plugin from scratch using Bash. This plugin's functionality is to print hello world. This guide should provide you with a clear approach to creating your own plugins. We assume you already have some basic knowledge of Docker.

Designing the Plugin

Parameter Design

The first step is to design the parameters required by the plugin:

• text: The text content to be printed to the console

main:
  push:
    - stages:
        - name: hello world
          image: cnbcool/hello-world
          settings:
            text: hello world

These input parameters will be passed to the container as environment variables, with the difference that they will be converted to uppercase and prefixed with PLUGIN_.

The above parameters will be transformed into the following environment variables:

PLUGIN_TEXT="hello world"

Supported Parameter Types

Parameter types support string, number, boolean, one-dimensional array, and plain object.

Where:

• Arrays will be split by commas , when passed to the container
• Plain objects will be converted to JSON strings when passed to the container

For example:

main:
  push:
    - stages:
        - name: hello world
          image: cnbcool/hello-world
          settings:
            boolean: true
            number: 123
            array: [hello, world]
            map:
              key: value

The parameter values will be transformed into the following environment variables:

PLUGIN_BOOLEAN='true'
PLUGIN_NUMBER='123'
PLUGIN_ARRAY='hello,world'
PLUGIN_MAP='{"key":"value"}'

For particularly complex parameter values, they can be stored in a file and loaded when the plugin runs. If you encounter extremely complex parameter values, it's often not a format issue - you should simplify these parameters or split them into multiple plugins.

Writing the Script

Next, write a Bash script to print the parameters, as shown below:

#!/bin/sh
echo "$PLUGIN_TEXT"

Building the Plugin Image

The plugin will be packaged as a Docker image for distribution and use. Therefore, we need to create a Dockerfile to package our previously written script, and set it as the Entrypoint.

FROM alpine

ADD entrypoint.sh /bin/
RUN chmod +x /bin/entrypoint.sh

ENTRYPOINT /bin/entrypoint.sh

Build your image:

docker build -t cnbcool/hello-world .

Testing the Plugin

You should test your plugin locally, using docker run to execute the plugin and pass parameters via environment variables:

docker run --rm \
  -e PLUGIN_TEXT="hello world" \
  cnbcool/hello-world

Testing Filesystem Access

The plugin has permission to read your build process workspace directory. It will map the build directory to a specific directory in the plugin by default and set this directory as the workspace:

docker run --rm \
  -e PLUGIN_TEXT="hello world" \
  -v $(pwd):$(pwd) \
  -w $(pwd) \
  cnbcool/hello-world

Exporting Variables

If the plugin needs to return results and export them as variables for subsequent tasks, refer to exports

Publishing the Plugin

A plugin is a Docker image, so publishing a plugin means pushing the image to an image registry.

You can publish to the built-in Artifact Registry of Cloud Native Build.

For globally available plugins, you can also publish to Docker Hub.

Pushing the Image

docker push cnbcool/hello-world