Introducing Kubectl with Oracle Cloud Native Environment

Introduction

Although graphical tools can manage Kubernetes, many administrators prefer to use command-line tools. The command line tool provided within the Kubernetes ecosystem is called kubectl . Kubectl is a versatile tool used to deploy and inspect the configurations and logs of the cluster resources and applications. Kubectl achieves this by using the Kubernetes API to authenticate with the Control Node of the Kubernetes cluster to complete any management actions requested by the administrator.

Most of the operations/commands available for kubectl provide administrators with the ability to deploy and manage applications deployed onto the Kubernetes cluster and inspect and manage the Kubernetes cluster resources. Because this tutorial is an introduction to kubectl, it will only focus on using kubectl to discover what Kubernetes resources are available in a new install of Oracle Cloud Native Environment.

Note: Many kubectl commands have the --all-namespaces option appended. For this reason, a shorthand for this option is the -A flag. This tutorial often uses kubectl -A instead of kubectl --all-namespaces.

Objectives

This tutorial introduces kubectl, a widely used command-line tool for interacting with a Kubernetes cluster. Beginning with why it is helpful to learn about it, the tutorial will also introduce some basic kubectl commands that help to understand any services deployed on a Kubernetes cluster, for example:

location of the configuration file
kubectl config
kubectl get
kubectl describe
kubectl version

Most of these commands provide both getter (to review settings) and setter (to define/update settings) functions. This tutorial only uses kubectl to view the current configuration information.

Prerequisites

Installation of Oracle Cloud Native Environment

Deploy Oracle Cloud Native Environment

Note: If running in your own tenancy, read the linux-virt-labs GitHub project README.md and complete the prerequisites before deploying the lab environment.

Open a terminal on the Luna Desktop.

Clone the linux-virt-labs GitHub project.

git clone https://github.com/oracle-devrel/linux-virt-labs.git

Change into the working directory.
```
cd linux-virt-labs/ocne2
```

Install the required collections.

ansible-galaxy collection install -r requirements.yml

Deploy the lab environment.
```
ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e install_ocne_rpm=true -e create_ocne_cluster=true -e "ocne_cluster_node_options='-n 1 -w 1'"
```
The free lab environment requires the extra variable local_python_interpreter, which sets ansible_python_interpreter for plays running on localhost. This variable is needed because the environment installs the RPM package for the Oracle Cloud Infrastructure SDK for Python, located under the python3.6 modules.
The default deployment shape uses the AMD CPU and Oracle Linux 8. To use an Intel CPU or Oracle Linux 9, add -e instance_shape="VM.Standard3.Flex" or -e os_version="9" to the deployment command.
Important: Wait for the playbook to run successfully and reach the pause task. At this stage of the playbook, the installation of Oracle Cloud Native Environment is complete, and the instances are ready. Take note of the previous play, which prints the public and private IP addresses of the nodes it deploys and any other deployment information needed while running the lab.

Locate the Configuration File

Before looking at how to use kubectl to investigate a Kubernetes environment, it helps to know where to find an installer for your platform . However, this is optional for the tutorial because kubectl is already present.

Open a terminal and connect via SSH to the ocne instance.
```
ssh oracle@<ip_address_of_node>
```
The configuration file for kubectl is in the $HOME/.kube directory. While it is not usually updated, it helps to know where to locate the configuration file(s), especially if more than one Kubernetes environment needs managing.
```
cat ~/.kube/kubeconfig.ocne.local
```
Note that the .kube/config file contains three main sections:
- clusters: - the HTTPS endpoint for the Kubernetes cluster.
- user: - the user(s) allowed to connect/authenticate to the Kubernetes cluster.
- contexts: - combines the user and cluster information to enable kubectl to connect to the Kubernetes cluster.

View Context and Configuration Information

An easier way to view the information in the .kube/config file is to use the kubectl config command.

View the configuration using kubectl.
```
kubectl config view
```
Example Output:
```
apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: DATA+OMITTED
    server: https://127.0.0.1:6443
  name: kubernetes
contexts:
- context:
    cluster: kubernetes
    user: kubernetes-admin
  name: kubernetes-admin@kubernetes
current-context: kubernetes-admin@kubernetes
kind: Config
preferences: {}
users:
- name: kubernetes-admin
  user:
    client-certificate-data: DATA+OMITTED
    client-key-data: DATA+OMITTED
```
This output presents the same information shown in the previous step. However, it does not present these fields in full:
- certificate-authority-data
- client-certificate-data
- client-key-data
Instead, the certificate information itself is obfuscated and replaced with these placeholders:
- DATA+OMITTED
- REDACTED
Why the difference between DATA+OMITTED and REDACTED? This difference is because the client-certificate-data and client-key-data information is sensitive and, therefore, needs to be kept confidential (REDACTED). However, it is not a secret because the certificate-authority-data is a public certificate. So, to differentiate between them this data is listed as DATA+OMITTED instead (see this GitHub Issue for more information).
NOTE: The non-redacted information can be displayed using kubectl and appending either of these flags:
- --raw - Displays all raw byte and sensitive data
- --flatten - Flattens the resulting kubeconfig file into self-contained output that you can use for creating portable kubeconfig files
Review the details of all defined contexts in the active configuration file.
```
kubectl config get-contexts
```
Example Output:
```
CURRENT   NAME                          CLUSTER      AUTHINFO           NAMESPACE
*         kubernetes-admin@kubernetes   kubernetes   kubernetes-admin 
```
Note: If the configuration contains more than one context in the configuration file, the current default context is indicated with an asterisk (*). The tutorial environment has only one context defined.
Display the default context currently in use.
```
kubectl config current-context
```
Example Output:
```
kubernetes-admin@kubernetes
```

