The following procedure creates a Kubernetes cluster using four worker VMs and one master VM (a total of five virtual machines). You can manage this cluster from you're local workstation or any preferred environment.

Before You Begin

For a simplified setup with a graphical user interface, consider using Google Kubernetes Engine (GKE) to provision and manage a hosted cluster. If you need to use custom binaries or the upstream open-source Kubernetes, follow the steps below.

Prerequisites

1. You need a Google Cloud Platform billing account. Refer to the Google Developers Console for details.

2. Install the gcloud command-line tool as part of the Google Cloud SDK.

3. Ensure you have the gcloud preview CLI components installed. Run gcloud preview in a terminal. If it prompts you to install any components, follow the instructions. If it simply displays help text, you are set. This is required because the cluster setup script uses GCE instance groups from the gcloud preview namespace. Additionally, enable the Compute Engine Instance Group Manager API in the Developers Console.

4. Confirm that gcloud is configured to use your intended GCP project. Check the current project with gcloud config list project and change it with gcloud config set project <project-id>.

5. Ensure you have GCloud credentials authenticated via gcloud auth login.

6. Verify you can launch a GCE VM from the command line. At a minimum, you should be able to complete the "Create an instance" part of the GCE quickstart.

7. Make sure you can SSH into a VM without interactive prompts. See the "Log in to an instance" section of the GCE quickstart.

Starting the Cluster

You can install the cliant binaries and bring up the cluster using either of the following commands (listed for compatibility with different systems):

curl -sS https://get.k8s.io | bash

Or:

wget -q -O - https://get.k8s.io | bash

After completion, one master VM and four worker VMs will be running as a Kubernetes cluster.

By default, several containers are deployed on the cluster, including logging (kibana and elasticsearch) and monitoring (heapster) components.

The command above executes a script that creates a cluster named or prefixed with "kubernetes". It appleis a specific configuration and should be run only once.

Alternatively, download and extract the latest Kubernetes release from the releases page, then run:

cd kubernetes
cluster/kube-up.sh

If you need multiple clusters in the same project, different names, or different node counts, review the file /cluster/gce/config-default.sh before starting the cluster for finer-grained settings.

For issues, refer to the Troubleshooting section, contact the Google Container Group, or ask on IRC freenode in the #google-containers channel.

Installing the Kubernetes CLI on Your Workstation

After the cluster startup, your workstation will contain a running cluster and a kubernetes directory. Ensure the kubectl binary is in your PATH.

kubectl is the command-line tool for controlling Kubernetes clusters. It allows you to inspect cluster resources, create, delete, and update components, and more. Add the appropriate binary folder to your PATH:

# macOS
export PATH=<path/to/kubernetes-directory>/platforms/darwin/amd64:$PATH

# Linux
export PATH=<path/to/kubernetes-directory>/platforms/linux/amd64:$PATH

Note: gcloud bundles kubectl and may add it to your PATH automatically. However, the version bundled with gcloud might be older than the one downloaded by the get.k8s.io installer. Using the downloaded binary is recommended to avoid client/server version mismatches.

Bash Completion for kubectl

Enable bash completion for kubectl:

source ./contrib/completions/bash/kubectl

This completion is session-specific. To make it permanent, add the line to your ~/.bash_profile. Alternatively, on many Linux distributions, copy the completion file to /etc/bash_completion.d/:

sudo cp ./contrib/completions/bash/kubectl /etc/bash_completion.d/

Note that you must update this file when you update kubectl.

Monitoring Your Cluster

With kubectl in your path, verify the cluster:

kubectl get --all-namespaces services

This should list a set of services. To see the pods created during startup:

kubectl get --all-namespaces pods

A sample output (specific names differ):

NAMESPACE     NAME                                      READY   STATUS    RESTARTS   AGE
kube-system   fluentd-cloud-logging-kubernetes-minion-63uo   1/1     Running   0          14m
kube-system   fluentd-cloud-logging-kubernetes-minion-c1n9   1/1     Running   0          14m
kube-system   fluentd-cloud-logging-kubernetes-minion-c4og   1/1     Running   0          14m
kube-system   fluentd-cloud-logging-kubernetes-minion-ngua   1/1     Running   0          14m
kube-system   kube-dns-v5-7ztia                           3/3     Running   0          15m
kube-system   kube-ui-v1-curt1                            1/1     Running   0          15m
kube-system   monitoring-heapster-v5-ex4u3                 1/1     Running   1          15m
kube-system   monitoring-influx-grafana-v1-piled           2/2     Running   0          15m

Some pods may take a few seconds to start (they appear as Pending initially). Re-check after a short while; they should all show Running.

Run a Sample Application

Test the new cluster with a simple nginx deployment. For complete application examples, see the examples/ directory. The Guestbook application is a good introductory walkthrough.

Tearing Down the Cluster

Use the kube-down.sh script to remove or dismantle the cluster:

cd kubernetes
cluster/kube-down.sh

After teardown, you can recreate the cluster by running kube-up.sh again from the same directory. There is no need to re-run the curl or wget command; everything needed is already on your workstation.

Customizing the Cluster

The scripts above rely on Google Cloud Storage to stage the Kubernetes release. They launch (by default) a single master and four worker VMs. You can modify parameters in kubernetes/cluster/gce/config-default.sh to change configuration. Review the cluster creation log after edits.

Troubleshooting

Project Settings

• Enable the Google Cloud Storage API and Google Cloud Storage JSON API (usually enabled by default for new projects). If not, enable them in the Google Cloud Console.
• As listed in the prerequisites, ensure the Compute Engine Instance Group Manager API is enabled and that you can launch a GCE VM from the command line according to the GCE quickstart.

Cluster Initialization Hangs

If the Kubernetes startup script hangs while waiting for the API to become available, SSH into the master and node VMs to examine logs, such as:

/var/log/startupscript.log

After resolving any issues, run kube-down.sh to clean up partially created cluster resources before attempting kube-up.sh again.

SSH Issues

If you cannot SSH into instances, verify that GCE firewall rules allow incoming traffic on port 22. By default, connectivity is enabled, but if you modified firewall rules or created a custom network, expose the port:

gcloud compute firewall-rules create default-ssh --network=<network-name> --description "SSH allowed" --allow tcp:22

Also, ensure your GCE SSH keys either have no passphrase or are handled by ssh-agent.

Network Communication

Instances must be able to reach each other using their private IPs. The script uses the "default" network, which includes a firewall rule called "default-allow-internal" that permits all traffic on private IPs. If this rule is missing or you are using a different network (specified in cluster/config-default.sh), create a new rule with:

• Source Ranges: 10.0.0.0/8
• Allowed Protocols and Ports: tcp:1-65535;udp:1-65535;icmp