Environment Requirements

Linux

If a Linux host is not available, consider using Vagrant to run a virtual machine or a cloud service like Google Compute Engine.

Docker

A minimum of Docker 1.3+ is required. Ensure the Docker daemon is active and responsive (e.g., docker ps works). Some Kubernetes components require root privileges to interact correctly with Docker.

etcd

Configure etcd in your environment. Install it and ensure its binary is in your $PATH.

Go

Go version 1.3 or higher is necessary. Install Go and set up your $GOPATH and $PATH accordingly.

Starting the Cluster

Open a new terminal session. Run the following commands. Since starting and stopping Kubernetes daemons requires root access, exeucting the script with elevated privileges simplifies the process:

cd /usr/src/kubernetes
sudo ./hack/local-up-cluster.sh

This command builds and launches a lightweight cluster with one master and one node. Press Ctrl+C to terminate the cluster.

Deploying Containers

Once the cluster is operational, use the kubectl.sh script within the cluster/ directory to manage it:

./cluster/kubectl.sh get pods
./cluster/kubectl.sh get services
./cluster/kubectl.sh get replicationcontrollers
./cluster/kubectl.sh run web-server --image=nginx --replicas=2 --port=80

While the command is processing, open another terminal to observe the container status:

sudo docker images # Observe nginx image being pulled
sudo docker ps    # View running containers
exit

After completion, verify the deployment:

./cluster/kubectl.sh get pods
./cluster/kubectl.sh get services
./cluster/kubectl.sh get replicationcontrollers

Running User-Defined Pods

Distinguish between a container and a pod. Requesting a container from Kubernetes results in a pod being created to encapsulate it. To expose a service like nginx, define a pod manifest specifying the port.

Create a pod using a custom definition:

./cluster/kubectl.sh create -f ./examples/nginx-pod.yaml

Troubleshooting

Cannot access service via IP Firewall tools using iptables may conflict with Kubernetes networking. Temporarily disable firewalls or other iptables-based systems. Check for SELinux denials with journalctl --since yesterday | grep avc.

The default service IP range is 10.0.0.0/8, which may overlap with Docker container IPs. If a conflict occurs, edit the hack/local-up-cluster.sh script to adjust the clutser's IP range.

Replica controller fails when replicas > 1 The single-node setup limits the number of pod replicas. For larger deployments, use Vagrant or a cloud provider.

How to run after modifying Kubernetes code

cd /usr/src/kubernetes
./hack/build-go.sh
sudo ./hack/local-up-cluster.sh

kubectl shows pod started, but get pods and docker ps show nothing The local cluster script does not enable DNS. A manual workaround or alternative solution is required.