Audience

This wiki is meant to provide details for additional teams to create "plugins" for the HPE CLI.

This is a working document, which we will refine as we onboard new plugins.

Prerequisites

GoLang

HPECLI is built in Go and is provided as a single executable file available for Windows, MacOS, and Linux. This means that additional plugins have to be written in Go and a development environment has to be set up on your machine before you can continue.

Use the following procedure to get started with GoLang: https://golang.org/doc/install

GitHub

HPECLI is hosted on GitHub and contributions would be done through the git commands, so git is another prerequisite to get started.

We suggest using the following documentation if you are not familiar with Git yet: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

Proxy settings

If you are operating from behind a firewall, remember to set proxy configuration accordingly so that Go will be able to build HPECLI and fetch some of the packages it needs from the Internet (GitHub)

Other requirements

We recommend using VisualStudio Code and its extension for GoLang (ms-vscode.go). This provides great support for GoLang development. Check it out on https://code.visualstudio.com/. VisualStudio Code also provides native support for git commands, so you can basically do it all from VisualStudio Code.

Architecture of HPECLI

Cobra

Cobra is both a library for creating powerful modern CLI applications as well as a program to generate applications and command files.

The framework Cobra provides a generator that adds some boilerplate code for you. This is handy because now you can focus more on the logic of your CLI instead of figuring out how to parse flags.

Cobra is built on a structure of commands, arguments & flags.

Commands represent actions, Args are things and Flags are modifiers for those actions.

The best applications will read like sentences when used. Users will know how to use the application because they will natively understand how to use it.

The pattern to follow is APPNAME VERB NOUN --ADJECTIVE. or APPNAME COMMAND ARG --FLAG

In the following example, oneview is a command, login is a subcommand and 'host' is a flag:

hpe oneview login --host "host_name"

When you look inside the $GOPATH\go\src\hpecli\cmd\hpecli\main.go file, there’s a rootCmd to hold all the other top-level commands, this file is the starting point of execution.

	// create the root command.  It doesn't do anything but used to hold
	// all of the other top-level commands
	rootCmd := &cobra.Command{
		Use:           "hpe",
		Short:         "hpe cli for accessing various services",
		SilenceErrors: true,
		SilenceUsage:  true,
	}

Here you can define how to use the HPE CLI, together with a short and a long description.

Common services

Logging

Logrus is used to provide console logging for the application. The application doesn't log to a separate debug log file. Modules should log their intended content as INFO messages. All INFO messages are directed to stdout. Any other log levels are directed to stderr.

Updating

The CLI core has the ability to detect and update itself to newer versions. Individual modules shouldn't need to do anything specific.

DB

The CLI core has a key/value store DB that is available for any modules to use. The data is persisted in a file in the users home directory. The interface to the DB is fairly simple and includes GET, PUT, DELETE methods. In order to avoid conflicts between modules, it is desirable to have modules have a consistent prefix for the keys. For example, the OneView module can use "ov", the iLO module use "ilo", etc. New modules should use a unique prefix.

Context

Many of the modules use a context to abstract details of interacting with the DB directly. Modules can then simply use the context, and the context handles the details of putting and retrieving values from the database in the most useful form. The use of a context is not required, but may be helpful.

Analytics

Stay Tuned...

Password Input

Existing modules provide several ways to collect passwords from users to log in to the remote service. Individual modules can provide options they feel are appropriate. The core has the ability to retrieve passwords from the console without echoing back to the user (so the password isn't printed to the screen). These are implemented in the password package. Example usage for iLO would be: password.Read(&opts.password, opts.passwordStdin, "ilo password: ") More details here: https://github.com/HewlettPackard/hpecli/blob/master/pkg/ilo/login.go

Command line completion

Command line completion is provided by the Cobra platform. We have added a command hpe completion to generate the command completion script which will add hpe CLI command completion to bash

Getting started

In order to best contribute to the hpe CLI we recommend to fork the hpecli repo into your own Github account using the fork button in the upper right corner of the https://github.com/HewlettPackard/hpecli repo. Once you have your own copy of the repository, clone it locally:

cd $GOPATH
cd go/src
git clone https://github.com/<YourAccount>/hpecli.git

Make sure you also add the original remote repo as an additional remote (traditionally called “upstream”) as shown below:

git remote add upstream https://github.com/HewlettPackard/hpecli.git
git remote -v

You should now have 2 remote named origin and 2 remote named upstream pointing to the original hpecli repo. You can now build you private copy.

cd hpecli
./build.sh

If you have been successful, you should be able to run the following commands:

./hpe --help
./hpe version

Creating a skeleton for the new package

The easiest way to get started with a new plugin is to copy an existing one and rename it.

• Step 1 - From your $GOPATH\go\src\hpecli\pkg folder make a copy of the oneview folder and rename it to match your plugin name, say newplugin. Make sure that copy is in the same folder as the original

• Step 2 - Some of these files might go away but for simplicity, just open each file in the $GOPATH\go\src\hpecli\pkg\newplugin folder and at line 1, replace package oneview with the name of the package you are building, for example package newplugin.

Register new verb in main.go file

Edit the main.go to add your newplugin command as already shown below for iLO or CloudVolumes:

func addSubCommands(rootCmd *cobra.Command) {
	rootCmd.AddCommand(
		cloudvolume.NewCloudVolumeCommand(),
		ilo.NewILOCommand(),
	)

Deciding verbs structure for a new module

Of course, we'd like to have the HPECLI as complete as possible, but for now, we are in a Proof-of-Concept phase so only a few verbs are enough to prove the point so we recommend starting simple. As an example the following diagram represents the currently supported verbs:

So the suggestion is to implement the following verbs:

login

With the following flags:

-- host: This is a mandatory flag for setting up the API endpoint of the service we are connecting to

-- username: This is a mandatory flag for a valid username at the target endpoint

-- password: This is an optional parameter for the password of the provided username. If not set, the user will be prompted to enter the password interactively.

-- password-stdin: This is an optional parameter for the password of provided username. This allows the password to be entered from stdin

get

We need a few get commands, make your call on which one makes the most sense. Information shall be returned in JSON.

logout

Terminate the session and remove the context from our stored contexts

context

With the following flags:

-- host This is an optional flag that specifies which host to change context to. If none is specified, you'll need to display the current host.

help

The help should be provided as part of the cobra verb implementation as shown in the example below.

func newLoginCommand() *cobra.Command {
	var opts iloLoginOptions

	var cmd = &cobra.Command{
		Use:   "login",
		Short: "Login to iLO",
		RunE: func(_ *cobra.Command, _ []string) error {
			return runLogin(&opts)
		},
	}

Cobra will use this to display help automatically.

Didiers-Mac:~ lalli$ hpe ilo --help
Access to HPE iLO commands

Usage:
  hpe ilo [command]

Available Commands:
  context     Change context to different HPE iLO host
  get         Get details from iLO
  login       Login to iLO
  logout      Logout from iLO

Flags:
  -h, --help   help for ilo

Global Flags:
      --debug   enable debug logging

Use "hpe ilo [command] --help" for more information about a command.

Developing your module

You are now ready to code the body of the functions you have decided to implement. Having a Go language binding for your API is a plus. You can write a client interface to the API as shown in the OneView module.

Testing / Quality rules

• You can run your commands with --debug to get full logging, don't hesitate to use logging throughout your code
• You will need to implement a test go file for each of your modules
• You will need to comply with SonarCloud/CircleCI rules (GoLang Lint)

Contributing back

Once you have tested your code locally, it's time to make it available. Using git you should:

• Create a new branch
• commit your code to that branch in your local repo
• Submit a Pull Request to the hpecli repo