Skip to content

Latest commit

 

History

History
198 lines (134 loc) · 7.57 KB

running-locally.md

File metadata and controls

198 lines (134 loc) · 7.57 KB

Getting started locally

Table of Contents

Requirements

Linux

Not running Linux? Consider running Minikube, or on a cloud provider like Google Compute Engine.

Container Runtime

You will need a Container Runtime like Containerd or CRI-O installed and running.

etcd

You need etcd installed and in your $PATH. Check here for instructions on installing a local copy.

go

You need go in your path (see Development Guide for supported versions), please make sure it is installed and in your $PATH.

OpenSSL

You need OpenSSL installed. If you do not have the openssl command available, the script will print an appropriate error.

CFSSL

The CFSSL binaries (cfssl, cfssljson) must be installed and available on your $PATH.

The easiest way to get it is to run these shell commands:

go install github.com/cloudflare/cfssl/cmd/...@latest
PATH=$PATH:$GOPATH/bin

Clone the repository

In order to run kubernetes you must have the kubernetes code on the local machine. Cloning this repository is sufficient.

git clone --filter=blob:none https://github.com/kubernetes/kubernetes.git

The --filter=blob:none parameter is optional and will ensure a smaller download.

Starting the cluster

Set the endpoint for container runtime e.g. containerd

export CONTAINER_RUNTIME_ENDPOINT="unix:///run/containerd/containerd.sock"

Optionally set any other environment variables as needed to change the cluster configuration. The possible options are listed at the top of the ./hack/local-up-cluster.sh script.

In a separate tab of your terminal, run the following:

cd kubernetes
./hack/local-up-cluster.sh

Since root access is sometimes needed to start/stop Kubernetes daemons, ./hack/local-up-cluster.sh may need to be run as root. If it reports failures, try this instead:

sudo ./hack/local-up-cluster.sh

This will build and start a lightweight local cluster, consisting of a master and a single node. Press Control+C to shut it down.

Note: If you've already compiled the Kubernetes components, you can avoid rebuilding them with the -O flag.

./hack/local-up-cluster.sh -O

You can use the ./cluster/kubectl.sh script to interact with the local cluster. ./hack/local-up-cluster.sh will print the commands to run to point kubectl at the local cluster.

Running a container

Your cluster is running, and you want to start running containers!

You can now use any of the cluster/kubectl.sh commands to interact with your local setup after setting your KUBECONFIG

export KUBECONFIG=/var/run/kubernetes/admin.kubeconfig
./cluster/kubectl.sh get pods
./cluster/kubectl.sh get services
./cluster/kubectl.sh get replicationcontrollers
./cluster/kubectl.sh run my-nginx --image=nginx --port=80

While waiting for the provisioning to complete, you can monitor progress in another terminal with these commands.

# containerd
# To list images
ctr --namespace k8s.io image ls
# To list containers
ctr --namespace k8s.io containers ls

Once provisioning is complete, you can use the following commands for Kubernetes introspection.

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

Running a user defined pod

Note the difference between a container and a pod. Since you only asked for the former, Kubernetes will create a wrapper pod for you. However, you cannot view the nginx start page on localhost. To verify that nginx is running, you need to run curl within the Docker container (try docker exec).

You can control the specifications of a pod via a user defined manifest, and reach nginx through your browser on the port specified therein:

./cluster/kubectl.sh create -f test/fixtures/doc-yaml/user-guide/pod.yaml

Congratulations!

Troubleshooting

I cannot reach service IPs on the network.

Some firewall software that uses iptables may not interact well with kubernetes. If you have trouble around networking, try disabling any firewall or other iptables-using systems, first. Also, you can check if SELinux is blocking anything by running a command such as journalctl --since yesterday | grep avc.

By default the IP range for service cluster IPs is 10.0.. - depending on your docker installation, this may conflict with IPs for containers. If you find containers running with IPs in this range, edit hack/local-cluster-up.sh and change the service-cluster-ip-range flag to something else.

I cannot create a replication controller with replica size greater than 1! What gives?

You are running a single node setup. This has the limitation of only supporting a single replica of a given pod. If you are interested in running with larger replica sizes, we encourage you to try Kind or one of the cloud providers.

I changed Kubernetes code, how do I run it?

cd kubernetes
make
./hack/local-up-cluster.sh

kubectl claims to start a container but get pods and docker ps don't show it.

One or more of the Kubernetes daemons might've crashed. Tail the logs of each in /tmp.

The pods fail to connect to the services by host names

To start the DNS service, you need to set the following variables:

KUBE_ENABLE_CLUSTER_DNS=true
KUBE_DNS_SERVER_IP="10.0.0.10"
KUBE_DNS_NAME="cluster.local"

To know more on DNS service you can check out the docs and see Debugging DNS Resolution for diagnosing DNS problems.

All pod fail to start with a cgroups error of expected cgroupsPath to be of format "slice:prefix:name" for systemd cgroups

Your container runtime is using the systemd cgroup driver, but by default ./hack/local-up-cluster.sh uses cgroupfs. To correct the mismatch, set the CGROUP_DRIVER environment variable to systemd as well.

export CGROUP_DRIVER=systemd