Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 1. OpenShift CLI (oc)

1.1. Getting started with the CLI

1.1.1. About the CLI

With the OpenShift Container Platform command-line interface (CLI), you can create applications and manage OpenShift Container Platform projects from a terminal. The CLI is ideal in situations where you:

  • work directly with project source code.
  • script OpenShift Container Platform operations.
  • are restricted by bandwidth resources and can not use the web console.

1.1.2. Installing the CLI

You can install the OpenShift CLI (oc) either by downloading the binary or by using an RPM.

1.1.2.1. Installing the CLI by downloading the binary

You can install the OpenShift CLI (oc) in order to interact with OpenShift Container Platform from a command-line interface. You can install oc on Linux, Windows, or macOS.

Important

If you installed an earlier version of oc, you cannot use it to complete all of the commands in OpenShift Container Platform 4.5. Download and install the new version of oc.

1.1.2.1.1. Installing the CLI on Linux

You can install the OpenShift CLI (oc) binary on Linux by using the following procedure.

Procedure

  1. Navigate to the Infrastructure Provider page on the Red Hat OpenShift Cluster Manager site.
  2. Select your infrastructure provider, and, if applicable, your installation type.
  3. In the Command line interface section, select Linux from the drop-down menu and click Download command-line tools.

  4. Unpack the archive:

    Copy to Clipboard Toggle word wrap 
    $ tar xvzf <file>

  5. Place the oc binary in a directory that is on your PATH.

    To check your PATH, execute the following command:

    Copy to Clipboard Toggle word wrap 
    $ echo $PATH

After you install the CLI, it is available using the oc command:

Copy to Clipboard Toggle word wrap 
$ oc <command>
1.1.2.1.2. Installing the CLI on Windows

You can install the OpenShift CLI (oc) binary on Windows by using the following procedure.

Procedure

  1. Navigate to the Infrastructure Provider page on the Red Hat OpenShift Cluster Manager site.
  2. Select your infrastructure provider, and, if applicable, your installation type.
  3. In the Command line interface section, select Windows from the drop-down menu and click Download command-line tools.
  4. Unzip the archive with a ZIP program.

  5. Move the oc binary to a directory that is on your PATH.

    To check your PATH, open the command prompt and execute the following command:

    Copy to Clipboard Toggle word wrap 
    C:\> path

After you install the CLI, it is available using the oc command:

Copy to Clipboard Toggle word wrap 
C:\> oc <command>
1.1.2.1.3. Installing the CLI on macOS

You can install the OpenShift CLI (oc) binary on macOS by using the following procedure.

Procedure

  1. Navigate to the Infrastructure Provider page on the Red Hat OpenShift Cluster Manager site.
  2. Select your infrastructure provider, and, if applicable, your installation type.
  3. In the Command line interface section, select MacOS from the drop-down menu and click Download command-line tools.
  4. Unpack and unzip the archive.

  5. Move the oc binary to a directory on your PATH.

    To check your PATH, open a terminal and execute the following command:

    Copy to Clipboard Toggle word wrap 
    $ echo $PATH

After you install the CLI, it is available using the oc command:

Copy to Clipboard Toggle word wrap 
$ oc <command>

1.1.2.2. Installing the CLI by using an RPM

For Red Hat Enterprise Linux (RHEL), you can install the OpenShift CLI (oc) as an RPM if you have an active OpenShift Container Platform subscription on your Red Hat account.

Prerequisites

  • Must have root or sudo privileges.

Procedure

  1. Register with Red Hat Subscription Manager:

    Copy to Clipboard Toggle word wrap 
    # subscription-manager register

  2. Pull the latest subscription data:

    Copy to Clipboard Toggle word wrap 
    # subscription-manager refresh

  3. List the available subscriptions:

    Copy to Clipboard Toggle word wrap 
    # subscription-manager list --available --matches '*OpenShift*'

  4. In the output for the previous command, find the pool ID for an OpenShift Container Platform subscription and attach the subscription to the registered system:

    Copy to Clipboard Toggle word wrap 
    # subscription-manager attach --pool=<pool_id>

  5. Enable the repositories required by OpenShift Container Platform 4.5.

    • For Red Hat Enterprise Linux 8:

      Copy to Clipboard Toggle word wrap 
      # subscription-manager repos --enable="rhocp-4.5-for-rhel-8-x86_64-rpms"

    • For Red Hat Enterprise Linux 7:

      Copy to Clipboard Toggle word wrap 
      # subscription-manager repos --enable="rhel-7-server-ose-4.5-rpms"

  6. Install the openshift-clients package:

    Copy to Clipboard Toggle word wrap 
    # yum install openshift-clients

After you install the CLI, it is available using the oc command:

