Getting started with the OpenShift CLI

About the OpenShift CLI

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

  • Working directly with project source code

  • Scripting OKD operations

  • Managing projects while restricted by bandwidth resources and the web console is unavailable

Installing the OpenShift CLI

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

Installing the OpenShift CLI by downloading the binary

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

If you installed an earlier version of oc, you cannot use it to complete all of the commands in OKD 4.6. Download and install the new version of oc.

Installing the OpenShift CLI on Linux

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

Procedure

  1. Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture.

  2. Download oc.tar.gz.

  3. Unpack the archive:

    1. $ tar xvzf <file>

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

    To check your PATH, execute the following command:

    1. $ echo $PATH

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

  1. $ oc <command>

Installing the OpenShift CLI on Windows

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

Procedure

  1. Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture.

  2. Download oc.zip.

  3. Unzip the archive with a ZIP program.

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

    1. C:\> path

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

  1. C:\> oc <command>

Installing the OpenShift CLI on macOS

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

Procedure

  1. Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture.

  2. Download oc.tar.gz.

  3. Unpack and unzip the archive.

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

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

    1. $ echo $PATH

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

  1. $ oc <command>

Logging in to the OpenShift CLI

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

Prerequisites

  • You must have access to an OKD cluster.

  • You must have installed the CLI.

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.

    1. $ oc login

    Example output

    1. Server [https://localhost:8443]: https://openshift.example.com:6443 (1)
    2. The server uses a certificate signed by an unknown authority.
    3. You can bypass the certificate check, but any data you send to the server could be intercepted by others.
    4. Use insecure connections? (y/n): y (2)
    6. Authentication required for https://openshift.example.com:6443 (openshift)
    7. Username: user1 (3)
    8. Password: (4)
    9. Login successful.
    11. You don't have any projects. You can try to create a new project, by running
    13.     oc new-project <projectname>
    15. Welcome! See 'oc help' to get started.
    1Enter the OKD server URL.
    2Enter whether to use insecure connections.
    3Enter the user name to log in as.
    4Enter the user’s password.

If you are logged in to the web console, you can generate an oc login command that includes your token and server information. You can use the command to log in to the OKD CLI without the interactive prompts. To generate the command, select Copy login command from the username drop-down menu at the top right of the web console.

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

Using the OpenShift CLI

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

Creating a project

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

  1. $ oc new-project my-project

Example output

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

Creating a new app

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

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

Example output

  1. --> Found image 40de956 (9 days old) in imagestream "openshift/php" under tag "7.2" for "php"
  3. ...
  5.     Run 'oc status' to view your app.

Viewing pods

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

  1. $ oc get pods -o wide

Example output

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

Viewing pod logs

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

  1. $ oc logs cakephp-ex-1-deploy

Example output

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

Viewing the current project

Use the oc project command to view the current project.

  1. $ oc project

Example output

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

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.

  1. $ oc status

Example output

  1. In project my-project on server https://openshift.example.com:6443
  3. svc/cakephp-ex - 172.30.236.80 ports 8080, 8443
  4.   dc/cakephp-ex deploys istag/cakephp-ex:latest <-
  5.     bc/cakephp-ex source builds https://github.com/sclorg/cakephp-ex on openshift/php:7.2
  6.     deployment #1 deployed 2 minutes ago - 1 pod
  8. 3 infos identified, use 'oc status --suggest' to see details.

Listing supported API resources

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

  1. $ oc api-resources

Example output

  1. NAME                                  SHORTNAMES       APIGROUP                              NAMESPACED   KIND
  2. bindings                                                                                     true         Binding
  3. componentstatuses                     cs                                                     false        ComponentStatus
  4. configmaps                            cm                                                     true         ConfigMap
  5. ...

Getting help

You can get help with CLI commands and OKD 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

    1. $ oc help

    Example output

    1. OpenShift Client
    3. This client helps you develop, build, deploy, and run your applications on any OpenShift or Kubernetes compatible
    4. platform. It also includes the administrative commands for managing a cluster under the 'adm' subcommand.
    6. Usage:
    7.   oc [flags]
    9. Basic Commands:
    10.   login           Log in to a server
    11.   new-project     Request a new project
    12.   new-app         Create a new application
    14. ...

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

    Example: Get help for the oc create command

    1. $ oc create --help

    Example output

    1. Create a resource by filename or stdin
    3. JSON and YAML formats are accepted.
    5. Usage:
    6.   oc create -f FILENAME [flags]
    8. ...

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

    Example: View documentation for the Pod resource

    1. $ oc explain pods

    Example output

    1. KIND:     Pod
    2. VERSION:  v1
    4. DESCRIPTION:
    5.      Pod is a collection of containers that can run on a host. This resource is
    6.      created by clients and scheduled onto hosts.
    8. FIELDS:
    9.    apiVersion    <string>
    10.      APIVersion defines the versioned schema of this representation of an
    11.      object. Servers should convert recognized schemas to the latest internal
    12.      value, and may reject unrecognized values. More info:
    13.      https://git.k8s.io/community/contributors/devel/api-conventions.md#resources
    15. ...

Logging out of the OpenShift CLI

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

  • Use the oc logout command.

    1. $ oc logout

    Example output

    1. Logged "user1" out on "https://openshift.example.com"

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