CLI Reference

The CLI for Windows is provided as a zip archive; you can download it from the Red Hat Customer Portal. After logging in with your Red Hat account, you must have an active OpenShift Enterprise subscription to access the downloads page:

Download the CLI from the Red Hat Customer Portal

Alternatively, if the cluster administrator has enabled it, you can download and unpack the CLI from the About page on the web console.

Tutorial Video:

The following video walks you through this process: Click here to watch

Then, unzip the archive with a ZIP program and move the oc binary to a directory on your PATH. To check your PATH, open the Command Prompt and run:

C:\> path

The CLI for Mac OS X is provided as a tar.gz archive; you can download it from the Red Hat Customer Portal. After logging in with your Red Hat account, you must have an active OpenShift Enterprise subscription to access the downloads page:

Download the CLI from the Red Hat Customer Portal

Alternatively, if the cluster administrator has enabled it, you can download and unpack the CLI from the About page on the web console.

Tutorial Video:

The following video walks you through this process: Click here to watch

Then, unpack the archive and move the oc binary to a directory on your PATH. To check your PATH, open a Terminal window and run:

$ echo $PATH

For Red Hat Enterprise Linux (RHEL) 7, you can install the CLI as an RPM using Red Hat Subscription Management (RHSM) if you have an active OpenShift Enterprise subscription on your Red Hat account:

# subscription-manager register
# subscription-manager refresh
# subscription-manager attach --pool=<pool_ID> 1
# subscription-manager repos --enable="rhel-7-server-ose-3.7-rpms"
# yum install atomic-openshift-clients

For RHEL, Fedora, and other Linux distributions, you can also download the CLI directly from the Red Hat Customer Portal as a tar.gz archive. After logging in with your Red Hat account, you must have an active OpenShift Enterprise subscription to access the downloads page.

Download the CLI from the Red Hat Customer Portal

Tutorial Video:

The following video walks you through this process: Click here to watch

Alternatively, if the cluster administrator has enabled it, you can download and unpack the CLI from the About page on the web console.

Then, unpack the archive and move the oc binary to a directory on your PATH. To check your path, run:

$ echo $PATH

To unpack the archive:

$ tar -xf <file>

oc: No such file or directory

Return information about the current session:

$ oc whoami [--options]

Display an introduction to some core OpenShift Container Platform concepts:

$ oc types

Log in to the OpenShift Container Platform server:

$ oc login

End the current session:

$ oc logout

Create a new project:

$ oc new-project <project_name>

Creates a new application based on the source code in the current directory:

$ oc new-app

Creates a new application based on the source code in a remote repository:

$ oc new-app https://github.com/sclorg/cakephp-ex

Creates a new application based on the source code in a private remote repository:

$ oc new-app https://github.com/youruser/yourprivaterepo --source-secret=yoursecret

Show an overview of the current project:

$ oc status

Switch to another project. Run without options to display the current project. To view all projects you have access to run oc projects.

$ oc project <project_name>

See the documentation of a resource and its fields:

$ oc explain <resource_name>

Start or stop a OpenShift Container Platform cluster:

$ oc cluster [--options]

Output shell completion code for the specified shell:

$ oc completion [--options]

Get help about any command:

$ oc <command> --help

Run a command line plug-in:

$ oc plugin [--options]

Display client and server versions:

$ oc version [--options]

Return a list of objects for the specified object type. If the optional <object_name> is included in the request, then the list of results is filtered by that value.

$ oc get <object_type> [<object_name>]

You can use the -o or --output option to modify the output format.

$ oc get <object_type> [<object_name>]-o|--output=json|yaml|wide|custom-columns=...|custom-columns-file=...|go-template=...|go-template-file=...|jsonpath=...|jsonpath-file=...]

The output format can be a JSON or YAML, or an extensible format like custom columns, golang template, and jsonpath.

For example, the following command lists the name of the pods running in a specific project:

$ oc get pods -n default -o jsonpath='{range .items[*].metadata}{"Pod Name: "}{.name}{"\n"}{end}'

Pod Name: docker-registry-1-wvhrx
Pod Name: registry-console-1-ntq65
Pod Name: router-1-xzw69

Returns information about the specific object returned by the query. A specific <object_name> must be provided. The actual information that is available varies as described in object type.

$ oc describe <object_type> <object_name>

Edit the desired object type:

$ oc edit <object_type>/<object_name>

Edit the desired object type with a specified text editor:

$ OC_EDITOR="<text_editor>" oc edit <object_type>/<object_name>