Copy to Clipboard Toggle word wrap 
$ oc <command>

1.1.3. Logging in to the CLI

You can log in to the oc CLI to access and manage your cluster.

Prerequisites

  • You must have access to an OpenShift Container Platform cluster.
  • You must have installed the CLI.
Note

To access a cluster that is accessible only over an HTTP proxy server, you can set the HTTP_PROXY, HTTPS_PROXY and NO_PROXY variables. These environment variables are respected by the oc CLI so that all communication with the cluster goes through the HTTP proxy.

Procedure

  • Log in to the CLI using the oc login command and enter the required information when prompted.

    Copy to Clipboard Toggle word wrap 
    $ oc login

    Example output

    Copy to Clipboard Toggle word wrap 
    Server [https://localhost:8443]: https://openshift.example.com:6443
    1 
    
The server uses a certificate signed by an unknown authority.
You can bypass the certificate check, but any data you send to the server could be intercepted by others.
Use insecure connections? (y/n): y
    2 
    

Authentication required for https://openshift.example.com:6443 (openshift)
Username: user1
    3 
    
Password:
    4 
    
Login successful.

You don't have any projects. You can try to create a new project, by running

    oc new-project <projectname>

Welcome! See 'oc help' to get started.

    1
    Enter the OpenShift Container Platform server URL.
    2
    Enter whether to use insecure connections.
    3
    Enter the user name to log in as.
    4
    Enter the user’s password.

You can now create a project or issue other commands for managing your cluster.

1.1.4. Using the CLI

Review the following sections to learn how to complete common tasks using the CLI.

1.1.4.1. Creating a project

Use the oc new-project command to create a new project.

Copy to Clipboard Toggle word wrap 
$ oc new-project my-project

Example output

Copy to Clipboard Toggle word wrap 
Now using project "my-project" on server "https://openshift.example.com:6443".

1.1.4.2. Creating a new app

Use the oc new-app command to create a new application.

Copy to Clipboard Toggle word wrap 
$ oc new-app https://github.com/sclorg/cakephp-ex

Example output

Copy to Clipboard Toggle word wrap 
--> Found image 40de956 (9 days old) in imagestream "openshift/php" under tag "7.2" for "php"

...

    Run 'oc status' to view your app.

1.1.4.3. Viewing pods

Use the oc get pods command to view the pods for the current project.

Copy to Clipboard Toggle word wrap 
$ oc get pods -o wide

Example output

Copy to Clipboard Toggle word wrap 
NAME                  READY   STATUS      RESTARTS   AGE     IP            NODE                           NOMINATED NODE
cakephp-ex-1-build    0/1     Completed   0          5m45s   10.131.0.10   ip-10-0-141-74.ec2.internal    <none>
cakephp-ex-1-deploy   0/1     Completed   0          3m44s   10.129.2.9    ip-10-0-147-65.ec2.internal    <none>
cakephp-ex-1-ktz97    1/1     Running     0          3m33s   10.128.2.11   ip-10-0-168-105.ec2.internal   <none>

1.1.4.4. Viewing pod logs

Use the oc logs command to view logs for a particular pod.

Copy to Clipboard Toggle word wrap 
$ oc logs cakephp-ex-1-deploy

Example output

Copy to Clipboard Toggle word wrap 
--> Scaling cakephp-ex-1 to 1
--> Success

1.1.4.5. Viewing the current project

Use the oc project command to view the current project.

Copy to Clipboard Toggle word wrap 
$ oc project

Example output

Copy to Clipboard Toggle word wrap 
Using project "my-project" on server "https://openshift.example.com:6443".

1.1.4.6. Viewing the status for the current project

Use the oc status command to view information about the current project, such as services, deployments, and build configs.

Copy to Clipboard Toggle word wrap 
$ oc status

Example output

Copy to Clipboard Toggle word wrap 
In project my-project on server https://openshift.example.com:6443

svc/cakephp-ex - 172.30.236.80 ports 8080, 8443
  dc/cakephp-ex deploys istag/cakephp-ex:latest <-
    bc/cakephp-ex source builds https://github.com/sclorg/cakephp-ex on openshift/php:7.2
    deployment #1 deployed 2 minutes ago - 1 pod

3 infos identified, use 'oc status --suggest' to see details.

1.1.4.7. Listing supported API resources

Use the oc api-resources command to view the list of supported API resources on the server.

Copy to Clipboard Toggle word wrap 
$ oc api-resources

Example output

Copy to Clipboard Toggle word wrap 
NAME                                  SHORTNAMES       APIGROUP                              NAMESPACED   KIND
bindings                                                                                     true         Binding
componentstatuses                     cs                                                     false        ComponentStatus
configmaps                            cm                                                     true         ConfigMap
...

1.1.5. Getting help

You can get help with CLI commands and OpenShift Container Platform resources in the following ways.

  • Use oc help to get a list and description of all available CLI commands:

    Example: Get general help for the CLI

    Copy to Clipboard Toggle word wrap 
    $ oc help

    Example output

    Copy to Clipboard Toggle word wrap 
    OpenShift Client

This client helps you develop, build, deploy, and run your applications on any OpenShift or Kubernetes compatible
platform. It also includes the administrative commands for managing a cluster under the 'adm' subcommand.

Usage:
  oc [flags]

Basic Commands:
  login           Log in to a server
  new-project     Request a new project
  new-app         Create a new application

...

  • Use the --help flag to get help about a specific CLI command:

    Example: Get help for the oc create command

    Copy to Clipboard Toggle word wrap 
    $ oc create --help

    Example output

    Copy to Clipboard Toggle word wrap 
    Create a resource by filename or stdin

JSON and YAML formats are accepted.

Usage:
  oc create -f FILENAME [flags]

...

  • Use the oc explain command to view the description and fields for a particular resource:

    Example: View documentation for the Pod resource

    Copy to Clipboard Toggle word wrap 
    $ oc explain pods

    Example output

    Copy to Clipboard Toggle word wrap 
    KIND:     Pod
VERSION:  v1

DESCRIPTION:
     Pod is a collection of containers that can run on a host. This resource is
     created by clients and scheduled onto hosts.

FIELDS:
   apiVersion	<string>
     APIVersion defines the versioned schema of this representation of an
     object. Servers should convert recognized schemas to the latest internal
     value, and may reject unrecognized values. More info:
     https://git.k8s.io/community/contributors/devel/api-conventions.md#resources

...

1.1.6. Logging out of the CLI

You can log out the CLI to end your current session.

  • Use the oc logout command.

    Copy to Clipboard Toggle word wrap 
    $ oc logout

    Example output

    Copy to Clipboard Toggle word wrap 
    Logged "user1" out on "https://openshift.example.com"

This deletes the saved authentication token from the server and removes it from your configuration file.

1.2. Configuring the CLI

1.2.1. Enabling tab completion

After you install the oc CLI tool, you can enable tab completion to automatically complete oc commands or suggest options when you press Tab.

Prerequisites

  • You must have the oc CLI tool installed.
  • You must have the package bash-completion installed.

Procedure

The following procedure enables tab completion for Bash.

  1. Save the Bash completion code to a file.

    Copy to Clipboard Toggle word wrap 
    $ oc completion bash > oc_bash_completion

  2. Copy the file to /etc/bash_completion.d/.

    Copy to Clipboard Toggle word wrap 
    $ sudo cp oc_bash_completion /etc/bash_completion.d/

    You can also save the file to a local directory and source it from your .bashrc file instead.

Tab completion is enabled when you open a new terminal.

1.3. Extending the CLI with 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.

1.3.1. 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.

Important

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.

  1. 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.

  2. Add the following contents to the file.

    Copy to Clipboard Toggle word wrap 
    #!/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

1.3.2. 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.

Important

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.

Prerequisites

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

Procedure

  1. If necessary, update the plug-in file to be executable.

    Copy to Clipboard Toggle word wrap 
    $ chmod +x <plugin_file>

  2. Place the file anywhere in your PATH, such as /usr/local/bin/.

    Copy to Clipboard Toggle word wrap 
    $ sudo mv <plugin_file> /usr/local/bin/.

  3. Run oc plugin list to make sure that the plug-in is listed.

    Copy to Clipboard Toggle word wrap 
    $ oc plugin list

    Example output

    Copy to Clipboard Toggle word wrap 
    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.

  4. 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.

    Copy to Clipboard Toggle word wrap 
    $ 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.

1.4. Developer CLI commands

1.4.1. Basic CLI commands

1.4.1.1. explain

Display documentation for a certain resource.

Example: Display documentation for pods

Copy to Clipboard Toggle word wrap 
$ oc explain pods

1.4.1.2. login

Log in to the OpenShift Container Platform server and save login information for subsequent use.

Example: Interactive login

Copy to Clipboard Toggle word wrap 
$ oc login

Example: Log in specifying a user name

Copy to Clipboard Toggle word wrap 
$ oc login -u user1

1.4.1.3. new-app

Create a new application by specifying source code, a template, or an image.

Example: Create a new application from a local Git repository

Copy to Clipboard Toggle word wrap 
$ oc new-app .

Example: Create a new application from a remote Git repository

Copy to Clipboard Toggle word wrap 
$ oc new-app https://github.com/sclorg/cakephp-ex

Example: Create a new application from a private remote repository

Copy to Clipboard Toggle word wrap 
$ oc new-app https://github.com/youruser/yourprivaterepo --source-secret=yoursecret

1.4.1.4. new-project

Create a new project and switch to it as the default project in your configuration.

Example: Create a new project

Copy to Clipboard Toggle word wrap 
$ oc new-project myproject

1.4.1.5. project

Switch to another project and make it the default in your configuration.

Example: Switch to a different project

Copy to Clipboard Toggle word wrap 
$ oc project test-project

1.4.1.6. projects

Display information about the current active project and existing projects on the server.

Example: List all projects

Copy to Clipboard Toggle word wrap 
$ oc projects

1.4.1.7. status

Show a high-level overview of the current project.

Example: Show the status of the current project

Copy to Clipboard Toggle word wrap 
$ oc status

1.4.2. Build and Deploy CLI commands

1.4.2.1. cancel-build

Cancel a running, pending, or new build.

Example: Cancel a build

Copy to Clipboard Toggle word wrap 
$ oc cancel-build python-1

Example: Cancel all pending builds from the python build config

Copy to Clipboard Toggle word wrap 
$ oc cancel-build buildconfig/python --state=pending

1.4.2.2. import-image

Import the latest tag and image information from an image repository.

Example: Import the latest image information

Copy to Clipboard Toggle word wrap 
$ oc import-image my-ruby

1.4.2.3. new-build

Create a new build config from source code.

Example: Create a build config from a local Git repository

Copy to Clipboard Toggle word wrap 
$ oc new-build .

Example: Create a build config from a remote Git repository

Copy to Clipboard Toggle word wrap 
$ oc new-build https://github.com/sclorg/cakephp-ex

1.4.2.4. rollback

Revert an application back to a previous deployment.

Example: Roll back to the last successful deployment

Copy to Clipboard Toggle word wrap 
$ oc rollback php

Example: Roll back to a specific version

Copy to Clipboard Toggle word wrap 
$ oc rollback php --to-version=3

1.4.2.5. rollout

Start a new rollout, view its status or history, or roll back to a previous revision of your application.

Example: Roll back to the last successful deployment

Copy to Clipboard Toggle word wrap 
$ oc rollout undo deploymentconfig/php

Example: Start a new rollout for a deployment with its latest state

Copy to Clipboard Toggle word wrap 
$ oc rollout latest deploymentconfig/php

1.4.2.6. start-build

Start a build from a build config or copy an existing build.

Example: Start a build from the specified build config

Copy to Clipboard Toggle word wrap 
$ oc start-build python

Example: Start a build from a previous build

Copy to Clipboard Toggle word wrap 
$ oc start-build --from-build=python-1

Example: Set an environment variable to use for the current build

Copy to Clipboard Toggle word wrap 
$ oc start-build python --env=mykey=myvalue

1.4.2.7. tag

Tag existing images into image streams.

Example: Configure the ruby image’s latest tag to refer to the image for the 2.0 tag

Copy to Clipboard Toggle word wrap 
$ oc tag ruby:latest ruby:2.0

1.4.3. Application management CLI commands

1.4.3.1. annotate

Update the annotations on one or more resources.

Example: Add an annotation to a route

Copy to Clipboard Toggle word wrap 
$ oc annotate route/test-route haproxy.router.openshift.io/ip_whitelist="192.168.1.10"

Example: Remove the annotation from the route

Copy to Clipboard Toggle word wrap 
$ oc annotate route/test-route haproxy.router.openshift.io/ip_whitelist-

1.4.3.2. apply

Apply a configuration to a resource by file name or standard in (stdin) in JSON or YAML format.

Example: Apply the configuration in pod.json to a pod

Copy to Clipboard Toggle word wrap 
$ oc apply -f pod.json

1.4.3.3. autoscale

Autoscale a deployment or replication controller.

Example: Autoscale to a minimum of two and maximum of five pods

Copy to Clipboard Toggle word wrap 
$ oc autoscale deploymentconfig/parksmap-katacoda --min=2 --max=5

1.4.3.4. create

Create a resource by file name or standard in (stdin) in JSON or YAML format.

Example: Create a pod using the content in pod.json

Copy to Clipboard Toggle word wrap 
$ oc create -f pod.json

1.4.3.5. delete

Delete a resource.

Example: Delete a pod named parksmap-katacoda-1-qfqz4

Copy to Clipboard Toggle word wrap 
$ oc delete pod/parksmap-katacoda-1-qfqz4

Example: Delete all pods with the app=parksmap-katacoda label

Copy to Clipboard Toggle word wrap 
$ oc delete pods -l app=parksmap-katacoda

1.4.3.6. describe

Return detailed information about a specific object.

Example: Describe a deployment named example

Copy to Clipboard Toggle word wrap 
$ oc describe deployment/example

Example: Describe all pods

Copy to Clipboard Toggle word wrap 
$ oc describe pods

1.4.3.7. edit

Edit a resource.

Example: Edit a deployment using the default editor

Copy to Clipboard Toggle word wrap 
$ oc edit deploymentconfig/parksmap-katacoda

Example: Edit a deployment using a different editor

Copy to Clipboard Toggle word wrap 
$ OC_EDITOR="nano" oc edit deploymentconfig/parksmap-katacoda

Example: Edit a deployment in JSON format

Copy to Clipboard Toggle word wrap 
$ oc edit deploymentconfig/parksmap-katacoda -o json

1.4.3.8. expose

Expose a service externally as a route.

Example: Expose a service

Copy to Clipboard Toggle word wrap 
$ oc expose service/parksmap-katacoda

Example: Expose a service and specify the host name

Copy to Clipboard Toggle word wrap 
$ oc expose service/parksmap-katacoda --hostname=www.my-host.com

1.4.3.9. get

Display one or more resources.

Example: List pods in the default namespace

Copy to Clipboard Toggle word wrap 
$ oc get pods -n default

Example: Get details about the python deployment in JSON format

Copy to Clipboard Toggle word wrap 
$ oc get deploymentconfig/python -o json

1.4.3.10. label

Update the labels on one or more resources.

Example: Update the python-1-mz2rf pod with the label status set to unhealthy

Copy to Clipboard Toggle word wrap 
$ oc label pod/python-1-mz2rf status=unhealthy

1.4.3.11. scale

Set the desired number of replicas for a replication controller or a deployment.

Example: Scale the ruby-app deployment to three pods

Copy to Clipboard Toggle word wrap 
$ oc scale deploymentconfig/ruby-app --replicas=3

1.4.3.12. secrets

Manage secrets in your project.

Example: Allow my-pull-secret to be used as an image pull secret by the default service account

Copy to Clipboard Toggle word wrap 
$ oc secrets link default my-pull-secret --for=pull

1.4.3.13. serviceaccounts

Get a token assigned to a service account or create a new token or kubeconfig file for a service account.

Example: Get the token assigned to the default service account

Copy to Clipboard Toggle word wrap 
$ oc serviceaccounts get-token default

1.4.3.14. set

Configure existing application resources.

Example: Set the name of a secret on a build config

Copy to Clipboard Toggle word wrap 
$ oc set build-secret --source buildconfig/mybc mysecret

1.4.4. Troubleshooting and debugging CLI commands

1.4.4.1. attach

Attach the shell to a running container.

Example: Get output from the python container from pod python-1-mz2rf

Copy to Clipboard Toggle word wrap 
$ oc attach python-1-mz2rf -c python

1.4.4.2. cp

Copy files and directories to and from containers.

Example: Copy a file from the python-1-mz2rf pod to the local file system

Copy to Clipboard Toggle word wrap 
$ oc cp default/python-1-mz2rf:/opt/app-root/src/README.md ~/mydirectory/.

1.4.4.3. debug

Launch a command shell to debug a running application.

Example: Debug the python deployment

Copy to Clipboard Toggle word wrap 
$ oc debug deploymentconfig/python

1.4.4.4. exec

Execute a command in a container.

Example: Execute the ls command in the python container from pod python-1-mz2rf

Copy to Clipboard Toggle word wrap 
$ oc exec python-1-mz2rf -c python ls

1.4.4.5. logs

Retrieve the log output for a specific build, build config, deployment, or pod.

Example: Stream the latest logs from the python deployment

Copy to Clipboard Toggle word wrap 
$ oc logs -f deploymentconfig/python

1.4.4.6. port-forward

Forward one or more local ports to a pod.

Example: Listen on port 8888 locally and forward to port 5000 in the pod

Copy to Clipboard Toggle word wrap 
$ oc port-forward python-1-mz2rf 8888:5000

1.4.4.7. proxy

Run a proxy to the Kubernetes API server.

Example: Run a proxy to the API server on port 8011 serving static content from ./local/www/

Copy to Clipboard Toggle word wrap 
$ oc proxy --port=8011 --www=./local/www/

1.4.4.8. rsh

Open a remote shell session to a container.

Example: Open a shell session on the first container in the python-1-mz2rf pod

Copy to Clipboard Toggle word wrap 
$ oc rsh python-1-mz2rf

1.4.4.9. rsync

Copy contents of a directory to or from a running pod container. Only changed files are copied using the rsync command from your operating system.

Example: Synchronize files from a local directory with a pod directory

Copy to Clipboard Toggle word wrap 
$ oc rsync ~/mydirectory/ python-1-mz2rf:/opt/app-root/src/

1.4.4.10. run

Create a pod running a particular image.

Example: Start a pod running the perl image

Copy to Clipboard Toggle word wrap 
$ oc run my-test --image=perl

1.4.4.11. wait

Wait for a specific condition on one or more resources.

Note

This command is experimental and might change without notice.

Example: Wait for the python-1-mz2rf pod to be deleted

Copy to Clipboard Toggle word wrap 
$ oc wait --for=delete pod/python-1-mz2rf

1.4.5. Advanced developer CLI commands

1.4.5.1. api-resources

Display the full list of API resources that the server supports.

Example: List the supported API resources

Copy to Clipboard Toggle word wrap 
$ oc api-resources

1.4.5.2. api-versions

Display the full list of API versions that the server supports.

Example: List the supported API versions

Copy to Clipboard Toggle word wrap 
$ oc api-versions

1.4.5.3. auth

Inspect permissions and reconcile RBAC roles.

Example: Check whether the current user can read pod logs

Copy to Clipboard Toggle word wrap 
$ oc auth can-i get pods --subresource=log

Example: Reconcile RBAC roles and permissions from a file

Copy to Clipboard Toggle word wrap 
$ oc auth reconcile -f policy.json

1.4.5.4. cluster-info

Display the address of the master and cluster services.

Example: Display cluster information

Copy to Clipboard Toggle word wrap 
$ oc cluster-info

1.4.5.5. convert

Convert a YAML or JSON configuration file to a different API version and print to standard output (stdout).

Example: Convert pod.yaml to the latest version

Copy to Clipboard Toggle word wrap 
$ oc convert -f pod.yaml

1.4.5.6. extract

Extract the contents of a config map or secret. Each key in the config map or secret is created as a separate file with the name of the key.

Example: Download the contents of the ruby-1-ca config map to the current directory

Copy to Clipboard Toggle word wrap 
$ oc extract configmap/ruby-1-ca

Example: Print the contents of the ruby-1-ca config map to stdout

Copy to Clipboard Toggle word wrap 
$ oc extract configmap/ruby-1-ca --to=-

1.4.5.7. idle

Idle scalable resources. An idled service will automatically become unidled when it receives traffic or it can be manually unidled using the oc scale command.

Example: Idle the ruby-app service

Copy to Clipboard Toggle word wrap 
$ oc idle ruby-app

1.4.5.8. image

Manage images in your OpenShift Container Platform cluster.

Example: Copy an image to another tag

Copy to Clipboard Toggle word wrap 
$ oc image mirror myregistry.com/myimage:latest myregistry.com/myimage:stable

1.4.5.9. observe

Observe changes to resources and take action on them.

Example: Observe changes to services

Copy to Clipboard Toggle word wrap 
$ oc observe services

1.4.5.10. patch

Updates one or more fields of an object using strategic merge patch in JSON or YAML format.

Example: Update the spec.unschedulable field for node node1 to true

Copy to Clipboard Toggle word wrap 
$ oc patch node/node1 -p '{"spec":{"unschedulable":true}}'

Note

If you must patch a custom resource definition, you must include the --type merge option in the command.

1.4.5.11. policy

Manage authorization policies.

Example: Add the edit role to user1 for the current project

Copy to Clipboard Toggle word wrap 
$ oc policy add-role-to-user edit user1

1.4.5.12. process

Process a template into a list of resources.

Example: Convert template.json to a resource list and pass to oc create

Copy to Clipboard Toggle word wrap 
$ oc process -f template.json | oc create -f -

1.4.5.13. registry

Manage the integrated registry on OpenShift Container Platform.

Example: Display information about the integrated registry

Copy to Clipboard Toggle word wrap 
$ oc registry info

1.4.5.14. replace

Modify an existing object based on the contents of the specified configuration file.

Example: Update a pod using the content in pod.json

Copy to Clipboard Toggle word wrap 
$ oc replace -f pod.json

1.4.6. Settings CLI commands

1.4.6.1. completion

Output shell completion code for the specified shell.

Example: Display completion code for Bash

Copy to Clipboard Toggle word wrap 
$ oc completion bash

1.4.6.2. config

Manage the client configuration files.

Example: Display the current configuration

Copy to Clipboard Toggle word wrap 
$ oc config view

Example: Switch to a different context

Copy to Clipboard Toggle word wrap 
$ oc config use-context test-context

1.4.6.3. logout

Log out of the current session.

Example: End the current session

Copy to Clipboard Toggle word wrap 
$ oc logout

1.4.6.4. whoami

Display information about the current session.

Example: Display the currently authenticated user

Copy to Clipboard Toggle word wrap 
$ oc whoami

1.4.7. Other developer CLI commands

1.4.7.1. help

Display general help information for the CLI and a list of available commands.

Example: Display available commands

Copy to Clipboard Toggle word wrap 
$ oc help

Example: Display the help for the new-project command

Copy to Clipboard Toggle word wrap 
$ oc help new-project

1.4.7.2. plugin

List the available plug-ins on the user’s PATH.

Example: List available plug-ins

Copy to Clipboard Toggle word wrap 
$ oc plugin list

1.4.7.3. version

Display the oc client and server versions.

Example: Display version information

Copy to Clipboard Toggle word wrap 
$ oc version

For cluster administrators, the OpenShift Container Platform server version is also displayed.

1.5. Administrator CLI commands

1.5.1. Cluster management CLI commands

1.5.1.1. inspect

Gather debugging information for a particular resource.

Note

This command is experimental and might change without notice.

Example: Collect debugging data for the OpenShift API server cluster Operator

Copy to Clipboard Toggle word wrap 
$ oc adm inspect clusteroperator/openshift-apiserver

1.5.1.2. must-gather

Bulk collect data about the current state of your cluster to debug issues.

Note

This command is experimental and might change without notice.

Example: Gather debugging information

Copy to Clipboard Toggle word wrap 
$ oc adm must-gather

1.5.1.3. top

Show usage statistics of resources on the server.

Example: Show CPU and memory usage for pods

Copy to Clipboard Toggle word wrap 
$ oc adm top pods

Example: Show usage statistics for images

Copy to Clipboard Toggle word wrap 
$ oc adm top images

1.5.2. Node management CLI commands

1.5.2.1. cordon

Mark a node as unschedulable. Manually marking a node as unschedulable blocks any new pods from being scheduled on the node, but does not affect existing pods on the node.

Example: Mark node1 as unschedulable

Copy to Clipboard Toggle word wrap 
$ oc adm cordon node1

1.5.2.2. drain

Drain a node in preparation for maintenance.

Example: Drain node1

Copy to Clipboard Toggle word wrap 
$ oc adm drain node1

1.5.2.3. node-logs

Display and filter node logs.

Example: Get logs for NetworkManager

Copy to Clipboard Toggle word wrap 
$ oc adm node-logs --role master -u NetworkManager.service

1.5.2.4. taint

Update the taints on one or more nodes.

Example: Add a taint to dedicate a node for a set of users

Copy to Clipboard Toggle word wrap 
$ oc adm taint nodes node1 dedicated=groupName:NoSchedule

Example: Remove the taints with key dedicated from node node1

Copy to Clipboard Toggle word wrap 
$ oc adm taint nodes node1 dedicated-

1.5.2.5. uncordon

Mark a node as schedulable.

Example: Mark node1 as schedulable

Copy to Clipboard Toggle word wrap 
$ oc adm uncordon node1

1.5.3. Security and policy CLI commands

1.5.3.1. certificate

Approve or reject certificate signing requests (CSRs).

Example: Approve a CSR

Copy to Clipboard Toggle word wrap 
$ oc adm certificate approve csr-sqgzp

1.5.3.2. groups

Manage groups in your cluster.

Example: Create a new group

Copy to Clipboard Toggle word wrap 
$ oc adm groups new my-group

1.5.3.3. new-project

Create a new project and specify administrative options.

Example: Create a new project using a node selector

Copy to Clipboard Toggle word wrap 
$ oc adm new-project myproject --node-selector='type=user-node,region=east'

1.5.3.4. pod-network

Manage pod networks in the cluster.

Example: Isolate project1 and project2 from other non-global projects

Copy to Clipboard Toggle word wrap 
$ oc adm pod-network isolate-projects project1 project2

1.5.3.5. policy

Manage roles and policies on the cluster.

Example: Add the edit role to user1 for all projects

Copy to Clipboard Toggle word wrap 
$ oc adm policy add-cluster-role-to-user edit user1

Example: Add the privileged security context constraint to a service account

Copy to Clipboard Toggle word wrap 
$ oc adm policy add-scc-to-user privileged -z myserviceaccount

1.5.4. Maintenance CLI commands

1.5.4.1. migrate

Migrate resources on the cluster to a new version or format depending on the subcommand used.

Example: Perform an update of all stored objects

Copy to Clipboard Toggle word wrap 
$ oc adm migrate storage

Example: Perform an update of only pods

Copy to Clipboard Toggle word wrap 
$ oc adm migrate storage --include=pods

1.5.4.2. prune

Remove older versions of resources from the server.

Example: Prune older builds including those whose build configs no longer exist

Copy to Clipboard Toggle word wrap 
$ oc adm prune builds --orphans

1.5.5. Configuration CLI commands

1.5.5.1. create-bootstrap-project-template

Create a bootstrap project template.

Example: Output a bootstrap project template in YAML format to stdout

Copy to Clipboard Toggle word wrap 
$ oc adm create-bootstrap-project-template -o yaml

1.5.5.2. create-error-template

Create a template for customizing the error page.

Example: Output a template for the error page to stdout

Copy to Clipboard Toggle word wrap 
$ oc adm create-error-template

1.5.5.3. create-kubeconfig

Creates a basic .kubeconfig file from client certificates.

Example: Create a .kubeconfig file with the provided client certificates

Copy to Clipboard Toggle word wrap 
$ oc adm create-kubeconfig \
  --client-certificate=/path/to/client.crt \
  --client-key=/path/to/client.key \
  --certificate-authority=/path/to/ca.crt

1.5.5.4. create-login-template

Create a template for customizing the login page.

Example: Output a template for the login page to stdout

Copy to Clipboard Toggle word wrap 
$ oc adm create-login-template

1.5.5.5. create-provider-selection-template

Create a template for customizing the provider selection page.

Example: Output a template for the provider selection page to stdout

Copy to Clipboard Toggle word wrap 
$ oc adm create-provider-selection-template

1.5.6. Other Administrator CLI commands

1.5.6.1. build-chain

Output the inputs and dependencies of any builds.

Example: Output dependencies for the perl imagestream

Copy to Clipboard Toggle word wrap 
$ oc adm build-chain perl

1.5.6.2. completion

Output shell completion code for the oc adm commands for the specified shell.

Example: Display oc adm completion code for Bash

Copy to Clipboard Toggle word wrap 
$ oc adm completion bash

1.5.6.3. config

Manage the client configuration files. This command has the same behavior as the oc config command.

Example: Display the current configuration

Copy to Clipboard Toggle word wrap 
$ oc adm config view

Example: Switch to a different context

Copy to Clipboard Toggle word wrap 
$ oc adm config use-context test-context

1.5.6.4. release

Manage various aspects of the OpenShift Container Platform release process, such as viewing information about a release or inspecting the contents of a release.

Example: Generate a changelog between two releases and save to changelog.md

Copy to Clipboard Toggle word wrap 
$ oc adm release info --changelog=/tmp/git \
    quay.io/openshift-release-dev/ocp-release:4.5.0-rc.7-x86_64 \
    quay.io/openshift-release-dev/ocp-release:4.5.4-x86_64 \
    > changelog.md

1.5.6.5. verify-image-signature

Verify the image signature of an image imported to the internal registry using the local public GPG key.

Example: Verify the nodejs image signature

Copy to Clipboard Toggle word wrap 
$ oc adm verify-image-signature \
    sha256:2bba968aedb7dd2aafe5fa8c7453f5ac36a0b9639f1bf5b03f95de325238b288 \
    --expected-identity 172.30.1.1:5000/openshift/nodejs:latest \
    --public-key /etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release \
    --save

1.6. Usage of oc and kubectl commands

Kubernetes' command line interface (CLI), kubectl, can be used to run commands against a Kubernetes cluster. Because OpenShift Container Platform is a certified Kubernetes distribution, you can use the supported kubectl binaries that ship with OpenShift Container Platform, or you can gain extended functionality by using the oc binary.

1.6.1. The oc binary

The oc binary offers the same capabilities as the kubectl binary, but it extends to natively support additional OpenShift Container Platform features, including:

  • Full support for OpenShift Container Platform resources

    Resources such as DeploymentConfig, BuildConfig, Route, ImageStream, and ImageStreamTag objects are specific to OpenShift Container Platform distributions, and build upon standard Kubernetes primitives.

  • Authentication

    The oc binary offers a built-in login command that allows authentication and enables you to work with OpenShift Container Platform projects, which map Kubernetes namespaces to authenticated users. See Understanding authentication for more information.

  • Additional commands

    The additional command oc new-app, for example, makes it easier to get new applications started using existing source code or pre-built images. Similarly, the additional command oc new-project makes it easier to start a project that you can switch to as your default.

1.6.2. The kubectl binary

The kubectl binary is provided as a means to support existing workflows and scripts for new OpenShift Container Platform users coming from a standard Kubernetes environment, or for those who prefer to use the kubectl CLI. Existing users of kubectl can continue to use the binary to interact with Kubernetes primitives, with no changes required to the OpenShift Container Platform cluster.

You can install the supported kubectl binary by following the steps to Install the CLI. The kubectl binary is included in the archive if you download the binary, or is installed when you install the CLI by using an RPM.

For more information, see the kubectl documentation.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat, Inc.