Skip to main content

Chapter 1.6 - Installation and Configuration

Overview​

Before you can start using Kubernetes, you need to install the necessary tools. This chapter guides you through the installation of kubectl (the Kubernetes command-line tool) and the configuration of a local cluster for practice.

Objectives​

By the end of this chapter, you will be able to:

  • Install kubectl on your system
  • Understand kubectl configuration
  • Start a local Kubernetes cluster
  • Verify that everything is working correctly
  • Use basic kubectl commands

What is kubectl?​

kubectl (pronounced "kube-control" or "kube-cuttle") is the official command-line tool for interacting with a Kubernetes cluster.

kubectl features:

  • Create, modify, delete resources
  • Inspect cluster state
  • Manage deployments
  • Debug applications
  • Access pod logs

Installing kubectl​

Verifying Installation​

Before installing, let's check if kubectl is already installed:

kubectl version --client

If you see a version, kubectl is already installed! Otherwise, follow the instructions below.

Installation on Windows​

If you have Chocolatey installed:

choco install kubernetes-cli

Method 2: Direct Download​

  1. Download the latest version from:

    https://dl.k8s.io/release/v1.28.0/bin/windows/amd64/kubectl.exe

    (Replace v1.28.0 with the desired version)

  2. Add kubectl.exe to your PATH:

    • Create a folder C:\kubectl
    • Place kubectl.exe in this folder
    • Add C:\kubectl to your PATH environment variable

  3. Verify the installation:

    kubectl version --client

Method 3: Via PowerShell​

# Download kubectl
$version = "v1.28.0"
$url = "https://dl.k8s.io/release/$version/bin/windows/amd64/kubectl.exe"
Invoke-WebRequest -Uri $url -OutFile "$env:TEMP\kubectl.exe"

# Move to a folder in PATH
Move-Item -Path "$env:TEMP\kubectl.exe" -Destination "C:\Windows\System32\kubectl.exe"

# Verify
kubectl version --client

Installation on Linux​

Method 1: Via Package Manager (Ubuntu/Debian)​

# Update packages
sudo apt-get update

# Install dependencies
sudo apt-get install -y apt-transport-https ca-certificates curl

# Add the Kubernetes GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

# Add the repository
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

# Install kubectl
sudo apt-get update
sudo apt-get install -y kubectl

# Verify
kubectl version --client

Method 2: Direct Download​

# Download the latest version
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

# Make executable
chmod +x kubectl

# Move to a folder in PATH
sudo mv kubectl /usr/local/bin/

# Verify
kubectl version --client

Installation on macOS​

brew install kubectl

Method 2: Direct Download​

# Download
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"

# Make executable
chmod +x kubectl

# Move to a folder in PATH
sudo mv kubectl /usr/local/bin/

# Verify
kubectl version --client

Configuring kubectl​

Configuration File​

kubectl uses a configuration file located at:

  • Linux/macOS: ~/.kube/config
  • Windows: %USERPROFILE%\.kube\config

This file contains:

  • Cluster connection information
  • Contexts (which cluster to use)
  • Users and authentication

Config File Structure​

apiVersion: v1
kind: Config
clusters:
  - name: my-cluster
    cluster:
      server: https://api.my-cluster.com
      certificate-authority-data: <cert-data>
contexts:
  - name: my-context
    context:
      cluster: my-cluster
      user: my-user
current-context: my-context
users:
  - name: my-user
    user:
      token: <token>

Useful Configuration Commands​

# View current configuration
kubectl config view

# View available contexts
kubectl config get-contexts

# Switch context
kubectl config use-context my-context

# View current context
kubectl config current-context

Local Cluster: minikube​

To practice Kubernetes locally, we will use minikube, which creates a single-node Kubernetes cluster in a virtual machine.

Installing minikube​

Windows​

# Via Chocolatey
choco install minikube

# Or direct download
# Download from: https://github.com/kubernetes/minikube/releases

Linux​

# Download
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64

# Install
sudo install minikube-linux-amd64 /usr/local/bin/minikube

macOS​

brew install minikube

Starting minikube​

# Start minikube
minikube start

# Check status
minikube status

# View cluster information
kubectl cluster-info

Useful minikube Commands​

# Stop the cluster
minikube stop

# Start the cluster
minikube start

# Delete the cluster
minikube delete

# Open the Kubernetes dashboard
minikube dashboard

# Access the minikube environment
minikube ssh

Local Cluster: kind (Alternative)​

kind (Kubernetes in Docker) is an alternative to minikube that uses Docker instead of a VM.

Installing kind​

Windows​

choco install kind

Linux/macOS​

# Download
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
# For macOS: kind-darwin-amd64

# Make executable
chmod +x ./kind

# Move to PATH
sudo mv ./kind /usr/local/bin/kind

Using kind​

# Create a cluster
kind create cluster --name my-cluster