Edit the desired object in a specified format (eg: JSON):

$ oc edit <object_type>/<object_name> \
    --output-version=<object_type_version> \
    -o <object_type_format>

Change configuration files for the client:

$ oc config  --config=""

Modify a volume:

$ oc volume <object_type>/<object_name> [--option]

Update the labels on a object:

$ oc label <object_type> <object_name> <label>

Update the annotations on a resource:

$ oc annotate [--options]

Look up a service and expose it as a route. There is also the ability to expose a deployment configuration, replication controller, service, or pod as a new service on a specified port. If no labels are specified, the new object will re-use the labels from the object it exposes.

If you are exposing a service, the default generator is --generator=route/v1. For all other cases the default is --generator=service/v2, which leaves the port unnamed. Generally, there is no need to set a generator with the oc expose command. A third generator, --generator=service/v1, is available with the port name default.

$ oc expose <object_type> <object_name>

Delete the specified object. An object configuration can also be passed in through STDIN. The oc delete all -l <label> operation deletes all objects matching the specified <label>, including the replication controller so that pods are not re-created.

$ oc delete -f <file_path>

$ oc delete <object_type> <object_name>

$ oc delete <object_type> -l <label>

$ oc delete all -l <label>

Modify a specific property of the specified object.

$ oc set env dc/mydc VAR1=value1

$ oc set build-secret --source bc/mybc mysecret

Manually start the build process with the specified build configuration file:

$ oc start-build <buildconfig_name>

Manually start the build process by specifying the name of a previous build as a starting point:

$ oc start-build --from-build=<build_name>

Manually start the build process by specifying either a configuration file or the name of a previous build and retrieve its build logs:

$ oc start-build --from-build=<build_name> --follow

$ oc start-build <buildconfig_name> --follow

Wait for a build to complete and exit with a non-zero return code if the build fails:

$ oc start-build --from-build=<build_name> --wait

Set or override environment variables for the current build without changing the build configuration. Alternatively, use -e.

$ oc start-build --env <var_name>=<value>

Set or override the default build log level output during the build:

$ oc start-build --build-loglevel [0-5]

Specify the source code commit identifier the build should use; requires a build based on a Git repository:

$ oc start-build --commit=<hash>

Re-run build with name <build_name>:

$ oc start-build --from-build=<build_name>

Archive <dir_name> and build with it as the binary input:

$ oc start-build --from-dir=<dir_name>

Use existing archive as the binary input; unlike --from-file the archive will be extracted by the builder prior to the build process:

$ oc start-build --from-archive=<archive_name>

Use <file_name> as the binary input for the build. This file must be the only one in the build source. For example, pom.xml or Dockerfile.

$ oc start-build --from-file=<file_name>

Download the binary input using HTTP or HTTPS instead of reading it from the file system:

$ oc start-build --from-file=<file_URL>

Download an archive and use its contents as the build source:

$ oc start-build --from-archive=<archive_URL>

The path to a local source code repository to use as the binary input for a build:

$ oc start-build --from-repo=<path_to_repo>

Specify a webhook URL for an existing build configuration to trigger:

$ oc start-build --from-webhook=<webhook_URL>

The contents of the post-receive hook to trigger a build:

$ oc start-build --git-post-receive=<contents>

The path to the Git repository for post-receive; defaults to the current directory:

$ oc start-build --git-repository=<path_to_repo>

List the webhooks for the specified build configuration or build; accepts all, generic, or github:

$ oc start-build --list-webhooks

Override the Spec.Strategy.SourceStrategy.Incremental option of a source-strategy build:

$ oc start-build --incremental

Override the Spec.Strategy.DockerStrategy.NoCache option of a docker-strategy build:

$oc start-build --no-cache

Perform a rollback:

$ oc rollback <deployment_name>

Manage a Kubernetes deployment or an OpenShift deployment configuration. Start a new rollout, view its status or history, or rollback to a previous revision of your application:

$ oc rollout [--options]

Create a build configuration based on the source code in the current Git repository (with a public remote) and a container image:

$ oc new-build .

Create a build configuration based on a remote git repository:

$ oc new-build https://github.com/sclorg/cakephp-ex

Create a build configuration based on a private remote git repository:

$ oc new-build https://github.com/youruser/yourprivaterepo --source-secret=yoursecret

Stop a build that is in progress:

$ oc cancel-build <build_name>

Cancel multiple builds at the same time:

$ oc cancel-build <build1_name> <build2_name> <build3_name>

