Chapter 1. OpenShift CLI (oc)

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.

$ 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>

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, DeploymentConfigs, and BuildConfigs.

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

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

$ 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 BuildConfig 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 BuildConfig 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 imagestreams.

$ 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 DeploymentConfig or ReplicationController.

$ 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 ReplicationController or a DeploymentConfig.

$ 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, BuildConfig, DeploymentConfig, 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 and run a particular image. By default, this creates a DeploymentConfig to manage the created containers.

$ oc run my-test --image=perl --replicas=3

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

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

$ oc convert -f pod.yaml

Extract the contents of a ConfigMap or secret. Each key in the ConfigMap 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 client configuration for connecting to the server. This creates a folder containing a client certificate, a client key, a server certificate authority, and a kubeconfig file for connecting to the master as the provided user.

$ oc adm create-api-client-config \
  --certificate-authority='/etc/origin/master/proxyca.crt' \
  --client-dir='/etc/origin/master/proxy' \
  --signer-cert='/etc/origin/master/proxyca.crt' \
  --signer-key='/etc/origin/master/proxyca.key' \
  --signer-serial='/etc/origin/master/proxyca.serial.txt' \
  --user='system:proxy'

Create the default bootstrap policy.

$ oc adm create-bootstrap-policy-file --filename=policy.json

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.3.0-rc.7 \
    quay.io/openshift-release-dev/ocp-release:4.3.0 \
    > 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