Plugin Development

About 443 wordsAbout 1 min

In Cloud Native Build, a plugin is essentially a Docker image. Below is how to develop an image plugin from scratch using Bash.

This example plugin prints hello world. We assume you have basic knowledge of Docker.

Designing the Plugin

Parameter Design

Design the plugin parameters:

text: The text content to be printed to the console

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

These parameters are passed to the container as environment variables, converted to uppercase with a PLUGIN_ prefix.

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

If parameters are overly complex, consider storing them in a file and loading at runtime, simplifying the design, or splitting into multiple plugins.

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

Corresponding environment variables:

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

Writing the Script

Next, write a Bash script to print the parameters:

#!/bin/sh
echo "$PLUGIN_TEXT"

Building the Plugin Image

The plugin is packaged as a Docker image for distribution. Create a Dockerfile to package the script and set it as the Entrypoint.

FROM alpine

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

ENTRYPOINT /bin/entrypoint.sh

Build the image:

docker build -t cnbcool/hello-world .

Testing the Plugin

Test the plugin locally using docker run, passing parameters via environment variables:

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

Testing Filesystem Access

The plugin can read the build process workspace directory. By default, the build directory is mapped to a plugin directory and set as the workspace:

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

docker push cnbcool/hello-world