Chapter 4. Developer CLI commands


4.1. Basic CLI commands

4.1.1. explain

Display documentation for a certain resource.

Example: Display documentation for Pods

$ oc explain pods

4.1.2. login

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

Example: Interactive login

$ oc login

Example: Log in specifying a user name

$ oc login -u user1

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

$ oc new-app .

Example: Create a new application from a remote Git repository

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

Example: Create a new application from a private remote repository

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

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

$ oc new-project myproject

4.1.5. project

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

Example: Switch to a different project

$ oc project test-project

4.1.6. projects

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

Example: List all projects

$ oc projects

4.1.7. status

Show a high-level overview of the current project.

Example: Show the status of the current project

$ oc status

4.2. Build and Deploy CLI commands

4.2.1. cancel-build

Cancel a running, pending, or new build.

Example: Cancel a build

$ oc cancel-build python-1

Example: Cancel all pending builds from the python BuildConfig

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

4.2.2. import-image

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

Example: Import the latest image information

$ oc import-image my-ruby

4.2.3. new-build

Create a new BuildConfig from source code.

Example: Create a BuildConfig from a local Git repository

$ oc new-build .

Example: Create a BuildConfig from a remote Git repository

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

4.2.4. rollback

Revert an application back to a previous Deployment.

Example: Roll back to the last successful Deployment

$ oc rollback php

Example: Roll back to a specific version

$ oc rollback php --to-version=3

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

$ oc rollout undo deploymentconfig/php

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

$ oc rollout latest deploymentconfig/php

4.2.6. start-build

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

Example: Start a build from the specified BuildConfig

$ oc start-build python

Example: Start a build from a previous build

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

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

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

4.2.7. tag

Tag existing images into imagestreams.

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

$ oc tag ruby:latest ruby:2.0

4.3. Application management CLI commands

4.3.1. annotate

Update the annotations on one or more resources.

Example: Add an annotation to a Route

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

Example: Remove the annotation from the Route

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

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

$ oc apply -f pod.json

4.3.3. autoscale

Autoscale a DeploymentConfig or ReplicationController.

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

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

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

$ oc create -f pod.json

4.3.5. delete

Delete a resource.

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

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

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

$ oc delete pods -l app=parksmap-katacoda

4.3.6. describe

Return detailed information about a specific object.

Example: Describe a Deployment named example

$ oc describe deployment/example

Example: Describe all Pods

$ oc describe pods

4.3.7. edit

Edit a resource.

Example: Edit a DeploymentConfig using the default editor

$ oc edit deploymentconfig/parksmap-katacoda

Example: Edit a DeploymentConfig using a different editor

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

Example: Edit a DeploymentConfig in JSON format

$ oc edit deploymentconfig/parksmap-katacoda -o json

4.3.8. expose

Expose a Service externally as a Route.

Example: Expose a Service

$ oc expose service/parksmap-katacoda

Example: Expose a Service and specify the host name

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

4.3.9. get

Display one or more resources.

Example: List Pods in the default namespace

$ oc get pods -n default

Example: Get details about the python DeploymentConfig in JSON format

$ oc get deploymentconfig/python -o json

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

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

4.3.11. scale

Set the desired number of replicas for a ReplicationController or a DeploymentConfig.

Example: Scale the ruby-app DeploymentConfig to three Pods

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

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

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

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

$ oc serviceaccounts get-token default

4.3.14. set

Configure existing application resources.

Example: Sets the name of a secret on a BuildConfig

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

4.4. Troubleshooting and debugging CLI commands

4.4.1. attach

Attach the shell to a running container.

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

$ oc attach python-1-mz2rf -c python

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

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

4.4.3. debug

Launch a command shell to debug a running application.

Example: Debug the python Deployment

$ oc debug deploymentconfig/python

4.4.4. exec

Execute a command in a container.

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

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

4.4.5. logs

Retrieve the log output for a specific build, BuildConfig, DeploymentConfig, or Pod.

Example: Stream the latest logs from the python DeploymentConfig

$ oc logs -f deploymentconfig/python

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

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

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/

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

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

$ oc rsh python-1-mz2rf

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

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

4.4.10. run

Create and run a particular image. By default, this creates a DeploymentConfig to manage the created containers.

Example: Start an instance of the perl image with three replicas

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

4.4.11. wait

Wait for a specific condition on one or more resources.

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

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

4.5. Advanced developer CLI commands

4.5.1. api-resources

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

Example: List the supported API resources

$ oc api-resources

4.5.2. api-versions

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

Example: List the supported API versions

$ oc api-versions

4.5.3. auth

Inspect permissions and reconcile RBAC roles.

Example: Check whether the current user can read Pod logs

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

Example: Reconcile RBAC roles and permissions from a file

$ oc auth reconcile -f policy.json

4.5.4. cluster-info

Display the address of the master and cluster services.

Example: Display cluster information

$ oc cluster-info

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

$ oc convert -f pod.yaml

4.5.6. extract

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.

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

$ oc extract configmap/ruby-1-ca

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

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

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

$ oc idle ruby-app

4.5.8. image

Manage images in your OpenShift Container Platform cluster.

Example: Copy an image to another tag

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

4.5.9. observe

Observe changes to resources and take action on them.

Example: Observe changes to Services

$ oc observe services

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

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

4.5.11. policy

Manage authorization policies.

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

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

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

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

4.5.13. registry

Manage the integrated registry on OpenShift Container Platform.

Example: Display information about the integrated registry

$ oc registry info

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

$ oc replace -f pod.json

4.6. Settings CLI commands

4.6.1. completion

Output shell completion code for the specified shell.

Example: Display completion code for Bash

$ oc completion bash

4.6.2. config

Manage the client configuration files.

Example: Display the current configuration

$ oc config view

Example: Switch to a different context

$ oc config use-context test-context

4.6.3. logout

Log out of the current session.

Example: End the current session

$ oc logout

4.6.4. whoami

Display information about the current session.

Example: Display the currently authenticated user

$ oc whoami

4.7. Other developer CLI commands

4.7.1. help

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

Example: Display available commands

$ oc help

Example: Display the help for the new-project command

$ oc help new-project

4.7.2. plugin

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

Example: List available plug-ins

$ oc plugin list

4.7.3. version

Display the oc client and server versions.

Example: Display version information

$ oc version

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.

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.

© 2024 Red Hat, Inc.