Chapter 1. Getting started with the CLI
1.1. About the CLI
With the OpenShift Container Platform command-line interface (CLI), you can create applications and manage OpenShift Container Platform projects from a terminal. The CLI is ideal in situations where you:
- Work directly with project source code.
- Script OpenShift Container Platform operations.
- Are restricted by bandwidth resources and can not use the web console.
1.2. Installing the CLI
You can install the CLI in order to interact with OpenShift Container Platform using a command-line interface.
- From the Infrastructure Provider page on the Red Hat OpenShift Cluster Manager site, navigate to the page for your installation type and click Download Command-line Tools.
- Click the folder for your operating system and architecture and click the compressed file.
- Save the file to your file system.
- Extract the compressed file.
Place it in a directory that is on your
After you install the CLI, it is available using the
$ oc <command>
1.3. Logging in to the CLI
You can log in to the
oc CLI to access and manage your cluster.
- You must have access to an OpenShift Container Platform cluster.
- You must have installed the CLI.
Log in to the CLI using the
oc logincommand and enter the required information when prompted.
$ oc login 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 3 Password: 4 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.
You can now create a project or issue other commands for managing your cluster.
1.4. Using the CLI
Review the following sections to learn how to complete common tasks using the CLI.
1.4.1. Creating a project
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".
1.4.2. Creating a new app
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.
1.4.3. Viewing pods
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>
1.4.4. Viewing pod logs
oc logs command to view logs for a particular pod.
$ oc logs cakephp-ex-1-deploy --> Scaling cakephp-ex-1 to 1 --> Success
1.4.5. Viewing the current project
oc project command to view the current project.
$ oc project Using project "my-project" on server "https://openshift.example.com:6443".
1.4.6. Viewing the status for the current project
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.
1.4.7. Listing supported API resources
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 ...
1.5. Getting help
You can get help with CLI commands and OpenShift Container Platform resources in the following ways.
oc helpto get a list and description of all available CLI commands:
Example: Get general help for the CLI
$ oc help 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 ...
--helpflag to get help about a specific CLI command:
Example: Get help for the
$ oc create --help Create a resource by filename or stdin JSON and YAML formats are accepted. Usage: oc create -f FILENAME [flags] ...
oc explaincommand to view the description and fields for a particular resource:
Example: View documentation for the Pod resource
$ oc explain pods 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 ...
1.6. Logging out of the CLI
You can log out the CLI to end your current session.
$ oc logout Logged "user1" out on "https://openshift.example.com"
This deletes the saved authentication token from the server and removes it from your configuration file.