Install Auto-Completion

Kubectl provides support for auto-completion, which in turn helps to reduce the amount of typing required at the command line. However, this functionality requires bash-completion to be present.

Install the Bash completion package.
```
sudo dnf install -y bash-completion
```
Depending on your environment, the installation of this package may already exist.
Enable auto-complete for kubectl in the Bash shell.
```
source <(kubectl completion bash)
```

Add auto-complete permanently to your Bash shell.

echo "source <(kubectl completion bash)" >> ~/.bashrc

By default, auto-completion will become available after reloading your shell. However, it is possible to enable auto-completion in the current shell session by sourcing the ~/.bashrc file.
```
source ~/.bashrc
```

Confirm bash-completion for kubectl is enabled.

Type the kubectl command <SPACE> and press the Tab key twice. The available sub-commands should be listed.

Example Output:

alpha          cluster-info   diff           label          run
annotate       completion     drain          logs           scale
api-resources  config         edit           options        set
api-versions   cordon         exec           patch          taint
apply          cp             explain        plugin         top
attach         create         expose         port-forward   uncordon
auth           debug          get            proxy          version
autoscale      delete         help           replace        wait
certificate    describe       kustomize      rollout

Lookup the Kubernetes Version

Before working with an Oracle Cloud Native Environment installation, the administrator can use these steps to gather some basic information about the topology and Kubernetes version used.

Display the short version of the Kubernetes version information.

kubectl version

Example Output:

Client Version: v1.30.3+1.el8
Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
Server Version: v1.30.3+1.el8

Return more detailed information about the deployed Kubernetes version in YAML format.

kubectl version --output=yaml

Example Output:

clientVersion:
  buildDate: "2024-07-23T22:25:54Z"
  compiler: gc
  gitCommit: e72e0005eb3c1d098793b855d0856410f293b200
  gitTreeState: clean
  gitVersion: v1.30.3+1.el8
  goVersion: go1.22.5
  major: "1"
  minor: "30"
  platform: linux/amd64
kustomizeVersion: v5.0.4-0.20230601165947-6ce0bf390ce3
serverVersion:
  buildDate: "2024-07-23T22:37:09Z"
  compiler: gc
  gitCommit: e72e0005eb3c1d098793b855d0856410f293b200
  gitTreeState: clean
  gitVersion: v1.30.3+1.el8
  goVersion: go1.22.5
  major: "1"
  minor: "30"
  platform: linux/amd64

Return the detailed information in JSON format.
```
kubectl version --output=json
```

Confirm the Node Information

Nodes are the workhorse of a Kubernetes cluster, so the number of control and worker nodes deployed on a cluster is vital for the administrator to be aware of.

Concisely confirm the node information.

This command displays an abridged listing showing the node names (NAME), node roles (ROLES), and the Kubernetes version (VERSION)

kubectl get nodes

Example Output:

NAME                   STATUS   ROLES           AGE   VERSION
ocne-control-plane-1   Ready    control-plane   54m   v1.30.3+1.el8
ocne-worker-1          Ready    <none>          53m   v1.30.3+1.el8

Return more detailed information about the nodes.
```
kubectl get nodes -o wide
```
This command shows more detailed information than the previous command by including this additional information:
- Internal and External IP information (INTERNAL-IP and EXTERNAL-IP)
- Operating System information on the node (OS_IMAGE)
- Kernel version on the node (KERNEL-VERSION)
- Container runtime information and version (CONTAINER-RUNTIME)

Confirm the API Versions in the Cluster

The API server is a critical component of the Kubernetes cluster control plane. It exposes an HTTP API that allows different cluster components and external resources (such as kubectl) to communicate and orchestrate applications deployed onto the Kubernetes cluster.

Because the API versions change with each Kubernetes version, confirming which API versions are available may also be helpful. For example, to understand why a deployment is failing.

