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
ordevspace 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:
After installing a plugin you can check all your existing plugins via:
Updating a plugin
To update a DevSpace plugin run the following command:
Removing a plugin
To remove a plugin via the DevSpace command line:
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 adddevspace 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 indevspace --help
description
the description of the command to print indevspace --help
subCommand
(Optional) the subcommand to append the command to (e.g.add
will add the command todevspace 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 adevspace.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 installedbefore_update
executed before the plugin will be updatedafter_update
executed after the plugin was updatedbefore_remove
executed before the plugin will be removedroot
executed at the beginning of a devspace command executionanalyze
,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: