181 lines
6.8 KiB
Markdown
181 lines
6.8 KiB
Markdown
Getting started locally
|
|
-----------------------
|
|
|
|
**Table of Contents**
|
|
|
|
- [Requirements](#requirements)
|
|
- [Linux](#linux)
|
|
- [Docker](#docker)
|
|
- [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/).
|
|
|
|
### Docker
|
|
|
|
You will need [Docker](https://docs.docker.com/get-docker/) installed, at least version 17.03. Check the [Kubernetes release notes](https://kubernetes.io/docs/setup/release/notes/) for information about supported Docker versions.
|
|
|
|
Ensure the Docker daemon is running and can be contacted with `docker ps`. Some of the Kubernetes components need to run as root, which normally works fine with docker.
|
|
|
|
### 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#install-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 get -u github.com/cloudflare/cfssl/cmd/...
|
|
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
|
|
|
|
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.
|
|
|
|
```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
|
|
docker images
|
|
# To watch the process pull the nginx image
|
|
docker ps
|
|
# To watch all Docker processes.
|
|
```
|
|
|
|
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 the local vagrant setup 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_DOMAIN="cluster.local"
|
|
```
|
|
|
|
To know more on DNS service you can check out the [docs](http://kubernetes.io/docs/admin/dns/).
|