Plugin creation guide#
So you wanna build a BitOps plugin, eh? Follow along for how to do it locally!
1. Create a plugin repo#
cd /path/to/bitops-plugins
mkdir my-plugin
cd my-plugin
Note: If the plugin needs to install tools, you will need to build and run a local version of BitOps. The first portion of this guide assumes the install.sh script DOES NOT needs to be run. For more information about how to set up BitOps for local development with a plugin that requires an installation, skip to step 5 below.
For this example, we'll keep to a really simple plugin.
To start with, create a file called bitops.schema.yaml
and add the following content.
duplicate-environment:
type: object
properties:
# CLI properties will be composed into a string with
# arguments and exported as "${BITOPS_MY_PLUGIN_CLI}"
cli:
type: object
properties:
# positional argument, because no `parameter` is set
# ex: "run"
command:
type: string
default: run
required: true
# typical cli argument
# ex: "--key=value"
key:
parameter: key
type: string
# cli flag, added if value is set to `true`
# ex: "--bar"
bar:
parameter: bar
type: boolean
default: true
options:
type: object
properties:
foo:
type: string
export_env: DUPLICATE_ENVIRONMENT_FOO
required: true
default: foo_value
Next, create a simple deploy.sh
script. This script does some checks and shows how to use some of the system BITOPS_
available environment variables then outputs configuration values defined by the bitops.schema.yaml
in cli
and options
sections.
#!/bin/bash
set -ex
echo "Running Duplicate Environment Plugin deployment script..."
# vars
export BITOPS_SCHEMA_ENV_FILE="$BITOPS_OPSREPO_ENVIRONMENT_DIR/ENV_FILE"
if [ ! -d "$BITOPS_OPSREPO_ENVIRONMENT_DIR" ]; then
echo "No duplicate-environment directory. Skipping."
exit 0
fi
echo "Deploying duplicate-environment..."
if [ ! -f "$BITOPS_SCHEMA_ENV_FILE" ]; then
echo "No duplicate-environment ENV file found"
else
source "$BITOPS_SCHEMA_ENV_FILE"
fi
cd $BITOPS_OPSREPO_ENVIRONMENT_DIR
echo "Listing contents of duplicate-environment Root: $BITOPS_OPSREPO_ENVIRONMENT_DIR"
ls -al .
echo "Running the plugin CLI:"
# Expected result: "plugin_command run --key=value --bar"
echo plugin_command "${BITOPS_MY_PLUGIN_CLI}"
echo "Options:"
echo "DUPLICATE_ENVIRONMENT_FOO"
# Expected result: "foo_value"
echo "$DUPLICATE_ENVIRONMENT_FOO"
Note: Much of the above is best practice boilerplate and is not strictly necessary.
Finally, create a plugin.config.yaml
to configure how BitOps uses the plugin.
plugin:
deployment:
language: bash
deployment_script: deploy.sh
core_schema_parsing: true
life_cycle_scripts: true
2. Create an ops repo for testing#
cd /path/to/ops-repos
mkdir duplicate-environment
cd duplicate-environment
From there, you'll need to create an environment with a directory that matches your tool.
mkdir -p /path/to/ops-repo/plugin-no-install/duplicate-environment
Populate the tool's bitops.config.yaml
based on the schema defined above:
/path/to/ops-repo/plugin-no-install/duplicate-environment/bitops.config.yaml
duplicate-environment:
cli:
command: run
key: value
bar: true
options:
foo: baz
3. Test your plugin#
3.1. BitOps-level BitOps Config#
To test your plugin, you'll need BitOps to run with a BitOps-level BitOps config that has your plugin defined in the deployments
.
Create a bitops.config.yaml
somewhere (say: /path/to/ops-repo/plugin-no-install/duplicate-environment/bitops-level/bitops.config.yaml
), and add a plugins
and deployments
reference to your plugin:
bitops:
fail_fast: true
logging:
level: DEBUG # Sets the logging level
color:
enabled: true # Enables colored logs
plugins:
duplicate-environment: {}
deployments:
duplicate-environment:
plugin: duplicate-environment
NOTE:
plugins.duplicate-environment
is empty because it's only used as a reference fordeployments.duplicate-environment
.
3.2. Run your test#
To run BitOps against a local plugin, you'll need to mount the plugin to the location BitOps expects plugins to be.
docker run --rm --name bitops \
-e BITOPS_ENVIRONMENT="duplicate-environment" \
-v /path/to/bitops:/opt/bitops \
-v /path/to/ops-repo/plugin-no-install:/opt/bitops_deployment \
-v /path/to/bitops-level/bitops.config.yaml:/opt/bitops/bitops.config.yaml \
-v /opt/bitops/scripts/plugins/terraform \
-v /path/to/bitops-plugins/duplicate-environment:/opt/bitops/scripts/installed-plugins/duplicate-environment \
bitovi/bitops:dev
Note: To see the full code so far, see docs/examples/plugin-examples/plugin-no-install/duplicate-environment
4. Handling the Plugin Install Script#
If your new plugin needs to run some install scripts (e.g. to install a CLI tool, for example), you'll need to build your own version of BitOps locally.
Note: For more information on how to do this, see plugins.
4.1. Update the Plugin to Add an Install Script#
Add the install
configuration to your plugin's plugin.config.yaml
plugin:
# this plugin has install instructions
install:
language: bash
install_script: install.sh
deployment:
language: bash
deployment_script: deploy.sh
core_schema_parsing: true
life_cycle_scripts: true
Add your install script:
install.sh
#!/bin/bash
set -e
echo ""
echo "When including a plugin in a BitOps install, this script will be called during docker build."
echo "It should be used to install any dependencies required to actually run your plugin."
echo "BitOps uses alpine linux as its base, so you'll want to use apk commands (Alpine Package Keeper)"
echo ""
apk info
echo "In the install script for the duplicate-environment"
echo "Install your things here"
4.2. Build a BitOps image#
Create a new directory to hold your custom BitOps config:
mkdir /path/to/bitops-custom
cd /path/to/bitops-custom
4.2.1. Add the BitOps config#
First, add your BitOps level bitops.config.yaml
and include a reference to your local file dependency (via plugins
) and a reference in the deployments
section:
bitops:
fail_fast: true
run_mode: default # (Unused for now)
logging:
level: DEBUG # Sets the logging level
color:
enabled: true # Enables colored logs
filename: bitops-run # log filename
err: bitops.logs # error logs filename
path: /var/logs/bitops # path to log folder
default_folder: _default
plugins:
duplicate-environment:
source: file:///opt/bitops-local-plugins/duplicate-environment
deployments:
duplicate-environment:
plugin: duplicate-environment
Note: This is the same file as above (
/path/to/ops-repo/plugin-no-install/duplicate-environment/bitops-level/bitops.config.yaml
), but we've filled in theplugins.duplicate-environment
object to include afile://
source. We will not use the previous file and will instead focus on this file.Note: The path of the source is reserved by BitOps for locally developed plugins. When you build a custom BitOps image, if there is a
plugins
directory as a sibling to theDockerfile
, BitOps will copy that file into the container at/opt/bitops-local-plugins
.
4.2.2. Add your Dockerfile#
Dockerfile
FROM bitovi/bitops:base
4.2.3. Copy plugin code to the BitOps directory#
In order for the build to have access to your local plugin files, they'll need to be in the same directory as the Dockerfile
. One quick way to do this is to set up a simple script to run prior to your docker build to clean and re-copy the plugin files:
copy-plugins.sh
#!/bin/bash
mkdir -p /path/to/bitops-custom/plugins
# duplicate-environment
rm -rf /path/to/bitops-custom/plugins/duplicate-environment
cp -r /path/to/bitops-plugins/duplicate-environment /path/to/bitops-custom/plugins/duplicate-environment
Note: The
/path/to/bitops-custom/plugins
directory is reserved by BitOps for the purpose of developing plugins locally.
4.2.4. Build the image#
./copy-plugins.sh
docker build bitops --tag bitovi/bitops:local-custom --progress=plain --no-cache .
4.2.5. Test your plugin#
docker run --rm --name bitops \
-e BITOPS_ENVIRONMENT="duplicate-environment" \
-v /path/to/bitops:/opt/bitops \
-v /path/to/ops-repo/plugin-install:/opt/bitops_deployment \
-v /path/to/bitops-level/bitops.config.yaml:/opt/bitops/bitops.config.yaml \
-v /opt/bitops/scripts/plugins/terraform \
-v /path/to/bitops-plugins/duplicate-environment:/opt/bitops/scripts/installed_plugins/duplicate-environment \
bitops:local-custom
5. Handling the Plugin Install Script (remote)#
As an alternative way to develop plugins locally is simply to host the plugin code/config remotely and specify the plugin via url instead of file://
like:
bitops:
fail_fast: true
run_mode: default # (Unused for now)
logging:
level: DEBUG # Sets the logging level
color:
enabled: true # Enables colored logs
filename: bitops-run # log filename
err: bitops.logs # error logs filename
path: /var/logs/bitops # path to log folder
default_folder: _default
plugins:
duplicate-environment:
source: https://github.com/your-org/your-plugin
deployments:
duplicate-environment:
plugin: duplicate-environment
Then, you can follow the steps in #5 above (sans the copy-plugins.sh
script).