Chapter 2. OpenShift CLI (oc)

• Working directly with project source code
• Scripting OpenShift Container Platform operations
• Managing projects while restricted by bandwidth resources and the web console is unavailable

Prerequisites

• You must have access to an OpenShift Container Platform cluster.
• You must have installed the CLI.

Procedure

• Log in to the CLI using the oc login command and enter the required information when prompted.

  $ oc login

  Copy to Clipboard Toggle word wrap

  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 

  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.

  Copy to Clipboard Toggle word wrap

  1

  Enter the OpenShift Container Platform server URL.

  2

  Enter whether to use insecure connections.

  3

  Enter the user name to log in as.

  4

  Enter the user’s password.

• Use oc help to get a list and description of all available CLI commands:

  Example: Get general help for the CLI

  $ oc help

  Copy to Clipboard Toggle word wrap

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

  Copy to Clipboard Toggle word wrap

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

  Example: Get help for the oc create command

  $ oc create --help

  Copy to Clipboard Toggle word wrap

  Example output

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

  Copy to Clipboard Toggle word wrap

• 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

  Copy to Clipboard Toggle word wrap

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

  Copy to Clipboard Toggle word wrap

• Use the oc logout command.

  $ oc logout

  Copy to Clipboard Toggle word wrap

  Example output

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

  Copy to Clipboard Toggle word wrap

Example usage

• Log in as a user that uses an access token. This token is used by the alice user:

• View the cluster entry automatically created:

• Update the current context to have users log in to the desired namespace:

• Examine the current context, to confirm that the changes are implemented:

• CLI config files are retrieved from your workstation, using the following hierarchy and merge rules:

  • If the --config option is set, then only that file is loaded. The flag is set once and no merging takes place.
  • If the $KUBECONFIG environment variable is set, then it is used. The variable can be a list of paths, and if so the paths are merged together. When a value is modified, it is modified in the file that defines the stanza. When a value is created, it is created in the first file that exists. If no files in the chain exist, then it creates the last file in the list.
  • Otherwise, the ~/.kube/config file is used and no merging takes place.

• The context to use is determined based on the first match in the following flow:

  • The value of the --context option.
  • The current-context value from the CLI config file.
  • An empty value is allowed at this stage.

• The user and cluster to use is determined. At this point, you may or may not have a context; they are built based on the first match in the following flow, which is run once for the user and once for the cluster:

  • The value of the --user for user name and --cluster option for cluster name.
  • If the --context option is present, then use the context’s value.
  • An empty value is allowed at this stage.

• The actual cluster information to use is determined. At this point, you may or may not have cluster information. Each piece of the cluster information is built based on the first match in the following flow:

  • The values of any of the following command line options:

    • --server,
    • --api-version
    • --certificate-authority
    • --insecure-skip-tls-verify
  • If cluster information and a value for the attribute is present, then use it.
  • If you do not have a server location, then there is an error.

• The actual user information to use is determined. Users are built using the same rules as clusters, except that you can only have one authentication technique per user; conflicting techniques cause the operation to fail. Command line options take precedence over config file values. Valid command line options are:

  • --auth-path
  • --client-certificate
  • --client-key
  • --token
• For any information that is still missing, default values are used and prompts are given for additional information.

Prerequisites

• You must have the oc CLI tool installed.
• You must have a CLI plug-in file that begins with oc- or kubectl-.