Note: The Kubernetes cluster output may differ.

kubectl api-versions

Example Output:

admissionregistration.k8s.io/v1
apiextensions.k8s.io/v1
apiregistration.k8s.io/v1
apps/v1
authentication.k8s.io/v1
authorization.k8s.io/v1
autoscaling/v1
autoscaling/v2
batch/v1
certificates.k8s.io/v1
coordination.k8s.io/v1
discovery.k8s.io/v1
events.k8s.io/v1
flowcontrol.apiserver.k8s.io/v1beta2
flowcontrol.apiserver.k8s.io/v1beta3
networking.k8s.io/v1
node.k8s.io/v1
platform.verrazzano.io/v1alpha1
policy/v1
rbac.authorization.k8s.io/v1
scheduling.k8s.io/v1
storage.k8s.io/v1
v1

It is possible to look for more detailed information about the API resources available on the Kubernetes cluster where the columns describe the following:

NAME - the resource name
SHORTNAMES - where listed, this represents an alternative short name to use with the kubectl command
APIVERSION - self-explanatory
NAMESPACED - while most Kubernetes resources are deployed into one of the namespaces(shown as true), not all are (shown as false).
KIND - confirms the 'kind' of resource type the API is related to, for example, a Deployment kind (found in a deployment.yaml file).

kubectl api-resources

Example Output:

Note: output has been abbreviated for clarity.

NAME                              SHORTNAMES       APIVERSION                             NAMESPACED   KIND
bindings                                           v1                                     true         Binding
componentstatuses                 cs               v1                                     false        ComponentStatus
configmaps                        cm               v1                                     true         ConfigMap
endpoints                         ep               v1                                     true         Endpoints
events                            ev               v1                                     true         Event
limitranges                       limits           v1                                     true         LimitRange
namespaces                        ns               v1                                     false        Namespace
nodes                             no               v1                                     false        Node
persistentvolumeclaims            pvc              v1                                     true         PersistentVolumeClaim
persistentvolumes                 pv               v1                                     false        PersistentVolume
pods                              po               v1                                     true         Pod
...
...
clusterroles                                       rbac.authorization.k8s.io/v1           false        ClusterRole
rolebindings                                       rbac.authorization.k8s.io/v1           true         RoleBinding
roles                                              rbac.authorization.k8s.io/v1           true         Role
priorityclasses                   pc               scheduling.k8s.io/v1                   false        PriorityClass
csidrivers                                         storage.k8s.io/v1                      false        CSIDriver
csinodes                                           storage.k8s.io/v1                      false        CSINode
csistoragecapacities                               storage.k8s.io/v1                      true         CSIStorageCapacity
storageclasses                    sc               storage.k8s.io/v1                      false        StorageClass
volumeattachments                                  storage.k8s.io/v1                      false        VolumeAttachment

NOTE: It is possible to display a shortened version of the same information by appending the --namespaced=true or --namespaced=false flag to the kubectl api-resources command.

Lookup Namespaces and Security Information

Namespaces provide the mechanism for applications deployed onto a cluster to isolate resources from each other when deployed in a cluster.

List all of the namespaces present.

kubectl get namespaces -A

Example Output:

NAME              STATUS   AGE
default           Active   55m
kube-flannel      Active   56m
kube-node-lease   Active   55m
kube-public       Active   56m
kube-system       Active   57m
ocne-system       Active   56m

List the certificates deployed onto the Kubernetes cluster.
Creating a 'CertificateSigningRequest' (CSR) is part of the signing process for an X.509 certificate. While not part of an administrator's daily work routine, it is helpful for the administrator to monitor the existing CSRs on a cluster so any redundant CSRs can be removed or updated.
```
kubectl get csr
```
Example Output:
```
NAME        AGE   SIGNERNAME                                    REQUESTOR                          REQUESTEDDURATION   CONDITION
csr-shsvw   56m   kubernetes.io/kube-apiserver-client-kubelet   system:bootstrap:e95tho            <none>              Approved,Issued
csr-xp9pm   57m   kubernetes.io/kube-apiserver-client-kubelet   system:node:ocne-control-plane-1   <none>              Approved,Issued
```
Note: A garbage collection process executes periodically on the cluster to remove old CertificateSigningRequest resources. Therefore, if a kubectl get csr has previously returned output but later returns a No Resources Found message, this indicates the garbage collector has executed (Please see Certificate and Certificate Signing Requests documentation for details.)

Lookup Secrets deployed on the Kubernetes cluster.

Kubernetes uses Secrets to hold confidential data, such as passwords, keys, or tokens. It helps by keeping them separate from the container image, thereby ensuring no confidential data remains with the application code contained within the container.

kubectl get secrets -A

Example Output:

