Getting started with the OpenShift CLI
- About the OpenShift CLI
- Installing the OpenShift CLI
- Logging in to the OpenShift CLI
- Using the OpenShift CLI
- Getting help
- Logging out of 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
) 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 |
Installing the OpenShift CLI on Linux
You can install the OpenShift CLI (oc
) binary on Linux by using the following procedure.
Procedure
Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture.
Download
oc.tar.gz
.Unpack the archive:
$ tar xvzf <file>
Place the
oc
binary in a directory that is on yourPATH
.To check your
PATH
, execute the following command:$ echo $PATH
After you install the OpenShift CLI, it is available using the oc
command:
$ oc <command>
Installing the OpenShift CLI on Windows
You can install the OpenShift CLI (oc
) binary on Windows by using the following procedure.
Procedure
Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture.
Download
oc.zip
.Unzip the archive with a ZIP program.
Move the
oc
binary to a directory that is on yourPATH
.To check your
PATH
, open the command prompt and execute the following command:C:\> path
After you install the OpenShift CLI, it is available using the oc
command:
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
Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture.
Download
oc.tar.gz
.Unpack and unzip the archive.
Move the
oc
binary to a directory on your PATH.To check your
PATH
, open a terminal and execute the following command:$ echo $PATH
After you install the OpenShift CLI, it is available using the oc
command:
$ oc <command>
Installing the OpenShift CLI by using the web console
You can install the OpenShift CLI (oc
) to interact with OKD from a web console. You can install oc
on Linux, Windows, or macOS.
If you installed an earlier version of |
Installing the OpenShift CLI on Linux using the web console
You can install the OpenShift CLI (oc
) binary on Linux by using the following procedure.
Procedure
From the web console, click ?.
Click Command Line Tools.
Select appropriate
oc
binary for your Linux platform, and then click Download oc for Linux.Save the file.
Unpack the archive.
$ tar xvzf <file>
Move the
oc
binary to a directory that is on yourPATH
.To check your
PATH
, execute the following command:$ echo $PATH
After you install the OpenShift CLI, it is available using the oc
command:
$ oc <command>
Installing the OpenShift CLI on Windows using the web console
You can install the OpenShift CLI (oc
) binary on Winndows by using the following procedure.
Procedure
From the web console, click ?.
Click Command Line Tools.
Select the
oc
binary for Windows platform, and then click Download oc for Windows for x86_64.Save the file.
Unzip the archive with a ZIP program.
Move the
oc
binary to a directory that is on yourPATH
.To check your
PATH
, open the command prompt and execute the following command:C:\> path
After you install the OpenShift CLI, it is available using the oc
command:
C:\> oc <command>
Installing the OpenShift CLI on macOS using the web console
You can install the OpenShift CLI (oc
) binary on macOS by using the following procedure.
Procedure
From the web console, click ?.
Click Command Line Tools.
Select the
oc
binary for macOS platform, and then click Download oc for Mac for x86_64.Save the file.
Unpack and unzip the archive.
Move the
oc
binary to a directory on your PATH.To check your
PATH
, open a terminal and execute the following command:$ echo $PATH
After you install the OpenShift CLI, it is available using the oc
command:
$ oc <command>
Logging in to the OpenShift CLI
You can log in to the OpenShift CLI (oc
) to access and manage your cluster.
Prerequisites
You must have access to an OKD cluster.
You must have installed the OpenShift CLI (
oc
).
To access a cluster that is accessible only over an HTTP proxy server, you can set the |
Procedure
Enter the
oc login
command and pass in a user name:$ oc login -u user1
When prompted, enter the required information:
Example output
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
Password: (3)
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 OKD server URL. 2 Enter whether to use insecure connections. 3 Enter the user’s password.
If you are logged in to the web console, you can generate an |
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.
$ oc new-project my-project
Example output
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.
$ oc new-app https://github.com/sclorg/cakephp-ex
Example output
--> Found image 40de956 (9 days old) in imagestream "openshift/php" under tag "7.2" for "php"
...
Run 'oc status' to view your app.
Viewing pods
Use the oc get pods
command to view the pods for the current project.
$ oc get pods -o wide
Example output
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>
Viewing pod logs
Use the oc logs
command to view logs for a particular pod.
$ oc logs cakephp-ex-1-deploy
Example output
--> Scaling cakephp-ex-1 to 1
--> Success
Viewing the current project
Use the oc project
command to view the current project.
$ oc project
Example output
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.
$ oc status
Example output
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.
Listing supported API resources
Use the oc api-resources
command to view the list of supported API resources on the server.
$ oc api-resources
Example output
NAME SHORTNAMES APIGROUP NAMESPACED KIND
bindings true Binding
componentstatuses cs false ComponentStatus
configmaps cm true ConfigMap
...
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
$ oc help
Example output
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$ oc create --help
Example output
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$ oc explain pods
Example output
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
...
Logging out of the OpenShift CLI
You can log out the OpenShift CLI to end your current session.
Use the
oc logout
command.$ oc logout
Example output
Logged "user1" out on "https://openshift.example.com"
This deletes the saved authentication token from the server and removes it from your configuration file.