Cancel all builds created from the build configuration:

$ oc cancel-build bc/<buildconfig_name>

Specify the builds to be canceled:

$ oc cancel-build bc/<buildconfig_name> --state=<state>

Example values for state are new or pending.

Useful commands for managing images.

$ oc image [--options]

Commands that import applications into OpenShift Container Platform.

$ oc import [--options]

Import tag and image information from an external image repository:

$ oc import-image <image_stream>

Set the number of desired replicas for a replication controller or a deployment configuration to the number of specified replicas:

$ oc scale <object_type> <object_name> --replicas=<#_of_replicas>

Take an existing tag or image from an image stream, or a container image "pull spec", and set it as the most recent image for a tag in one or more other image streams:

$ oc tag <current_image> <image_stream>

Administrative commands. Tools for managing a cluster:

$ oc adm [--options]

Apply a configuration to a resource by file name or stdin:

$ oc apply [--options]

Parse a configuration file and create one or more OpenShift Container Platform objects based on the file contents. The -f flag can be passed multiple times with different file or directory paths. When the flag is passed multiple times, oc create iterates through each one, creating the objects described in all of the indicated files. Any existing resources are ignored.

$ oc create -f <file_or_dir_path>

Attempt to modify an existing object based on the contents of the specified configuration file. The -f flag can be passed multiple times with different file or directory paths. When the flag is passed multiple times, oc replace iterates through each one, updating the objects described in all of the indicated files.

$ oc replace -f <file_or_dir_path>

Transform a project template into a project configuration file:

$ oc process -f <template_file_path>

Create and run a particular image, possibly replicated. By default, create a deployment configuration to manage the created container(s). You can choose to create a different resource using the --generator flag:

You can choose to run in the foreground for an interactive container execution.

$ oc run NAME --image=<image> \
    [--generator=<resource>] \
    [--port=<port>] \
    [--replicas=<replicas>] \
    [--dry-run=<bool>] \
    [--overrides=<inline_json>] \
    [options]

Updates one or more fields of an object using strategic merge patch:

$ oc patch <object_type> <object_name> -p <changes>

The <changes> is a JSON or YAML expression containing the new fields and the values. For example, to update the spec.unschedulable field of the node node1 to the value true, the json expression is:

$ oc patch node node1 -p '{"spec":{"unschedulable":true}}'

Export resources to be used elsewhere:

$ oc export <object_type> [--options]

See Creating a Template from Existing Objects for more information on exporting existing objects from your project in template form.

Extract secrets or config maps to disk:

$ oc extract [--options]

Idle scalable resources:

$ oc idle [--options]

Observe changes to resources and react to them:

$ oc observe [--options]

Inspect authorization:

$ oc auth [--options]

Manage authorization policies:

$ oc policy [--options]

Convert configuration files between different API versions:

$ oc convert [--options]

Configure secrets:

$ oc secrets [--options] path/to/ssh_key

Setup an autoscaler for your application. Requires metrics to be enabled in the cluster. See Enabling Cluster Metrics for cluster administrator instructions, if needed.

$ oc autoscale dc/<dc_name> [--options]

Launch a command shell to debug a running application.

$ oc debug -h

When debugging images and setup problems, you can get an exact copy of a running pod configuration and troubleshoot with a shell. Since a failing pod may not be started and not accessible to rsh or exec, running the debug command creates a carbon copy of that setup.

The default mode is to start a shell inside of the first container of the referenced pod, replication controller, or deployment configuration. The started pod will be a copy of your source pod, with labels stripped, the command changed to /bin/sh, and readiness and liveness checks disabled. If you just want to run a command, add -- and a command to run. Passing a command will not create a TTY or send STDIN by default. Other flags are supported for altering the container or pod in common ways.

A common problem running containers is a security policy that prohibits you from running as a root user on the cluster. You can use this command to test running a pod as non-root (with --as-user) or to run a non-root pod as root (with --as-root).

The debug pod is deleted when the the remote command completes or you interrupt the shell.

$ oc debug RESOURCE/NAME [ENV1=VAL1 ...] [-c CONTAINER] [options] [-- COMMAND]

$ oc debug dc/test

$ oc debug dc/test --as-user=1000000

$ oc debug dc/test -c second -- /bin/env

$ oc debug dc/test -o yaml

Retrieve the log output for a specific build, deployment, or pod. This command works for builds, build configurations, deployment configurations, and pods.

$ oc logs -f <pod>

Execute a command in an already-running container. You can optionally specify a container ID, otherwise it defaults to the first container.

