Codakey
Play
← Back to kuberenetes/kubernetes

How to Deploy & Use kuberenetes/kubernetes

Kubernetes Deployment and Usage Guide

Prerequisites

Required Tools

  • Git: For cloning the repository
  • Make: For running build targets
  • Go 1.21+: For building from source (see Go environment requirements)
  • Docker (optional): For containerized builds without local Go setup

System Requirements

  • Linux (preferred) or macOS for development
  • Windows with WSL2 for Linux-based builds
  • Minimum 4GB RAM for local cluster testing
  • Container runtime (containerd, CRI-O, or Docker) for running nodes

Installation

Clone the Repository

git clone https://github.com/kubernetes/kubernetes
cd kubernetes

Verify Prerequisites

# Check Go version
go version

# Verify make is installed
make --version

# Verify Docker (if using containerized builds)
docker --version

Configuration

Environment Variables

Build Configuration:

# Specify target platforms for cross-compilation
export KUBE_BUILD_PLATFORMS="linux/amd64 linux/arm64"

# Set build verbosity (0-6)
export KUBE_VERBOSE=2

# Skip tests during build
export KUBE_RUN_TESTS=n

Development Configuration:

# Set GOPATH if not using Go modules (legacy)
export GOPATH=$(go env GOPATH)

# Add Kubernetes binaries to PATH
export PATH=$PATH:$(pwd)/_output/bin

Important Notes

  • Do not use as a library: Importing k8s.io/kubernetes or k8s.io/kubernetes/... packages as libraries is not supported. Use published components from staging repositories instead.

Build & Run

Building Binaries

Standard Build (requires Go):

make

Output binaries are placed in _output/bin/.

Containerized Build (requires Docker only):

make quick-release

This builds Linux binaries for amd64, arm64, and ppc64le using a container.

Specific Targets:

# Build specific components
make WHAT=cmd/kubelet
make WHAT=cmd/kube-apiserver
make WHAT=cmd/kubectl

# Build for specific platform
make CROSS=true KUBE_BUILD_PLATFORMS=linux/amd64

Running Locally

Option 1: Local Cluster (hack/local-up-cluster.sh)

# Start etcd, API server, controller manager, scheduler, and kubelet
./hack/local-up-cluster.sh

# In another terminal, configure kubectl
export KUBECONFIG=/var/run/kubernetes/admin.kubeconfig
kubectl get nodes

Option 2: Unit Tests

# Run all tests
make test

# Run specific package tests
make test WHAT=./pkg/kubelet

# Run integration tests
make test-integration

Option 3: End-to-End Tests

# Requires running cluster
make test-e2e

Deployment

Development/Testing Clusters

Kind (Kubernetes in Docker):

# Install kind
go install sigs.k8s.io/kind@latest

# Create cluster
kind create cluster --image=kindest/node:v1.28.0

# Use cluster
kubectl cluster-info --context kind-kind

Minikube:

minikube start --kubernetes-version=stable

Production Deployment

Using kubeadm (On-Premises/VMs):

# On master node
sudo kubeadm init --pod-network-cidr=10.244.0.0/16
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

# Install CNI (e.g., Flannel)
kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml

# Join worker nodes
sudo kubeadm join <master-ip>:<port> --token <token> --discovery-token-ca-cert-hash sha256:<hash>

Cloud Managed Services:

  • AWS: Use EKS (Elastic Kubernetes Service)
  • GCP: Use GKE (Google Kubernetes Engine)
  • Azure: Use AKS (Azure Kubernetes Service)

From Source (Advanced): For deploying custom builds to production:

  1. Build release artifacts: make release
  2. Push to container registry: make push
  3. Deploy using your configuration management tool (kustomize, helm, or raw manifests)

Troubleshooting

Build Issues

Error: "Go version is too old"

# Check installed version
go version

# Install Go 1.21+ from https://go.dev/doc/install

Error: "Cannot find package"

# Ensure modules are enabled
export GO111MODULE=on

# Download dependencies
go mod download

Error: "make: *** No rule to make target"

# Ensure you're in the kubernetes directory root
cd kubernetes
ls -la Makefile  # Should exist

Runtime Issues

API Server won't start

  • Check etcd is running: systemctl status etcd or docker ps | grep etcd
  • Verify ports are free: netstat -tulpn | grep 6443
  • Check logs: /var/log/kube-apiserver.log or journalctl -u kubelet

Node NotReady

# Check kubelet status
systemctl status kubelet
journalctl -u kubelet -f

# Verify container runtime
crictl ps

# Check node conditions
kubectl describe node <node-name>

DNS Resolution Failures

# Check CoreDNS pods
kubectl get pods -n kube-system -l k8s-app=kube-dns

# Test DNS from pod
kubectl run -it --rm debug --image=busybox:1.28 --restart=Never -- nslookup kubernetes.default

Testing Failures

Unit tests timeout

# Run with increased timeout
make test WHAT=./pkg/kubelet TIMEOUT=10m

# Run specific test
go test ./pkg/kubelet -run TestSpecificName -v

E2E tests can't find cluster

# Ensure KUBECONFIG is set
export KUBECONFIG=~/.kube/config

# Verify cluster access
kubectl cluster-info

Getting Help

← Project overviewView alternatives to kuberenetes/kubernetes →