DevSpace Plugins

The functionality of DevSpace can be extended and changed via plugins. Plugins are managed through DevSpace and are contained in a single binary or shell script. Plugins are able to extend DevSpace in the following ways:

• Add new commands to DevSpace (e.g. devspace login or devspace list users)
• Add new predefined variables
• Execute hooks at specific events (like a command execution)

Installing a plugin

Plugins can be installed from an URL, Git Repository or local file. To install a plugin run:

# Add a plugin from a git repository

devspace add plugin https://github.com/my-organization/my-repo

# Add a plugin from an URL

devspace add plugin https://myorg.com/path/to/plugin.yaml

# Add a plugin from a local path

devspace add plugin ./plugin.yaml

After installing a plugin you can check all your existing plugins via:

devspace list plugins

Updating a plugin

To update a DevSpace plugin run the following command:

# Enter the name and not the path

devspace update plugin PLUGIN_NAME

# This only works for GIT plugins

devspace update plugin PLUGIN_NAME --version GIT_TAG

Removing a plugin

To remove a plugin via the DevSpace command line:

# Enter the name and not the path

devspace remove plugin PLUGIN_NAME

If the plugin cannot be removed because a certain hook fails (or any other reason), you can also delete the plugin manually. DevSpace saves all plugin data in $HOME/.devspace/plugins. You will have to check each folders plugin.yaml to see which plugin is stored in the folder. To remove a plugin, simply delete the complete plugin folder.

Developing a custom DevSpace plugin

Creating an own DevSpace plugin is quite easy. You only need a plugin.yaml that specifies where DevSpace can find the plugin binary and how DevSpace should execute it. You can also take a look at the devspace-plugin-example project for a complete example. For each installed plugin, DevSpace will create a folder in $HOME/.devspace/plugins with a plugin.yaml and a downloaded or copied binary that will be executed.

plugin.yaml

The plugin.yaml specifies how the plugin is installed and integrates into DevSpace and consists of the following parts.

name

Name of the plugin as shown in devspace list plugins and used for devspace update plugin and devspace remove plugin. (e.g. my-devspace-plugin)

version

The semantic current version of the plugin (e.g. 0.0.1)

binaries

This section states where DevSpace can retrieve the plugin binary for the current operating system and architecture. If devspace cannot find a binary for the current runtime.GOOS and runtime.GOARCH it will not install the plugin. The binaries section expects an array with objects that can have the following properties:

• os is the runtime.GOOS name of the operating system (e.g. darwin, windows, linux etc.)
• arch is the runtime.GOARCH name of the system (e.g. amd64, 386 etc.)
• path is the URL to the binary to download or the local path to the binary to copy

commands

This section specifies which commands should be added to DevSpace. It expects an array with objects that can have the following properties:

• name of the command that should be added to devspace (e.g. login will add devspace login)
• baseArgs these args are prepended to the plugin binary, so when a user will call 'devspace login other --flag 123', devspace will call the plugin binary with 'plugin-binary baseArgs... other --flag 123'
• usage the usage of the command to print in devspace --help
• description the description of the command to print in devspace --help
• subCommand (Optional) the subcommand to append the command to (e.g. add will add the command to devspace add)

DevSpace will forward all passed arguments and flags to the plugin command.

vars

This section specifies which predefined variables are added to DevSpace. These variable values will be retrieved from the plugin binary instead of asking the user. It expects an array with objects that can have the following properties:

• name of the predefined variable to add (e.g. EXAMPLE_VARIABLE which can then be used in a devspace.yaml as ${EXAMPLE_VARIABLE})
• baseArgs these args are appended to the plugin binary (e.g. ["print", "var", "test"] will cause devspace to call the plugin binary with: plugin-binary print var test)

DevSpace expects the plugin binary to either fail (exit code unequal zero) or print the variable value to the stdout stream. Furthermore when executing the plugin-binary, DevSpace will set the following environment variables:

• DEVSPACE_PLUGIN_OS_ARGS all arguments that were used to call the current command encoded as JSON (e.g. ["devspace", "dev", "--wait", "--force-build"])
• DEVSPACE_PLUGIN_KUBE_NAMESPACE_FLAG the value of --namespace if set (e.g. namespace)
• DEVSPACE_PLUGIN_KUBE_CONTEXT_FLAG the value of --kube-context if set (e.g. my-kube-context)

