Monday, February 20, 2017

Write Your Own CLI Plugins for Bluemix Cloud Foundry

Screenshot showing README for my plugin
README for my Plugin
Last year I blogged about how I am using plugins to extend the Bluemix Cloud Foundry command line interface (CLI). The CLI has a set of commands to manage plugin repositories and to install and uninstall plugins. It is pretty easy to use and there are some useful plugins available from Cloud Foundry and IBM Bluemix. Having mastered the first step, I wanted to know how plugins work and what it takes to write my own plugin. Here is what I learned.


Getting Started

I started my endeavor trying to understand the internals of cf CLI plugins by visiting the Cloud Foundry page with Community plugins. On the right are two links pointing to instructions on how to include my own plugin into the collection and, more important to me, how to get started writing my own plugin. There are some requirements to be met:
  • Have GoLang (the programming language Go) installed
  • Have the CLI source code installed with a level of at least v6.7.0
Once that is done, a new plugin can be developed. Because I didn't know how to code in Go I took the interactive introduction tour for Go. Easy.

Plugin Interface and Development

After that I was ready to write my own plugin. Developing a plugin means implementing the defined plugin interface. It consists of two functions:

type Plugin interface {
 Run(cliConnection CliConnection, args []string)
 GetMetadata() PluginMetadata
} 
  • Run: Execute the plugin logic. It involves detecting the command and its parameters, invoking the necessary functions and returning output, if any.
  • GetMetadata: The functions is used to announce the plugin name, its commands, help texts and some additional data to the cf CLI. The listed plugin commands are shown in the help section of the cf command ("Commands offered by installed plugins") and are also used to route the processing flow to the plugin.
There are several sample plugins available that demonstrate the general plugin structure, how to process one or multiple commands or how to interact with the user on the command line. A plugin API can be used to execute existing CLI commands and to consume their output. Thus, it would be possible to write a wrapper plugin that, e.g., automates several steps of a typical usage scenario.
After the plugin code has been developed, the plugin development guide shows how to compile or build the executable plugin ("go build"), how to install and uninstall it ("cf install-plugin" and "cf uninstall-plugin") and how to write test cases. The page on how to share your own plugin even has instructions on building executables for the different operating platforms such as Linux, OS/X and Windows.

With all that background I was able to create my own cf CLI plugin. It is coded in Go, implements the plugin interface, makes use of the mentioned API and I built executable binaries for three platforms. I will describe the plugin in another blog post.

BTW: The plugin is named "multi-instance", is available on GitHub and is in an early state. It is intended to interact with multiple Cloud Foundry instances at the same time, e.g., getting status from Bluemix Public in several regions. If you like the concept, leave a comment or request a feature.