1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
Getting started locally
-----------------------
**Table of Contents**
- [Requirements](#requirements)
- [Linux](#linux)
- [Container Runtime](#container-runtime)
- [etcd](#etcd)
- [go](#go)
- [OpenSSL](#openssl)
- [CFSSL](#cfssl)
- [Clone the repository](#clone-the-repository)
- [Starting the cluster](#starting-the-cluster)
- [Running a container](#running-a-container)
- [Running a user defined pod](#running-a-user-defined-pod)
- [Troubleshooting](#troubleshooting)
- [I cannot reach service IPs on the network.](#i-cannot-reach-service-ips-on-the-network)
- [I cannot create a replication controller with replica size greater than 1! What gives?](#i-cannot-create-a-replication-controller-with-replica-size-greater-than-1--what-gives)
- [I changed Kubernetes code, how do I run it?](#i-changed-kubernetes-code-how-do-i-run-it)
- [kubectl claims to start a container but `get pods` and `docker ps` don't show it.](#kubectl-claims-to-start-a-container-but-get-pods-and-docker-ps-dont-show-it)
- [The pods fail to connect to the services by host names](#the-pods-fail-to-connect-to-the-services-by-host-names)
## Requirements
### Linux
Not running Linux? Consider running [Minikube](https://kubernetes.io/docs/setup/learning-environment/minikube/), or on a cloud provider like [Google Compute Engine](https://kubernetes.io/docs/setup/production-environment/turnkey/gce/).
### Container Runtime
You will need a [Container Runtime](https://kubernetes.io/docs/setup/production-environment/container-runtimes/) like [Containerd](https://github.com/containerd/containerd) or [CRI-O](https://github.com/cri-o/cri-o) installed and running.
### etcd
You need [etcd](https://github.com/coreos/etcd/releases) installed and in your `$PATH`. [Check here](https://github.com/kubernetes/community/blob/master/contributors/devel/development.md#etcd) for instructions on installing a local copy.
### go
You need [go](https://golang.org/doc/install) in your path (see [Development Guide](development.md#go) for supported versions), please make sure it is installed and in your ``$PATH``.
### OpenSSL
You need [OpenSSL](https://www.openssl.org/) installed. If you do not have the `openssl` command available, the script will print an appropriate error.
### CFSSL
The [CFSSL](https://cfssl.org/) binaries (cfssl, cfssljson) must be installed and available on your ``$PATH``.
The easiest way to get it is to run these shell commands:
```sh
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.
```sh
git clone --depth=1 https://github.com/kubernetes/kubernetes.git
```
The `--depth=1` parameter is optional and will ensure a smaller download.
## Starting the cluster
Set the endpoint for container runtime e.g. containerd
```sh
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:
```sh
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:
```sh
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.
```sh
./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
```sh
export KUBECONFIG=/var/run/kubernetes/admin.kubeconfig
```
```sh
./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.
```sh
# 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.
```sh
./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](https://kubernetes.io/docs/user-guide/containers/)
and a [pod](https://kubernetes.io/docs/user-guide/pods/). 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:
```sh
./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?
```sh
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:
```sh
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](http://kubernetes.io/docs/admin/dns/).
### 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.
```sh
export CGROUP_DRIVER=systemd
```
|