hooks

This section specifies certain plugin commands that should be executed at certain DevSpace events. It expects an array with objects that can have the following properties:

• event name of the event when to execute the command. The following events exist:
  • after_install executed after the plugin was installed
  • before_update executed before the plugin will be updated
  • after_update executed after the plugin was updated
  • before_remove executed before the plugin will be removed
  • root executed at the beginning of a devspace command execution
  • analyze, attach, build, deploy, dev, enter, init, logs, open, print, purge, render, restart, run, sync, ui, upgrade are executed after the corresponding devspace command has loaded the config and created a kubernetes client (if there is a config to load or a kubernetes client to create)
• baseArgs these args are appended to the plugin binary (e.g. ["run", "my", "command"] will cause devspace to call the plugin binary with: plugin-binary run my command)
• background if true will execute the hook in the background and continue DevSpace command execution

If a non-background hook fails (exit code unequals zero) DevSpace will stop command execution and the complete DevSpace command fails. Furthermore when executing the plugin-binary, DevSpace will set the following environment variables (if they apply for the event):

• DEVSPACE_PLUGIN_OS_ARGS all arguments that were used to call the current command encoded as JSON (e.g. ["devspace", "dev", "--wait", "--force-build"])
• DEVSPACE_PLUGIN_CONFIG the config that was loaded for the command as yaml encoded (all profiles and variables are resolved at this point)
• DEVSPACE_PLUGIN_COMMAND the name of the DevSpace command that was executed (e.g. dev)
• DEVSPACE_PLUGIN_COMMAND_LINE the complete name of the DevSpace command that was executed (e.g. devspace dev [FLAGS])
• DEVSPACE_PLUGIN_COMMAND_FLAGS the flags that were passed to the DevSpace command encoded as JSON (e.g. ["--namespace", "test", "--skip-build", "true"])
• DEVSPACE_PLUGIN_COMMAND_ARGS the arguments that were passed to the DevSpace command encoded as JSON (without any flags) (e.g. ["arg1"])
• DEVSPACE_PLUGIN_KUBE_NAMESPACE_FLAG the kubernetes namespace where DevSpace will operate in (e.g. namespace)
• DEVSPACE_PLUGIN_KUBE_CONTEXT_FLAG the kubernetes context where DevSpace will operate in (e.g. my-kube-context)

Example

An example plugin.yaml could look like this:

name: devspace-plugin-example

version: 0.0.1

commands:

# This will add the command devspace login

- name: "login"

# these args are prepended to the plugin binary, so when a user will call 'devspace login test test2 --flag 123'

# devspace will call the plugin binary with 'plugin-binary other command test test2 --flag 123'

baseArgs: ["other", "command"]

usage: "short description of command"

description: "long description of command"

# You can also add commands under already existing devspace subcommands

# This will add the devspace command: devspace list env

- name: "env"

baseArgs: ["list", "env"]

subCommand: "list"

# Hooks are called before certain already existing commands are executed

# in devspace, for example devspace dev

hooks:

# will be executed when devspace print is run by the user

- event: print

# this will call the plugin binary before devspace print is called with: 'plugin-binary list env'

baseArgs: ["list", "env"]

# root is executed before any other event and command execution except for other plugin commands

- event: root

baseArgs: ["login"]

# You can also add predefined variables for the config via plugins

vars:

# the name of the predefined variable

# that can be used within any devspace.yaml

- name: EXAMPLE_USER

# this will call the plugin binary when resolving this variable and expects the variable

# output on stdout.

baseArgs: ["print", "env", "USER"]

- name: EXAMPLE_HOME

baseArgs: [ "print", "env", "HOME" ]

# In this section the plugin binaries (or scripts) and their locations are defined

# if devspace cannot find a binary for the current runtime.GOOS and runtime.GOARCH

# it will not install the plugin

binaries:

- os: darwin

arch: amd64

# can be either an URL or local path

path: ./main

- os: linux

arch: amd64

path: main

- os: linux

arch: "386"

path: main

- os: windows

arch: amd64

path: path/to/main.exe

- os: windows

arch: "386"

path: https://my-domain.url/path/to/windows.exe