Stella Achar Oiro

Posted on Jan 8

Building a Custom CLI Tool for Kubernetes: A Beginner's Guide

What is Kubernetes?

Before building our tool, let's understand what Kubernetes is through some everyday examples.

The Restaurant Kitchen Analogy

Imagine you're running a restaurant kitchen. You have:

Multiple chefs (containers) preparing different dishes
Kitchen stations (nodes) where cooking happens
A kitchen manager (Kubernetes) coordinating everything
Recipe cards (configuration files) that describe how to make each dish
Orders coming in (user requests) that need to be fulfilled
Ingredients (resources) that need to be distributed

The Shopping Mall Analogy

Another way to think about Kubernetes is like managing a shopping mall:

Stores (containers) provide different services
The building (node) houses these stores
Mall management (Kubernetes) handles:
- Opening new stores when needed (scaling up)
- Closing stores when quiet (scaling down)
- Moving stores to different locations (pod scheduling)
- Making sure the mall stays operational (self-healing)

The Orchestra Analogy

You can also think of Kubernetes as an orchestra conductor:

Musicians (containers) play different instruments
Sections (pods) group related instruments together
The conductor (Kubernetes) ensures:
- Everyone plays in sync
- The right number of musicians are present
- Replacing musicians when needed
- The overall performance stays harmonious

Why Build a Custom CLI Tool?

A CLI (Command Line Interface) tool is like a specialized remote control. While Kubernetes comes with its own remote control (kubectl), sometimes you need a simpler one that does specific tasks for your team. Think of it like creating a child-friendly remote with just the essential buttons instead of using the complex one that came with your TV.

Prerequisites

Go 1.19 or later installed
A text editor (like Visual Studio Code)
Basic knowledge of programming
Access to a computer with admin rights

Don't worry if you don't have Kubernetes installed yet - we'll cover that later.

Understanding the Building Blocks

Visual Overview: How Everything Connects

Think of the system like building with LEGO blocks:

