This is a cache of https://docs.openshift.com/aro/3/cli_reference/get_started_cli.html. It is a snapshot of the page at 2024-11-25T21:06:18.875+0000.
Get Started with the CLI | CLI Reference | Azure Red Hat OpenShift 3
    OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
×

Get Started with the CLI

Important

Azure Red Hat OpenShift 3.11 will be retired 30 June 2022. Support for creation of new Azure Red Hat OpenShift 3.11 clusters continues through 30 November 2020. Following retirement, remaining Azure Red Hat OpenShift 3.11 clusters will be shut down to prevent security vulnerabilities.

Follow this guide to create an Azure Red Hat OpenShift 4 cluster. If you have specific questions, please contact us

Overview

The Azure Red Hat OpenShift CLI exposes commands for managing your applications, as well as lower level tools to interact with each component of your system. This topic guides you through getting started with the CLI, including installation and logging in to create your first project.

Installing the CLI

The easiest way to download the CLI is by accessing the Command Line Tools page on the web console:

Command Line Tools

Installation options for the CLI vary depending on your operating system.

To log in using the CLI, collect your token from the web console’s Command Line page, which is accessed from Command Line Tools in the Help menu. The token is hidden, so you must click the copy to clipboard button at the end of the oc login line on the Command Line Tools page, then paste the copied contents to show the token.

For Windows

Then, unzip the archive with a ZIP program and move the oc binary to a directory on your PATH. To check your PATH, open the Command Prompt and run:

C:\> path

For Mac OS X

Then, and move the oc binary to a directory on your PATH. To check your PATH, open a Terminal window and run:

$ echo $PATH

For Linux

Then, unpack the archive and move the oc binary to a directory on your PATH. To check your path, run:

$ echo $PATH

To unpack the archive:

$ tar -xf <file>

If you do not use RHEL or Fedora, ensure that libc is installed in a directory on your library path. If libc is not available, you might see the following error when you run CLI commands:

oc: No such file or directory

Basic Setup and Login

The oc login command is the best way to initially set up the CLI, and it serves as the entry point for most users. The interactive flow helps you establish a session to an Azure Red Hat OpenShift server with the provided credentials. The information is automatically saved in a CLI configuration file that is then used for subsequent commands.

The following example shows the interactive setup and login using the oc login command:

Example 1. Initial CLI Setup
$ oc login
Example Output
OpenShift server [https://localhost:8443]: https://openshift.example.com (1)

Username: alice (2)
Authentication required for https://openshift.example.com (openshift)
Password: ******
Login successful. (3)

You don't have any projects. You can try to create a new project, by running

    $ oc new-project <projectname> (4)

Welcome to OpenShift! See 'oc help' to get started.
1 The command prompts for the Azure Red Hat OpenShift server URL.
2 The command prompts for login credentials: a user name and password.
3 A session is established with the server, and a session token is received.
4 If you do not have a project, information is given on how to create one.

When you have completed the CLI configuration, subsequent commands use the configuration file for the server, session token, and project information.

You can log out of CLI using the oc logout command:

$ oc logout
Example Output
User, alice, logged out of https://openshift.example.com

If you log in after creating or being granted access to a project, a project you have access to is automatically set as the current default, until switching to another one:

$ oc login
Example Output
Username: alice
Authentication required for https://openshift.example.com (openshift)
Password:
Login successful.

Using project "aliceproject".

Additional options are also available for the oc login command.

If you have access to administrator credentials but are no longer logged in as the default system user system:admin, you can log back in as this user at any time as long as the credentials are still present in your CLI configuration file. The following command logs in and switches to the default project:

$ oc login -u system:admin -n default

CLI Configuration Files

A CLI configuration file permanently stores oc options and contains a series of authentication mechanisms and Azure Red Hat OpenShift server connection information associated with nicknames.

As described in the previous section, the oc login command automatically creates and manages CLI configuration files. All information gathered by the command is stored in a configuration file located in ~/.kube/config. The current CLI configuration can be viewed using the following command:

Example 2. Viewing the CLI Configuration
$ oc config view
Example Output
apiVersion: v1
clusters:
- cluster:
    server: https://openshift.example.com
  name: openshift
contexts:
- context:
    cluster: openshift
    namespace: aliceproject
    user: alice
  name: alice
current-context: alice
kind: Config
preferences: {}
users:
- name: alice
  user:
    token: NDM2N2MwODgtNjI1Yy10N3VhLTg1YmItYzI4NDEzZDUyYzVi

CLI configuration files can be used to setup multiple CLI profiles using various Azure Red Hat OpenShift servers, namespaces, and users so that you can switch easily between them. The CLI can support multiple configuration files; they are loaded at runtime and merged together along with any override options specified from the command line.

Projects

$ oc project

If you have access to multiple projects, use the following syntax to switch to a particular project by specifying the project name:

$ oc project <project_name>

For example:

Switch to Project project02
$ oc project project02
Example Output
Now using project 'project02'.
Switch to Project project03
$ oc project project03
Example Output
Now using project 'project03'.
List the Current Project
$ oc project
Example Output
Using project 'project03'.