Kubernetes (k8s) Usage#

This document provides a guide to interacting with Kubernetes clusters, focusing on kubectl (the Kubernetes command-line tool) and common helper utilities.

Overview#

Kubernetes (commonly stylized as k8s) is an open-source system for automating deployment, scaling, and management of containerized applications.

kubectl: The Kubernetes CLI#

kubectl is the primary command-line tool for running commands against Kubernetes clusters. It allows you to deploy applications, inspect and manage cluster resources, and view logs.

Installation#

• Homebrew (macOS):

  brew install kubectl
  

• Official Guides: For other operating systems or specific versions, refer to the official Kubernetes documentation on installing kubectl.

Installation might be managed by chezmoi if kubectl is part of your standard toolset.

Configuration (kubeconfig)#

kubectl uses a configuration file, typically located at ~/.kube/config, to store cluster access information (server endpoints, user credentials, namespaces, contexts).

• Multiple Clusters: The kubeconfig file can define multiple clusters and contexts.
• Context Switching: Use kubectl config use-context <context_name> to switch between defined contexts.
• Environment Variable: You can specify a different kubeconfig file by setting the KUBECONFIG environment variable:

  export KUBECONFIG=~/.kube/custom-config:~/.kube/another-config
  

• Security: Kubeconfig files can contain sensitive credentials.
  • Avoid committing them directly to public repositories.
  • Consider using tools that dynamically generate or fetch credentials (e.g., aws eks update-kubeconfig for Amazon EKS, gcloud container clusters get-credentials for GKE).
  • If you must store parts of a kubeconfig managed by chezmoi, ensure sensitive fields are templated and sourced from a secrets manager like 1Password (see docs/1password-usage.md).

Common kubectl Commands#

• Cluster Information & Contexts:

  • kubectl cluster-info: Display endpoint information about the master and services.
  • kubectl config get-contexts: List available contexts.
  • kubectl config current-context: Display the current context.
  • kubectl config use-context <context_name>: Switch to a different context.

• Viewing Resources:

  • kubectl get nodes: List all nodes in the cluster.
  • kubectl get pods [-n <namespace>] [-o wide]: List pods in a namespace (add -A or --all-namespaces for all).
  • kubectl get services [-n <namespace>]: List services.
  • kubectl get deployments [-n <namespace>]: List deployments.
  • kubectl get namespaces: List all namespaces.
  • kubectl describe pod <pod_name> [-n <namespace>]: Show detailed information about a pod.
  • kubectl describe node <node_name>: Show detailed information about a node.

• Interacting with Pods:

  • kubectl logs <pod_name> [-n <namespace>] [-c <container_name>]: Print the logs for a container in a pod.
    • kubectl logs -f <pod_name>: Follow log output.
  • kubectl exec -it <pod_name> [-n <namespace>] [-c <container_name>] -- <command>: Execute a command in a container.
    • Example (get a shell): kubectl exec -it my-pod -- /bin/sh
  • kubectl cp <file_path> <pod_name>:<path_in_pod>: Copy files and directories to and from containers.

• Managing Applications:

  • kubectl apply -f <filename.yaml_or_directory>: Apply a configuration to a resource by filename or stdin.
  • kubectl delete -f <filename.yaml>: Delete resources defined in a file.
  • kubectl delete pod <pod_name> [-n <namespace>]: Delete a pod.
  • kubectl scale deployment <deployment_name> --replicas=<count>: Scale a deployment.

• Port Forwarding:

  • kubectl port-forward <pod_name_or_service/service_name> <local_port>:<remote_port>: Forward one or more local ports to a pod or service.
    • Example: kubectl port-forward svc/my-service 8080:80

Helper Tools & Ecosystem#

• k9s: A terminal-based UI to interact with your Kubernetes clusters. Highly recommended for easier navigation and management.
  • Installation (Homebrew): brew install k9s
• kubectx + kubens: Tools to switch between Kubernetes contexts (kubectx) and namespaces (kubens) more easily.
  • Installation (Homebrew): brew install kubectx
• Helm: The package manager for Kubernetes. Helps you manage Kubernetes applications through Helm Charts.
  • Installation (Homebrew): brew install helm
• Lens: A popular open-source Kubernetes IDE for managing clusters.
• Stern: Multi-pod and container log tailing for Kubernetes.

Resources#

• Official Kubernetes Documentation: https://kubernetes.io/docs/
• kubectl Cheat Sheet: https://kubernetes.io/docs/reference/kubectl/cheatsheet/
• kubectl Command Reference: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands
• k9s: https://k9scli.io/
• kubectx + kubens: https://github.com/ahmetb/kubectx
• Helm: https://helm.sh/docs/

This document provides a starting point. Kubernetes is a complex system; refer to the official documentation and tool-specific guides for detailed information.