Chapter 2. OpenShift CLI (oc)

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

$ oc <command>

C:\> oc <command>

$ oc <command>

You can install the OpenShift CLI (oc) to interact with OpenShift Container Platform from a web console. You can install oc on Linux, Windows, or macOS.

$ oc <command>

C:\> oc <command>

$ oc <command>

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.

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

$ oc <command>

For macOS, you can install the OpenShift CLI (oc) by using the Homebrew package manager.

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

$ oc new-project my-project

Now using project "my-project" on server "https://openshift.example.com:6443".

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

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

--> Found image 40de956 (9 days old) in imagestream "openshift/php" under tag "7.2" for "php"

...

    Run 'oc status' to view your app.

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

$ oc get pods -o wide

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>

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

$ oc logs cakephp-ex-1-deploy

--> Scaling cakephp-ex-1 to 1
--> Success

Use the oc project command to view the current project.

$ oc project

Using project "my-project" on server "https://openshift.example.com:6443".

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

$ oc status

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.

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

$ oc api-resources

NAME                                  SHORTNAMES       APIGROUP                              NAMESPACED   KIND
bindings                                                                                     true         Binding
componentstatuses                     cs                                                     false        ComponentStatus
configmaps                            cm                                                     true         ConfigMap
...

After you install the OpenShift CLI (oc), you can enable tab completion to automatically complete oc commands or suggest options when you press Tab. The following procedure enables tab completion for the Bash shell.

Tab completion is enabled when you open a new terminal.

After you install the OpenShift CLI (oc), you can enable tab completion to automatically complete oc commands or suggest options when you press Tab. The following procedure enables tab completion for the Zsh shell.

Tab completion is enabled when you open a new terminal.

Display documentation for a certain resource.

$ oc explain pods

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

$ oc login -u user1

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

$ oc new-app .

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

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

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

$ oc new-project myproject

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

$ oc project test-project

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

$ oc projects

Show a high-level overview of the current project.

$ oc status

Cancel a running, pending, or new build.

$ oc cancel-build python-1

$ oc cancel-build buildconfig/python --state=pending

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

$ oc import-image my-ruby

Create a new build config from source code.

$ oc new-build .

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

Revert an application back to a previous deployment.

$ oc rollback php

$ oc rollback php --to-version=3

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

$ oc rollout undo deploymentconfig/php

$ oc rollout latest deploymentconfig/php

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

$ oc start-build python

$ oc start-build --from-build=python-1

$ oc start-build python --env=mykey=myvalue

Tag existing images into image streams.

$ oc tag ruby:latest ruby:2.0

Update the annotations on one or more resources.

$ oc annotate route/test-route haproxy.router.openshift.io/ip_whitelist="192.168.1.10"

$ oc annotate route/test-route haproxy.router.openshift.io/ip_whitelist-

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

$ oc apply -f pod.json

Autoscale a deployment or replication controller.

$ oc autoscale deploymentconfig/parksmap-katacoda --min=2 --max=5

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

$ oc create -f pod.json

Delete a resource.

$ oc delete pod/parksmap-katacoda-1-qfqz4

$ oc delete pods -l app=parksmap-katacoda

Return detailed information about a specific object.

$ oc describe deployment/example

$ oc describe pods

Edit a resource.

$ oc edit deploymentconfig/parksmap-katacoda

$ OC_EDITOR="nano" oc edit deploymentconfig/parksmap-katacoda

$ oc edit deploymentconfig/parksmap-katacoda -o json

Expose a service externally as a route.

$ oc expose service/parksmap-katacoda

$ oc expose service/parksmap-katacoda --hostname=www.my-host.com

Display one or more resources.

$ oc get pods -n default

$ oc get deploymentconfig/python -o json

Update the labels on one or more resources.

$ oc label pod/python-1-mz2rf status=unhealthy

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

$ oc scale deploymentconfig/ruby-app --replicas=3

Manage secrets in your project.

$ oc secrets link default my-pull-secret --for=pull

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

$ oc serviceaccounts get-token default

Configure existing application resources.

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

Attach the shell to a running container.

$ oc attach python-1-mz2rf -c python

Copy files and directories to and from containers.

$ oc cp default/python-1-mz2rf:/opt/app-root/src/README.md ~/mydirectory/.