$ oc exec <pod> [-c <container>] <command>

Open a remote shell session to a container:

$ oc rsh <pod>

Copy the contents to or from a directory in an already-running pod container. If you do not specify a container, it defaults to the first container in the pod.

To copy contents from a local directory to a directory in a pod:

$ oc rsync <local_dir> <pod>:<pod_dir> -c <container>

To copy contents from a directory in a pod to a local directory:

$ oc rsync <pod>:<pod_dir> <local_dir> -c <container>

Forward one or more local ports to a pod:

$ oc port-forward <pod> <local_port>:<remote_port>

Run a proxy to the Kubernetes API server:

$ oc proxy --port=<port> --www=<static_directory>

Attach to a running container:

$ oc attach [--options]

Copy files and directories to and from containers:

$ oc cp [--options]

Creates a new project:

$ oc adm new-project <project_name>

Manages authorization policies:

$ oc adm policy

Manages groups:

$ oc adm groups

Installs a router:

$ ocadm router <router_name>

Installs an IP failover group for a set of nodes:

$ oc adm ipfailover <ipfailover_config>

Installs an integrated container registry:

$ oc adm registry

Outputs the inputs and dependencies of any builds:

$ oc adm build-chain <image_stream>[:<tag>]

Manages nodes. For example, list or evacuate pods, or mark them ready:

$ oc adm manage-node

Removes older versions of resources from the server:

$ oc adm prune

Changes kubelet configuration files:

$ oc adm config <subcommand>

Creates a basic .kubeconfig file from client certificates:

$ oc adm create-kubeconfig

Creates a configuration file for connecting to the server as a user:

$ oc adm create-api-client-config

Creates a bootstrap project template:

$ oc adm create-bootstrap-project-template

Creates the default bootstrap policy:

$ oc adm create-bootstrap-policy-file

Creates a login template:

$ oc adm create-login-template

Resets the policy to the default values:

$ oc adm overwrite-policy

Creates a configuration bundle for a node:

$ oc adm create-node-config

Manages certificates and keys:

$ oc adm ca

Displays the version of the indicated object:

$ oc adm version

Displays help about any command:

$ oc adm help <command>

The plug-in loader is responsible for searching plug-in files, and checking if the plug-in provides the minimum amount of information required for it to run. Files placed in the correct location that do not provide the minimum amount of information (for example, an incomplete plugin.yaml descriptor) are ignored.

The descriptor file supports the following attributes:

name: "great-plugin"              # REQUIRED: the plug-in command name, to be invoked under 'kubectl'
shortDesc: "great-plugin plug-in" # REQUIRED: the command short description, for help
longDesc: ""                      # the command long description, for help
example: ""                       # command example(s), for help
command: "./example"              # REQUIRED: the command, binary, or script to invoke when running the plug-in
flags:                            # flags supported by the plug-in
  - name: "flag-name"             # REQUIRED for each flag: flag name
    shorthand: "f"                # short version of the flag name
    desc: "example flag"          # REQUIRED for each flag: flag description
    defValue: "extreme"           # default value of the flag
tree:                             # allows the declaration of subcommands
  - ...                           # subcommands support the same set of attributes

The preceding descriptor declares the great-plugin plug-in, which has one flag named -f | --flag-name. It could be invoked as:

$ oc plugin great-plugin -f value

When the plug-in is invoked, it calls the example binary or script, which is located in the same directory as the descriptor file, passing a number of arguments and environment variables. The Accessing Runtime Attributes section describes how the example command accesses the flag value and other runtime context.

It is recommended that each plug-in has its own subdirectory in the file system, preferably with the same name as the plug-in command. The directory must contain the plugin.yaml descriptor and any binary, script, asset, or other dependency it might require.

For example, the directory structure for the great-plugin plug-in could look like this:

~/.kube/plugins/
└── great-plugin
    ├── plugin.yaml
    └── example

In most use cases, the binary or script file you write to support the plug-in must have access to some contextual information provided by the plug-in framework. For example, if you declared flags in the descriptor file, your plug-in must have access to the user-provided flag values at runtime.

The same is true for global flags. The plug-in framework is responsible for doing that, so plug-in writers do not need to worry about parsing arguments. This also ensures the best level of consistency between plug-ins and regular oc commands.

Plug-ins have access to runtime context attributes through environment variables. To access the value provided through a flag, for example, look for the value of the proper environment variable using the appropriate function call for your binary or script.

The supported environment variables are: