Use Kubepug with Oracle Cloud Native Environment

Introduction

Kubepug is an open-source project and program that helps administrators of a Kubernetes cluster upgrade by finding deprecated APIs for resources that require either migration or removal from the cluster.

These different API types are usually deprecated in one version and then removed or deleted in a future version based on a selected lifecycle. Kubepug detects these deprecations or deletions by allowing you to set your Kubernetes version, which it will use to validate your cluster or manifest files.

Objectives

In this tutorial, you will learn:

How to install the Kubepug plugin using Krew
How to run Kubepug to determine deprecated clusters and manifests

Prerequisites

Installation of Oracle Cloud Native Environment
- a single control node and one worker node

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

Start a Kubernetes Cluster

We'll use a single control plane and worker node cluster based on Kubernetes v1.27 with plans to upgrade to 1.30.

Open a terminal and connect via SSH to the ocne instance.
```
ssh oracle@<ip_address_of_node>
```

Start the cluster.

ocne cluster start --version 1.27 -n 1 -w 1 -u false

Set the kubeconfig environment variable for your new cluster.
```
export KUBECONFIG=$(ocne cluster show -C ocne)
```
Where ocne is the default name for a cluster unless specified. You can then use kubectl get nodes to show the two nodes and verify that they are running version 1.27.

Install Krew

Krew is a package manager for kubectl plugins, which makes it easy to discover and install them on your system.

Install the git package.
```
sudo dnf install -y git
```

Download and install the plugin.

(
set -x; cd "$(mktemp -d)" &&
OS="$(uname | tr '[:upper:]' '[:lower:]')" &&
ARCH="$(uname -m | sed -e 's/x86_64/amd64/' -e 's/\(arm\)\(64\)\?.*/\1\2/' -e 's/aarch64$/arm64/')" &&
KREW="krew-${OS}_${ARCH}" &&
curl -fsSLO "https://github.com/kubernetes-sigs/krew/releases/latest/download/${KREW}.tar.gz" &&
tar zxvf "${KREW}.tar.gz" &&
./"${KREW}" install krew
)

Add the krew binary to your PATH environment variable.
```
export PATH="${KREW_ROOT:-$HOME/.krew}/bin:$PATH"
```
To make this change permanent, update your .bashrc file and restart your shell by logging out and back into the system.
Verify the installation.
```
kubectl krew
```

Install Kubepug Plugin

Search for the plugin.
```
kubectl krew search deprecations
```
You can install the Kubepug plugin as a binary or as a krew plugin called deprecations.
Install the plugin.
```
kubectl krew install deprecations
```
Verify the kubepug installation.
```
kubectl deprecations --help
```

Use the Kubepug Plugin

Before an upgrade, you need to validate the various objects and manifests within your Kubernetes cluster and ensure that you resolve any deprecated or deleted API references. In a production cluster, you could run kubepug directly against the cluster, but in our sample, you wouldn't get any output as everything is up to date. Therefore, we'll need a sample manifest that contains a deprecated API.

Create a sample Ingress manifest.

cat << EOF | tee ingress.yaml > /dev/null 
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: foo
  namespace: foobar
spec: {}
EOF

Check the manifest.

kubectl deprecations --k8s-version=v1.30 --input-file=ingress.yaml

Example Output:

Deleted APIs:
	 APIs REMOVED FROM THE CURRENT VERSION AND SHOULD BE MIGRATED IMMEDIATELY!!
Ingress found in extensions/v1beta1
	 ├─ Deleted at: 1.22
	 ├─ Replacement: networking.k8s.io/v1/Ingress 
	 ├─ Ingress is a collection of rules that allow inbound connections to reach theendpoints defined by a backend. An Ingress can be configured to give servicesexternally-reachable urls, load balance traffic, terminate SSL, offer namebased virtual hosting etc.DEPRECATED - This group version of Ingress is deprecated by networking.k8s.io/v1beta1 Ingress. See the release notes for more information.
		-> OBJECT: foo namespace: foobar location: ingress.yaml


Kubepug validates the APIs using Kubernetes markers. To know what are the deprecated and deleted APIS it checks, please go to https://kubepug.xyz/status/

The output shows the removal of the extensions/v1beta1/Ingress API in Kubernetes 1.22 and, therefore, needs to be replaced with networking.k8s.io/v1/Ingress before we upgrade to Kubernetes 1.30.

Update Kubernetes

After fixing the API and applying the changes to the cluster, we can update it. Kubernetes requires you to update one version at a time, so you'll need to repeat these steps for each version.

Stage the next Kubernetes version.
```
ocne cluster stage -v 1.28
```
Get a list of your cluster nodes.
```
kubectl get nodes
```
Check if there are updates available.
```
watch ocne cluster info
```
Monitor until you see nodes with available updates: 2 reported in the output. Enter Ctrl-c to exit the watch command.
Update the control plane node.
You must first update all control plane nodes within the cluster.
```
ocne node update -N ocne-control-plane-1
```
The update may take a few minutes to complete after the command finishes. You can use kubectl get nodes to check the version of the control plane node.
Update the worker node.
```
ocne node update -N ocne-worker-1 --delete-emptydir-data
```
Repeat the command if you get a warning that an upgrade is unavailable or cannot be performed. This small cluster may take a few minutes to stabilize before you can update the worker node.
The worker node requires the --delete-emptydir-data option because the ui Pod uses an emptyDir volume to share content across its running containers.
Verify the version of the cluster nodes.
```
kubectl get nodes
```
Repeat the command until the output shows that each node is updated to version 1.28.

Next Steps

Knowing that your APIs are current and the first update is complete, you can continue updating your nodes until you reach the latest version of Kubernetes.