At the bottom, we have our computer (like the LEGO baseplate)
On top of that, we have Kubernetes (like a specialized LEGO set)
Inside Kubernetes, we have:
- Containers (individual LEGO pieces)
- Pods (small assembled units)
- Services (larger assembled structures)
The CLI tool (what you're building) is like a special LEGO tool that helps us:
- Add new pieces (deploy containers)
- Move pieces around (manage pods)
- Check if everything is connected properly (monitoring)

What is Go?

Go (or Golang) is the programming language we'll use. It's like a set of building blocks created by Google that makes it easy to build tools like ours. Go is particularly good at building systems that need to talk to other systems, which is exactly what we need for our Kubernetes tool.

Basic Kubernetes Concepts

Let's understand some key terms:

Pod: Think of a pod as a lunch box. It contains one or more containers (like different compartments in your lunch box).
Node: A node is like a worker in our restaurant kitchen - it's a computer that runs your containers.
Cluster: The entire restaurant kitchen - it's a group of nodes working together.

Building Your CLI Tool Step by Step

Step 1: Set Up Your Workspace

First, create a space for your project:

# Create a new folder for our project
mkdir my-kube-tool
cd my-kube-tool

# Initialize the Go project
go mod init my-kube-tool

Step 2: Create a Simple Tool

Let's start with something simple - a tool that just tells us what pods (lunch boxes) we have:

package main

import (
    "fmt"
    "os"
)

func main() {
    fmt.Println("Welcome to My Kubernetes Tool!")
    fmt.Println("This tool will help you manage your Kubernetes cluster.")
}

Step 3: Add Basic Commands

Now, add some basic commands to your tool. We'll use a library called Cobra that makes it easy to create CLI commands:

package main

import (
    "fmt"
    "github.com/spf13/cobra"
)

func main() {
    var rootCmd = &cobra.Command{
        Use:   "my-kube-tool",
        Short: "A friendly Kubernetes helper",
        Long:  `A tool that helps you work with Kubernetes in a simpler way`,
    }

    // Add a command to list pods
    var listCmd = &cobra.Command{
        Use:   "list",
        Short: "List all your running applications",
        Run: func(cmd *cobra.Command, args []string) {
            fmt.Println("Looking for your applications...")
            // We'll add the actual listing code later
        },
    }

    rootCmd.AddCommand(listCmd)
    rootCmd.Execute()
}

Step 4: Connect to Kubernetes

Now we'll add the code to actually talk to Kubernetes. Think of this like teaching our tool how to communicate with the kitchen manager:

package main

import (
    "fmt"
    "k8s.io/client-go/kubernetes"
    "k8s.io/client-go/tools/clientcmd"
)

func connectToCluster() (*kubernetes.Clientset, error) {
    // Get the path to your Kubernetes configuration
    kubeconfig := os.Getenv("HOME") + "/.kube/config"

    // Load the configuration
    config, err := clientcmd.BuildConfigFromFlags("", kubeconfig)
    if err != nil {
        return nil, fmt.Errorf("couldn't read Kubernetes configuration: %v", err)
    }

    // Create a connection
    clientset, err := kubernetes.NewForConfig(config)
    if err != nil {
        return nil, fmt.Errorf("couldn't connect to Kubernetes: %v", err)
    }

    return clientset, nil
}

Common Tasks Your Tool Can Do

View Your Applications

Let's add a command to see what applications are running:

func listPods(namespace string) {
    // Connect to Kubernetes
    client, err := connectToCluster()
    if err != nil {
        fmt.Printf("Oops! Couldn't connect: %v\n", err)
        return
    }

    // Get the list of pods
    pods, err := client.CoreV1().Pods(namespace).List(context.Background(), metav1.ListOptions{})
    if err != nil {
        fmt.Printf("Couldn't get the list of applications: %v\n", err)
        return
    }

    // Print each pod in a friendly way
    fmt.Println("Here are your running applications:")
    for _, pod := range pods.Items {
        fmt.Printf("- %s (Status: %s)\n", pod.Name, pod.Status.Phase)
    }
}

Understand the Output

When you run your tool, you'll see something like this:

$ ./my-kube-tool list
Here are your running applications:
- web-app (Status: Running)
- database (Status: Running)
- cache (Status: Running)

Each line shows:

The name of your application
Whether it's running properly

Troubleshooting Guide

Understand Error Messages

Like learning a new language, error messages have patterns. Here are some common ones translated to plain English:

Connection Errors

Error: Unable to connect to the server

Think of this like trying to call someone but having no signal. Check if:

Your phone (computer) is connected to the network
The person (Kubernetes cluster) is available
You have the right phone number (configuration)

Permission Errors

Error: Forbidden

This is like trying to enter a VIP area without a pass. Make sure:

You have the right credentials
Your pass (certificate) hasn't expired
You're allowed to access that area (namespace)

Resource Errors

Error: Resource not found

Similar to trying to find a store that has moved or closed. Check if:

You're in the right mall (cluster)
The store (resource) still exists
You're using the right name

Common Problems and Solutions

"Can't connect to Kubernetes"
- Make sure Kubernetes is running on your computer
- Check if you have a file at ~/.kube/config
- Try running kubectl get pods to see if basic Kubernetes commands work
"Permission denied"
- You might need administrator rights
- Try running the command with sudo (on Mac/Linux)
- Check if you're logged in to your cluster
"Command not found"
- Make sure you're in the right folder
- Check if you built the tool correctly
- Try building the tool again with go build

Next Steps

Once you're comfortable with the basic tool, you can:

Add more commands to see different types of information
Create shortcuts for common tasks
Add colorful output to make information easier to read
Add help text to explain what each command does

Helpful Resources

Go Programming Language Tutorial
Kubernetes Basics
Video tutorials (recommended for visual learners)
Online playgrounds where you can practice Focus on understanding one piece at a time and gradually build up your knowledge. Each concept becomes clearer with practice.

Visual Mental Models

Think of Kubernetes Like a City

Cluster = The entire city
Nodes = City districts
Pods = Buildings
Containers = Apartments
Services = Public transportation routes
ConfigMaps = City planning documents
Secrets = Security protocols

Think of Your CLI Tool Like a Swiss Army Knife

list command = Binoculars to view the city
create command = Construction permit office
delete command = Demolition crew
update command = Renovation team
describe command = Building inspector

Think of Resources Like City Infrastructure

CPU = Electricity supply
Memory = Water supply
Storage = Parking spaces
Network = Roads and highways

Glossary

CLI: Command Line Interface - a way to talk to your computer by typing commands
Container: A package that contains an application and everything it needs to run
Pod: A group of containers in Kubernetes
Namespace: A way to organize your applications in Kubernetes, like folders on your computer
API: The language that computers use to talk to each other

DEV Community