NAMESPACE      NAME                                 TYPE                            DATA   AGE
kube-flannel   sh.helm.release.v1.flannel.v1        helm.sh/release.v1              1      57m
kube-system    bootstrap-token-8u5mxn               bootstrap.kubernetes.io/token   6      57m
kube-system    bootstrap-token-e95tho               bootstrap.kubernetes.io/token   6      57m
kube-system    bootstrap-token-trau6v               bootstrap.kubernetes.io/token   4      57m
kube-system    kubeadm-certs                        Opaque                          8      57m
ocne-system    certificate-authority-tls            kubernetes.io/tls               2      57m
ocne-system    oidc                                 Opaque                          0      57m
ocne-system    sh.helm.release.v1.ocne-catalog.v1   helm.sh/release.v1              1      57m
ocne-system    sh.helm.release.v1.ui.v1             helm.sh/release.v1              1      57m
ocne-system    ui-tls                               kubernetes.io/tls               2      57m

Lookup Services and Endpoint

Services within a Kubernetes cluster represent the endpoint(s) used to access applications deployed onto the cluster instead of connecting directly to a container. That allows you to terminate or replace an individual pod without interrupting the end user's interaction with the application.

Endpoints track and map the IP addresses of the objects created for a Service to ensure all traffic is routed correctly to the correct application and is managed automatically by Kubernetes. However, if debugging an issue, this is how to look up their details.

List all the Services deployed.

kubectl get services -A

Example Output:

NAMESPACE     NAME           TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                  AGE
default       kubernetes     ClusterIP   10.96.0.1        <none>        443/TCP                  58m
kube-system   kube-dns       ClusterIP   10.96.0.10       <none>        53/UDP,53/TCP,9153/TCP   59m
ocne-system   ocne-catalog   NodePort    10.111.157.210   <none>        80:32554/TCP             58m
ocne-system   ui             ClusterIP   10.101.248.47    <none>        443/TCP                  58m

List any Endpoints on the Kubernetes cluster.

kubectl get endpoints -A

Example Output:

NAMESPACE     NAME           ENDPOINTS                                               AGE
default       kubernetes     192.168.122.218:6444                                    59m
kube-system   kube-dns       10.244.0.2:53,10.244.1.4:53,10.244.0.2:53 + 3 more...   59m
ocne-system   ocne-catalog   10.244.1.3:80                                           59m
ocne-system   ui             10.244.1.2:4466                                         59m

List all the Pods deployed on the Kubernetes cluster.

kubectl get pods -A

Example Output:

NAMESPACE      NAME                                           READY   STATUS    RESTARTS      AGE
kube-flannel   kube-flannel-ds-5mp9m                          1/1     Running   3 (60m ago)   60m
kube-flannel   kube-flannel-ds-9rjpm                          1/1     Running   3 (60m ago)   60m
kube-system    coredns-f7d444b54-g6fgj                        1/1     Running   0             60m
kube-system    coredns-f7d444b54-kptzr                        1/1     Running   0             60m
kube-system    etcd-ocne-control-plane-1                      1/1     Running   0             60m
kube-system    kube-apiserver-ocne-control-plane-1            1/1     Running   0             60m
kube-system    kube-controller-manager-ocne-control-plane-1   1/1     Running   0             60m
kube-system    kube-proxy-bpxhc                               1/1     Running   0             60m
kube-system    kube-proxy-m6vp5                               1/1     Running   0             60m
kube-system    kube-scheduler-ocne-control-plane-1            1/1     Running   0             60m
ocne-system    ocne-catalog-578c959566-mh448                  1/1     Running   0             60m
ocne-system    ui-84dd57ff69-46phf                            1/1     Running   0             60m

Lookup Pod Information

Retrieve information about any pod deployed on the cluster.
The previous kubectl get pods -A command returns a list of all the pods currently running on the cluster. Because this is a fresh install of Oracle Cloud Native Environment, only the 'system' pods are running. However, kubectl can retrieve more information about any of these deployed pods. All that needs noting are the NAMESPACE and NAME values. Because many pods are dynamically assigned names, these values may change from those shown when you execute the same command. However, the etcd pod should remain the same, so this is the example used for the lab.
```
kubectl describe pods etcd-ocne-control -n kube-system
```
Note: the -n kube-system directs kubectl to look inside the kube-system namespace for the etcd-ocne-control pod.
For now, this serves only as an illustration to show how easy it is to use kubectl at the command line to return a large amount of detailed information about deployments. This ability will eventually become one of several tools you will use as an administrator to manage and troubleshoot the Kubernetes cluster for which you're responsible.

Next Steps

These steps conclude the brief introduction to the kubectl command-line tool, demonstrating its use to query a Kubernetes cluster and discovering a wealth of information about the services currently deployed to the Kubernetes cluster. However, kubectl can do more than retrieve information; it also manages application deployments and operations on the Kubernetes cluster.