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 OpenShift Container Platform CLI.

Writing CLI plug-ins

You can write a plug-in for the OpenShift Container Platform 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. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

See the Red Hat Technology Preview features support scope for more information.

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- in order 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 OpenShift Container Platform 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 OpenShift Container Platform CLI, you must install it to use the functionality that it provides.

See the Red Hat Technology Preview features support scope for more information.

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.