Plugin Development

In Cloud Native Build, a plugin is a Docker image. Below we introduce how to develop an image plugin from scratch using Bash. The function of this plugin is to print hello world. This content should provide you with a clear idea for creating your own plugins. We assume here that you already know some basic knowledge of Docker.

• Designing Plugins
  • Parameter Design
  • Supported Parameter Types
• Write Scripts
• Build Plugin Image
• Test Plugin
  • Test File System Reading
• Export Variables
• Publish Plugin
  • Publish Image

Designing Plugins

Parameter Design

The first step should be to design the parameters needed by the plugin:

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

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

These input parameters will be passed to the container in the form of environment variables, the difference is, they will become uppercase and will be prefixed with PLUGIN_.

The above input parameters will be converted to the following environment variables:

PLUGIN_TEXT="hello world"

Supported Parameter Types

Parameter types support string, numeric, boolean, one-dimensional array, ordinary object

Among them:

• Arrays will be separated by English commas , when passed to the container
• Ordinary objects will be converted to JSON strings when passed to the container

For example:

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

The uploaded parameter values will be converted to the following environment variables:

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

Especially complex parameter values can be stored in a file and loaded when the plugin runs. If you encounter exceptionally complex parameter values, it is often not a matter of format that can solve it, you should simplify these parameters, or make them into multiple plugins.

Write Scripts

The next step is to write a Bash script that prints parameters, as follows:

#!/bin/sh
echo "$PLUGIN_TEXT"

Build Plugin Image

The plugin will be packaged into a Docker image for distribution and use. Therefore, you need to create a Dockerfile to package the script we wrote earlier, and set it as Entrypoint.

FROM alpine

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

ENTRYPOINT /bin/entrypoint.sh

Build your image:

docker build -t cnb/hello-world .

Test Plugin

You should test your plugin locally, you can use docker run to run the plugin, and pass the parameters in through environment variables:

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

Test File System Reading

The plugin has the permission to read your build process workspace directory, it will default to map the build directory to a certain directory of the plugin, and then set this directory as the workspace:

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

Export Variables

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

Publish Plugin

A plugin is a Docker image, so publishing a plugin means you need to publish the image to an image source.

For globally available plugins, it is recommended to publish to Docker Hub.

For plugins that are only available within the enterprise, it is recommended to publish to the enterprise's private Docker Registry.

Publish Image

docker push cnb/hello-world