# List clusters
kind get clusters

# Delete a cluster
kind delete cluster --name my-cluster

Verifying Installation​

Complete Test​

Run these commands to verify everything is working:

# 1. Check kubectl version
kubectl version --client

# 2. Check cluster connection
kubectl cluster-info

# 3. List nodes
kubectl get nodes

# 4. List all pods (should be empty at first)
kubectl get pods --all-namespaces

# 5. Check system components
kubectl get componentstatuses
# Note: This command is deprecated in recent versions

Expected Result​

If everything is working, you should see:

$ kubectl get nodes
NAME           STATUS   ROLES           AGE   VERSION
minikube       Ready    control-plane   1m    v1.28.0

Basic kubectl Commands​

Here are the essential commands you will use throughout the course:

General Commands​

# Get information
kubectl get <resource>              # List resources
kubectl describe <resource> <name>  # Resource details
kubectl explain <resource>          # Resource documentation

# Create resources
kubectl create <resource>          # Create from command line
kubectl apply -f <file.yaml>        # Create from a YAML file

# Modify resources
kubectl edit <resource> <name>      # Edit a resource
kubectl patch <resource> <name>    # Partially modify

# Delete resources
kubectl delete <resource> <name>    # Delete a resource
kubectl delete -f <file.yaml>        # Delete from a file

Practical Examples​

# List all pods
kubectl get pods

# List all pods in all namespaces
kubectl get pods --all-namespaces

# View pod details
kubectl describe pod my-pod

# View pod logs
kubectl logs my-pod

# Execute a command in a pod
kubectl exec -it my-pod -- /bin/bash

# Copy a file to/from a pod
kubectl cp my-pod:/path/file ./local-file

Autocompletion (Bonus)​

Setting Up Autocompletion​

Autocompletion makes kubectl much easier to use:

Bash (Linux/macOS)​

# Add to ~/.bashrc
echo 'source <(kubectl completion bash)' >> ~/.bashrc
source ~/.bashrc

Zsh (macOS)​

# Add to ~/.zshrc
echo 'source <(kubectl completion zsh)' >> ~/.zshrc
source ~/.zshrc

PowerShell (Windows)​

# Install the module
Install-Module -Name PSKubectlCompletion

# Import in profile
Add-Content $PROFILE "Import-Module PSKubectlCompletion"

Summary​

In this chapter, you learned:

How to install kubectl on different systems
How to configure kubectl to connect to a cluster
How to start a local cluster with minikube or kind
How to verify that everything is working correctly
Essential basic kubectl commands

Next Steps​

Now that you have kubectl installed and a working local cluster, you are ready for:

Lab 1.1: First deployment on Kubernetes
Module 2: Detailed architecture and Kubernetes components

Resources​

Troubleshooting​

Common Problems and Solutions​

Problem 1: kubectl: command not found​

Symptom:

kubectl: command not found

Solutions:

  1. Verify installation:

    # Windows
    where kubectl

    # Linux/macOS
    which kubectl

  2. Check PATH:

    • Make sure the folder containing kubectl is in your PATH
    • Windows: Check system environment variables
    • Linux/macOS: Check echo $PATH

  3. Reinstall:

    • Follow the installation instructions again for your OS

Problem 2: Unable to connect to the server​

Symptom:

The connection to the server <server> was refused

Solutions:

  1. Check that the cluster is running:

    # For minikube
    minikube status
    minikube start

    # For kind
    kind get clusters

  2. Check configuration:

    kubectl config view
    kubectl config current-context

  3. Check network connection:

    kubectl cluster-info

Problem 3: minikube start fails​

Possible symptoms:

  • Virtualization error
  • Resource issue (RAM/CPU)
  • Docker conflict

Solutions:

  1. Check virtualization:

    • Windows: Enable Hyper-V or VirtualBox
    • Linux: Check KVM
    • macOS: Check VirtualBox or HyperKit

  2. Allocate more resources:

    minikube start --memory=4096 --cpus=2

  3. Use a different driver:

    minikube start --driver=docker
    # or
    minikube start --driver=virtualbox

  4. Reset minikube:

    minikube delete
    minikube start

Problem 4: SSL Certificate Error​

Symptom:

x509: certificate signed by unknown authority

Solutions:

  1. Check system date:

    • Make sure your system date/time is correct

  2. Reset context:

    kubectl config use-context minikube

  3. Recreate the cluster:

    minikube delete
    minikube start

Problem 5: kubectl version shows client only​

Symptom:

kubectl version --client
# Works, but
kubectl version
# Error: Unable to connect to the server

Solution:

  • The cluster is not started or kubectl is not configured
  • Follow the "Verifying Installation" steps above

Previous chapter: Chapter 1.5 - Fundamental Concepts
Back to module: Module 1 - Introduction to Kubernetes
Next lab: Lab 1.1 - First Deployment

Chapter created: December 2024