Extending the OpenShift cli with plug-ins - OpenShift cli (oc) | cli tools

Writing cli plug-ins
Installing and using cli plug-ins

You can write and install plug-ins to build on the default oc commands, allowing you to perform new and more complex tasks with the OKD cli.

Writing cli plug-ins

You can write a plug-in for the OKD cli in any programming language or script that allows you to write command-line commands. Note that you can not use a plug-in to overwrite an existing oc command.

OpenShift cli plug-ins are currently a Technology Preview feature.

Procedure

This procedure creates a simple Bash plug-in that prints a message to the terminal when the oc foo command is issued.

Create a file called oc-foo.

When naming your plug-in file, keep the following in mind:
- The file must begin with oc- or kubectl- to be recognized as a plug-in.
- The file name determines the command that invokes the plug-in. For example, a plug-in with the file name oc-foo-bar can be invoked by a command of oc foo bar. You can also use underscores if you want the command to contain dashes. For example, a plug-in with the file name oc-foo_bar can be invoked by a command of oc foo-bar.

Add the following contents to the file.

#!/bin/bash

# optional argument handling
if [[ "$1" == "version" ]]
then
    echo "1.0.0"
    exit 0
fi

# optional argument handling
if [[ "$1" == "config" ]]
then
    echo $KUBECONFIG
    exit 0
fi

echo "I am a plugin named kubectl-foo"

After you install this plug-in for the OKD cli, it can be invoked using the oc foo command.

Additional resources

Review the Sample plug-in repository for an example of a plug-in written in Go.
Review the cli runtime repository for a set of utilities to assist in writing plug-ins in Go.

Installing and using cli plug-ins

After you write a custom plug-in for the OKD cli, you must install it to use the functionality that it provides.

OpenShift cli plug-ins are currently a Technology Preview feature.

Prerequisites

You must have the oc cli tool installed.
You must have a cli plug-in file that begins with oc- or kubectl-.

Procedure

If necessary, update the plug-in file to be executable.
```
$ chmod +x <plugin_file>
```
Place the file anywhere in your PATH, such as /usr/local/bin/.
```
$ sudo mv <plugin_file> /usr/local/bin/.
```
Run oc plugin list to make sure that the plug-in is listed.
```
$ oc plugin list
```
Example output
```
The following compatible plugins are available:

/usr/local/bin/<plugin_file>
```
If your plug-in is not listed here, verify that the file begins with oc- or kubectl-, is executable, and is on your PATH.
Invoke the new command or option introduced by the plug-in.

For example, if you built and installed the kubectl-ns plug-in from the Sample plug-in repository, you can use the following command to view the current namespace.
```
$ oc ns
```
Note that the command to invoke the plug-in depends on the plug-in file name. For example, a plug-in with the file name of oc-foo-bar is invoked by the oc foo bar command.