Launch a command shell to debug a running application.

$ oc debug deploymentconfig/python

Execute a command in a container.

$ oc exec python-1-mz2rf -c python ls

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

$ oc logs -f deploymentconfig/python

Forward one or more local ports to a pod.

$ oc port-forward python-1-mz2rf 8888:5000

Run a proxy to the Kubernetes API server.

$ oc proxy --port=8011 --www=./local/www/

Open a remote shell session to a container.

$ oc rsh python-1-mz2rf

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.

$ oc rsync ~/mydirectory/ python-1-mz2rf:/opt/app-root/src/

Create a pod running a particular image.

$ oc run my-test --image=perl

Wait for a specific condition on one or more resources.

$ oc wait --for=delete pod/python-1-mz2rf

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

$ oc api-resources

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

$ oc api-versions

Inspect permissions and reconcile RBAC roles.

$ oc auth can-i get pods --subresource=log

$ oc auth reconcile -f policy.json

Display the address of the master and cluster services.

$ oc cluster-info

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.

$ oc extract configmap/ruby-1-ca

$ oc extract configmap/ruby-1-ca --to=-

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.

$ oc idle ruby-app

Manage images in your OpenShift Container Platform cluster.

$ oc image mirror myregistry.com/myimage:latest myregistry.com/myimage:stable

Observe changes to resources and take action on them.

$ oc observe services

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

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

Manage authorization policies.

$ oc policy add-role-to-user edit user1

Process a template into a list of resources.

$ oc process -f template.json | oc create -f -

Manage the integrated registry on OpenShift Container Platform.

$ oc registry info

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

$ oc replace -f pod.json

Output shell completion code for the specified shell.

$ oc completion bash

Manage the client configuration files.

$ oc config view

$ oc config use-context test-context

Log out of the current session.

$ oc logout

Display information about the current session.

$ oc whoami

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

$ oc help

$ oc help new-project

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

$ oc plugin list

Display the oc client and server versions.

$ oc version

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

Gather debugging information for a particular resource.

$ oc adm inspect clusteroperator/openshift-apiserver

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

$ oc adm must-gather

Show usage statistics of resources on the server.

$ oc adm top pods

$ oc adm top images

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.

$ oc adm cordon node1

Drain a node in preparation for maintenance.

$ oc adm drain node1

Display and filter node logs.

$ oc adm node-logs --role master -u NetworkManager.service

Update the taints on one or more nodes.

$ oc adm taint nodes node1 dedicated=groupName:NoSchedule

$ oc adm taint nodes node1 dedicated-

Mark a node as schedulable.

$ oc adm uncordon node1

Approve or reject certificate signing requests (CSRs).

$ oc adm certificate approve csr-sqgzp

Manage groups in your cluster.

$ oc adm groups new my-group

Create a new project and specify administrative options.

$ oc adm new-project myproject --node-selector='type=user-node,region=east'

Manage pod networks in the cluster.

$ oc adm pod-network isolate-projects project1 project2

Manage roles and policies on the cluster.

$ oc adm policy add-cluster-role-to-user edit user1

$ oc adm policy add-scc-to-user privileged -z myserviceaccount

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

$ oc adm migrate storage

$ oc adm migrate storage --include=pods

Remove older versions of resources from the server.

$ oc adm prune builds --orphans

Create a bootstrap project template.

$ oc adm create-bootstrap-project-template -o yaml

Create a template for customizing the error page.

$ oc adm create-error-template

Creates a basic .kubeconfig file from client certificates.

$ oc adm create-kubeconfig \
  --client-certificate=/path/to/client.crt \
  --client-key=/path/to/client.key \
  --certificate-authority=/path/to/ca.crt

Create a template for customizing the login page.

$ oc adm create-login-template

Create a template for customizing the provider selection page.

$ oc adm create-provider-selection-template

Output the inputs and dependencies of any builds.

$ oc adm build-chain perl

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

$ oc adm completion bash

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

$ oc adm config view

$ oc adm config use-context test-context

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

$ oc adm release info --changelog=/tmp/git \
    quay.io/openshift-release-dev/ocp-release:4.7.0-x86_64 \
    quay.io/openshift-release-dev/ocp-release:4.7.1-x86_64 \
    > changelog.md

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

$ 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