Chapter 2.  Kubernetes and OpenShift Command-line Interfaces and APIs

The oc CLI installation also includes an installation of the kubectl CLI, which is the recommended method for installing the kubectl CLI for OpenShift users.

You can also install the kubectl CLI independently of the oc CLI. You must use a kubectl CLI version that is within one minor version difference of your cluster. For example, a v1.26 client can communicate with v1.25, v1.26, and v1.27 control planes. Using the latest compatible version of the kubectl CLI can help to avoid unforeseen issues.

To perform a manual installation of the kubectl binary for a Linux installation, you must first download the latest release by using the curl command.

[user@host ~]$ curl -LO "https://dl.k8s.io/release/$(curl -L \
  -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

Then, you must download the kubectl checksum file and then validate the kubectl binary against the checksum file.

[user@host ~]$ curl -LO "https://dl.k8s.io/$(curl -L \
-s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl.sha256"

[user@host ~]$ echo "$(cat kubectl.sha256)  kubectl" | sha256sum --check
kubectl: OK

If the check fails, then the sha256sum command exits with nonzero status, and prints a kubectl: FAILED message.

You can then install the kubectl CLI.

[user@host ~]$ sudo install -o root -g root -m 0755 kubectl \
  /usr/local/bin/kubectl

Finally, use the kubectl version command to verify the installed version. This command prints the client and server versions. Use the --client option to view the client version only.

[user@host ~]$ kubectl version --client

Alternatively, a distribution that is based on Red Hat Enterprise Linux (RHEL) can install the kubectl CLI with the following command:

[user@host ~]$ cat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://packages.cloud.google.com/yum/repos/kubernetes-el7-\$basearch
enabled=1
gpgcheck=1
gpgkey=https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
EOF
[user@host ~]$ sudo yum install -y kubectl

To view a list of the available kubectl commands, use the kubectl --help command.

[user@host ~]$ kubectl --help
kubectl controls the Kubernetes cluster manager.

 Find more information at:
https://kubernetes.io/docs/reference/kubectl/

Basic Commands (Beginner):
  create        Create a resource from a file or from stdin
  expose        Take a replication controller, service, deployment or pod and
expose it as a new Kubernetes Service
  run           Run a particular image on the cluster
  set           Set specific features on objects

Basic Commands (Intermediate):
...output omitted...

You can also use the --help option on any command to view detailed information about the command, including its purpose, examples, available subcommands, and options. For example, the following command provides information about the kubectl create command and its usage.

[user@host ~]$ kubectl create --help
Create a resource from a file or from stdin.

 JSON and YAML formats are accepted.

Examples:
  # Create a pod using the data in pod.json
  kubectl create -f ./pod.json

  # Create a pod based on the JSON passed into stdin
  cat pod.json | kubectl create -f -

  # Edit the data in registry.yaml in JSON then create the resource using the edited data
  kubectl create -f registry.yaml --edit -o json

Available Commands:
  clusterrole              Create a cluster role
  clusterrolebinfing   	   Create a cluster role binding for a particular cluster role
...output omitted...

Kubernetes uses many resource components to support applications. The kubectl explain command provides detailed information about the attributes of a given resource. For example, use the following command to learn more about the attributes of a pod resource.

[user@host ~]$ kubectl explain pod
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.
...output omitted...

Refer to Kubernetes Documentation - Getting Started for further information about the kubectl commands.

The main method of interacting with an RHOCP cluster is by using the oc command.

You can download the oc CLI from the OpenShift web console to ensure that the CLI tools are compatible with the RHOCP cluster. From the OpenShift web console, navigate to Help → Command line tools. The Help menu is represented by a ? icon. The web console provides several installation options for the oc client, such as downloads for the following operating systems:

The basic usage of the oc command is through its subcommands in the following syntax:

[user@host ~]$ oc command

Because the oc CLI is a superset of the kubectl CLI, the version, --help, and explain commands are the same for both CLIs. However, the oc CLI includes additional commands that are not included in the kubectl CLI, such as the oc login and oc new-project commands.

Developers who are familiar with Kubernetes can use the kubectl utility to manage a RHOCP cluster. This course uses the oc command-line utility, to take advantage of additional RHOCP features. The oc commands manage resources that are exclusive to RHOCP, such as projects, deployment configurations, routes, and image streams.

Before you can interact with your RHOCP cluster, you must authenticate your requests. Use the oc login command to authenticate your requests. The oc login command provides role-based authentication and authorization that protects the RHOCP cluster from unauthorized access. The syntax to log in is shown below:

[user@host ~]$ oc login cluster-url

For example, in this course, you can use the following command:

[user@host ~]$ oc login https://api.ocp4.example.com:6443
Username: developer
Password: developer
Login successful.

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

  $ oc new-project <projectname>

Welcome to OpenShift! See 'oc help' to get started.

After authenticating to the RHOCP cluster, you can create a project with the oc new-project command. Projects provide isolation between your application resources. Projects are Kubernetes namespaces with additional annotations that provide multitenancy scoping for applications.

[user@host ~]$ oc new-project myapp

Several essential commands can manage RHOCP and Kubernetes resources, as described here. Unless otherwise specified, the following commands are compatible with both the oc and kubectl CLIs.

Some commands require a user with cluster administrator access. The following list includes several useful oc commands for cluster administrators.

Other useful commands are available to both regular and administrator users:

Add the --recursive flag to display all fields of a resource without descriptions. Information about each field is retrieved from the server in OpenAPI format.

Each of these commands is executed in the current selected project. To execute commands in a different project, you must include the --namespace or -n options.

[user@host ~]$ oc get pods -n openshift-apiserver
NAME                         READY   STATUS    RESTARTS   AGE
apiserver-68c9485699-ndqlc   2/2     Running   2          18d

Refer to the references for a complete list of oc commands.

For users to interact with RHOCP, they must first authenticate to the cluster. The authentication layer identifies the user that is associated with requests to the RHOCP API. After authentication, the authorization layer then uses information about the requesting user to determine whether the request is allowed.

A user in OpenShift is an entity that can make requests to the RHOCP API. An RHOCP User object represents an actor that can be granted permissions in the system by adding roles to the user or to the user's groups. Typically, this represents the account of a developer or an administrator.

Several types of users can exist.

Each user must authenticate to access a cluster. After authentication, policy determines what the user is authorized to do.

The RHOCP control plane includes a built-in OAuth server. To authenticate themselves to the API, users obtain OAuth access tokens. Token authentication is the only guaranteed method to work with any OpenShift cluster, because enterprise Single Sign-On (SSO) might replace the login form of the web console.

When a person requests a new OAuth token, the OAuth server uses the configured identity provider to determine the identity of the person who makes the request. The OAuth server then determines the user that the identity maps to; creates an access token for that user; and then returns the token for use.

To retrieve an OAuth token by using the OpenShift web console, navigate to Help → Command line tools. The Help menu is represented by a ? icon.

On the Command Line Tools page, navigate to Copy login Command. The following page requires you to log in with your OpenShift user credentials. Next, navigate to Display token. Use the command under the Log in with this token label to log in to the OpenShift API.

Copy the command from the web console and paste it on the command line. The copied command uses the --token and --server options, similar to the following example.

[user@host ~]$ oc login --token=sha256-BW...rA8 \
  --server=https://api.ocp4.example.com:6443