github
/
k3s
mirror of https://github.com/k3s-io/k3s
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

updates to vagrant.md 

Signed-off-by: mikebrow <brownwm@us.ibm.com>
pull/6/head
mikebrow 2016-04-19 14:52:56 -05:00
parent 4638f2f355
commit eb43e19fd0
1 changed files with 236 additions and 186 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

422
docs/devel/developer-guides/vagrant.md
View File

@ -34,45 +34,67 @@ Documentation for other releases can be found at
## Getting started with Vagrant
Running kubernetes with Vagrant (and VirtualBox) is an easy way to run/test/develop on your local machine (Linux, Mac OS X).
Running Kubernetes with Vagrant is an easy way to run/test/develop on your
local machine in an environment using the same setup procedures when running on
GCE or AWS cloud providers. This provider is not tested on a per PR basis, if
you experience bugs when testing from HEAD, please open an issue.
### Prerequisites
1. Install latest version >= 1.6.2 of vagrant from http://www.vagrantup.com/downloads.html
2. Install one of:
1. The latest version of Virtual Box from https://www.virtualbox.org/wiki/Downloads
2. [VMWare Fusion](https://www.vmware.com/products/fusion/) version 5 or greater as well as the appropriate [Vagrant VMWare Fusion provider](https://www.vagrantup.com/vmware)
3. [VMWare Workstation](https://www.vmware.com/products/workstation/) version 9 or greater as well as the [Vagrant VMWare Workstation provider](https://www.vagrantup.com/vmware)
4. [Parallels Desktop](https://www.parallels.com/products/desktop/) version 9 or greater as well as the [Vagrant Parallels provider](https://parallels.github.io/vagrant-parallels/)
3. Get or build a [binary release](../../../docs/getting-started-guides/binary_release.md)
1. Install latest version >= 1.8.1 of vagrant from
http://www.vagrantup.com/downloads.html
2. Install a virtual machine host. Examples:
1. [Virtual Box](https://www.virtualbox.org/wiki/Downloads)
2. [VMWare Fusion](https://www.vmware.com/products/fusion/) plus
[Vagrant VMWare Fusion provider](https://www.vagrantup.com/vmware)
3. [Parallels Desktop](https://www.parallels.com/products/desktop/)
plus
[Vagrant Parallels provider](https://parallels.github.io/vagrant-parallels/)
3. Get or build a
[binary release](../../../docs/getting-started-guides/binary_release.md)
### Setup
Setting up a cluster is as simple as running:
```sh
```shell
export KUBERNETES_PROVIDER=vagrant
curl -sS https://get.k8s.io | bash
```
Alternatively, you can download [Kubernetes release](https://github.com/kubernetes/kubernetes/releases) and extract the archive. To start your local cluster, open a shell and run:
Alternatively, you can download
[Kubernetes release](https://github.com/kubernetes/kubernetes/releases) and
extract the archive. To start your local cluster, open a shell and run:
```sh
```shell
cd kubernetes
export KUBERNETES_PROVIDER=vagrant
./cluster/kube-up.sh
```
The `KUBERNETES_PROVIDER` environment variable tells all of the various cluster management scripts which variant to use. If you forget to set this, the assumption is you are running on Google Compute Engine.
The `KUBERNETES_PROVIDER` environment variable tells all of the various cluster
management scripts which variant to use. If you forget to set this, the
assumption is you are running on Google Compute Engine.
By default, the Vagrant setup will create a single master VM (called kubernetes-master) and one node (called kubernetes-node-1). Each VM will take 1 GB, so make sure you have at least 2GB to 4GB of free memory (plus appropriate free disk space).
By default, the Vagrant setup will create a single master VM (called
kubernetes-master) and one node (called kubernetes-node-1). Each VM will take 1
GB, so make sure you have at least 2GB to 4GB of free memory (plus appropriate
free disk space).
Vagrant will provision each machine in the cluster with all the necessary components to run Kubernetes. The initial setup can take a few minutes to complete on each machine.
Vagrant will provision each machine in the cluster with all the necessary
components to run Kubernetes. The initial setup can take a few minutes to
complete on each machine.
If you installed more than one Vagrant provider, Kubernetes will usually pick the appropriate one. However, you can override which one Kubernetes will use by setting the [`VAGRANT_DEFAULT_PROVIDER`](https://docs.vagrantup.com/v2/providers/default.html) environment variable:
If you installed more than one Vagrant provider, Kubernetes will usually pick
the appropriate one. However, you can override which one Kubernetes will use by
setting the
[`VAGRANT_DEFAULT_PROVIDER`](https://docs.vagrantup.com/v2/providers/default.html)
environment variable:
```sh
```shell
export VAGRANT_DEFAULT_PROVIDER=parallels
export KUBERNETES_PROVIDER=vagrant
./cluster/kube-up.sh
@ -82,25 +104,26 @@ By default, each VM in the cluster is running Fedora.
To access the master or any node:
```sh
```shell
vagrant ssh master
vagrant ssh node-1
```
If you are running more than one node, you can access the others by:
```sh
```shell
vagrant ssh node-2
vagrant ssh node-3
```
Each node in the cluster installs the docker daemon and the kubelet.
The master node instantiates the Kubernetes master components as pods on the machine.
The master node instantiates the Kubernetes master components as pods on the
machine.
To view the service status and/or logs on the kubernetes-master:
```console
```shell
[vagrant@kubernetes-master ~] $ vagrant ssh master
[vagrant@kubernetes-master ~] $ sudo su
@ -117,7 +140,7 @@ To view the service status and/or logs on the kubernetes-master:
To view the services on any of the nodes:
```console
```shell
[vagrant@kubernetes-master ~] $ vagrant ssh node-1
[vagrant@kubernetes-master ~] $ sudo su
@ -130,197 +153,134 @@ To view the services on any of the nodes:
### Interacting with your Kubernetes cluster with Vagrant.
With your Kubernetes cluster up, you can manage the nodes in your cluster with the regular Vagrant commands.
With your Kubernetes cluster up, you can manage the nodes in your cluster with
the regular Vagrant commands.
To push updates to new Kubernetes code after making source changes:
```sh
```shell
./cluster/kube-push.sh
```
To stop and then restart the cluster:
```sh
```shell
vagrant halt
./cluster/kube-up.sh
```
To destroy the cluster:
```sh
```shell
vagrant destroy
```
Once your Vagrant machines are up and provisioned, the first thing to do is to check that you can use the `kubectl.sh` script.
Once your Vagrant machines are up and provisioned, the first thing to do is to
check that you can use the `kubectl.sh` script.
You may need to build the binaries first, you can do this with `make`
```console
```shell
$ ./cluster/kubectl.sh get nodes
NAME LABELS STATUS
kubernetes-node-0whl kubernetes.io/hostname=kubernetes-node-0whl Ready
kubernetes-node-4jdf kubernetes.io/hostname=kubernetes-node-4jdf Ready
kubernetes-node-epbe kubernetes.io/hostname=kubernetes-node-epbe Ready
```
### Interacting with your Kubernetes cluster with the `kube-*` scripts.
Alternatively to using the vagrant commands, you can also use the `cluster/kube-*.sh` scripts to interact with the vagrant based provider just like any other hosting platform for kubernetes.
All of these commands assume you have set `KUBERNETES_PROVIDER` appropriately:
```sh
export KUBERNETES_PROVIDER=vagrant
```
Bring up a vagrant cluster
```sh
./cluster/kube-up.sh
```
Destroy the vagrant cluster
```sh
./cluster/kube-down.sh
```
Update the vagrant cluster after you make changes (only works when building your own releases locally):
```sh
./cluster/kube-push.sh
```
Interact with the cluster
```sh
./cluster/kubectl.sh
```
### Authenticating with your master
When using the vagrant provider in Kubernetes, the `cluster/kubectl.sh` script will cache your credentials in a `~/.kubernetes_vagrant_auth` file so you will not be prompted for them in the future.
When using the vagrant provider in Kubernetes, the `cluster/kubectl.sh` script
will cache your credentials in a `~/.kubernetes_vagrant_auth` file so you will
not be prompted for them in the future.
```console
$ cat ~/.kubernetes_vagrant_auth
```shell
cat ~/.kubernetes_vagrant_auth
```
```json
{ "User": "vagrant",
"Password": "vagrant"
"Password": "vagrant",
"CAFile": "/home/k8s_user/.kubernetes.vagrant.ca.crt",
"CertFile": "/home/k8s_user/.kubecfg.vagrant.crt",
"KeyFile": "/home/k8s_user/.kubecfg.vagrant.key"
}
```
You should now be set to use the `cluster/kubectl.sh` script. For example try to list the nodes that you have started with:
You should now be set to use the `cluster/kubectl.sh` script. For example try to
list the nodes that you have started with:
```sh
```shell
./cluster/kubectl.sh get nodes
```
### Running containers
Your cluster is running, you can list the nodes in your cluster:
You can use `cluster/kube-*.sh` commands to interact with your VM machines:
```console
$ ./cluster/kubectl.sh get nodes
NAME LABELS STATUS
kubernetes-node-0whl kubernetes.io/hostname=kubernetes-node-0whl Ready
kubernetes-node-4jdf kubernetes.io/hostname=kubernetes-node-4jdf Ready
kubernetes-node-epbe kubernetes.io/hostname=kubernetes-node-epbe Ready
```
Now start running some containers!
You can now use any of the cluster/kube-*.sh commands to interact with your VM machines.
Before starting a container there will be no pods, services and replication controllers.
```console
$ cluster/kubectl.sh get pods
NAME READY STATUS RESTARTS AGE
$ cluster/kubectl.sh get services
NAME LABELS SELECTOR IP(S) PORT(S)
$ cluster/kubectl.sh get rc
CONTROLLER CONTAINER(S) IMAGE(S) SELECTOR REPLICAS
```
Start a container running nginx with a replication controller and three replicas
```console
$ cluster/kubectl.sh run my-nginx --image=nginx --replicas=3 --port=80
CONTROLLER CONTAINER(S) IMAGE(S) SELECTOR REPLICAS
my-nginx my-nginx nginx run=my-nginx 3
```
When listing the pods, you will see that three containers have been started and are in Waiting state:
```console
$ cluster/kubectl.sh get pods
NAME READY STATUS RESTARTS AGE
my-nginx-389da 1/1 Waiting 0 33s
my-nginx-kqdjk 1/1 Waiting 0 33s
my-nginx-nyj3x 1/1 Waiting 0 33s
```
You need to wait for the provisioning to complete, you can monitor the nodes by doing:
```console
$ sudo salt '*node-1' cmd.run 'docker images'
kubernetes-node-1:
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
<none> <none> 96864a7d2df3 26 hours ago 204.4 MB
kubernetes/pause latest 6c4579af347b 8 weeks ago 239.8 kB
```
Once the docker image for nginx has been downloaded, the container will start and you can list it:
```console
$ sudo salt '*node-1' cmd.run 'docker ps'
kubernetes-node-1:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
dbe79bf6e25b nginx:latest "nginx" 21 seconds ago Up 19 seconds k8s--mynginx.8c5b8a3a--7813c8bd_-_3ffe_-_11e4_-_9036_-_0800279696e1.etcd--7813c8bd_-_3ffe_-_11e4_-_9036_-_0800279696e1--fcfa837f
fa0e29c94501 kubernetes/pause:latest "/pause" 8 minutes ago Up 8 minutes 0.0.0.0:8080->80/tcp k8s--net.a90e7ce4--7813c8bd_-_3ffe_-_11e4_-_9036_-_0800279696e1.etcd--7813c8bd_-_3ffe_-_11e4_-_9036_-_0800279696e1--baf5b21b
```
Going back to listing the pods, services and replicationcontrollers, you now have:
```console
$ cluster/kubectl.sh get pods
NAME READY STATUS RESTARTS AGE
my-nginx-389da 1/1 Running 0 33s
my-nginx-kqdjk 1/1 Running 0 33s
my-nginx-nyj3x 1/1 Running 0 33s
$ cluster/kubectl.sh get services
NAME LABELS SELECTOR IP(S) PORT(S)
$ cluster/kubectl.sh get rc
NAME IMAGE(S) SELECTOR REPLICAS
my-nginx nginx run=my-nginx 3
```
We did not start any services, hence there are none listed. But we see three replicas displayed properly.
Check the [guestbook](../../../examples/guestbook/README.md) application to learn how to create a service.
You can already play with scaling the replicas with:
```console
$ ./cluster/kubectl.sh scale rc my-nginx --replicas=2
```shell
$ ./cluster/kubectl.sh get pods
NAME READY STATUS RESTARTS AGE
my-nginx-kqdjk 1/1 Running 0 13m
my-nginx-nyj3x 1/1 Running 0 13m
NAME READY STATUS RESTARTS AGE
$ ./cluster/kubectl.sh get services
NAME CLUSTER_IP EXTERNAL_IP PORT(S) SELECTOR AGE
$ ./cluster/kubectl.sh get deployments
CONTROLLER CONTAINER(S) IMAGE(S) SELECTOR REPLICAS
```
To Start a container running nginx with a Deployment and three replicas:
```shell
$ ./cluster/kubectl.sh run my-nginx --image=nginx --replicas=3 --port=80
```
When listing the pods, you will see that three containers have been started and
are in Waiting state:
```shell
$ ./cluster/kubectl.sh get pods
NAME READY STATUS RESTARTS AGE
my-nginx-3800858182-4e6pe 0/1 ContainerCreating 0 3s
my-nginx-3800858182-8ko0s 1/1 Running 0 3s
my-nginx-3800858182-seu3u 0/1 ContainerCreating 0 3s
```
When the provisioning is complete:
```shell
$ ./cluster/kubectl.sh get pods
NAME READY STATUS RESTARTS AGE
my-nginx-3800858182-4e6pe 1/1 Running 0 40s
my-nginx-3800858182-8ko0s 1/1 Running 0 40s
my-nginx-3800858182-seu3u 1/1 Running 0 40s
$ ./cluster/kubectl.sh get services
NAME CLUSTER_IP EXTERNAL_IP PORT(S) SELECTOR AGE
$ ./cluster/kubectl.sh get deployments
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
my-nginx 3 3 3 3 1m
```
We did not start any Services, hence there are none listed. But we see three
replicas displayed properly. Check the
[guestbook](https://github.com/kubernetes/kubernetes/tree/%7B%7Bpage.githubbranch%7D%7D/examples/guestbook)
application to learn how to create a Service. You can already play with scaling
the replicas with:
```shell
$ ./cluster/kubectl.sh scale deployments my-nginx --replicas=2
$ ./cluster/kubectl.sh get pods
NAME READY STATUS RESTARTS AGE
my-nginx-3800858182-4e6pe 1/1 Running 0 2m
my-nginx-3800858182-8ko0s 1/1 Running 0 2m
```
Congratulations!
### Testing
The following will run all of the end-to-end testing scenarios assuming you set your environment in `cluster/kube-env.sh`:
The following will run all of the end-to-end testing scenarios assuming you set
your environment in `cluster/kube-env.sh`:
```sh
```shell
NUM_NODES=3 go run hack/e2e.go -v --build --up --test --down
```
@ -328,27 +288,74 @@ NUM_NODES=3 go run hack/e2e.go -v --build --up --test --down
#### I keep downloading the same (large) box all the time!
By default the Vagrantfile will download the box from S3. You can change this (and cache the box locally) by providing a name and an alternate URL when calling `kube-up.sh`
By default the Vagrantfile will download the box from S3. You can change this
(and cache the box locally) by providing a name and an alternate URL when
calling `kube-up.sh`
```sh
```shell
export KUBERNETES_BOX_NAME=choose_your_own_name_for_your_kuber_box
export KUBERNETES_BOX_URL=path_of_your_kuber_box
export KUBERNETES_PROVIDER=vagrant
./cluster/kube-up.sh
```
#### I am getting timeouts when trying to curl the master from my host!
During provision of the cluster, you may see the following message:
```shell
Validating node-1
.............
Waiting for each node to be registered with cloud provider
error: couldn't read version from server: Get https://10.245.1.2/api: dial tcp 10.245.1.2:443: i/o timeout
```
Some users have reported VPNs may prevent traffic from being routed to the host
machine into the virtual machine network.
To debug, first verify that the master is binding to the proper IP address:
```
$ vagrant ssh master
$ ifconfig | grep eth1 -C 2
eth1: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500 inet 10.245.1.2 netmask
255.255.255.0 broadcast 10.245.1.255
```
Then verify that your host machine has a network connection to a bridge that can
serve that address:
```shell
$ ifconfig | grep 10.245.1 -C 2
vboxnet5: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
inet 10.245.1.1 netmask 255.255.255.0 broadcast 10.245.1.255
inet6 fe80::800:27ff:fe00:5 prefixlen 64 scopeid 0x20<link>
ether 0a:00:27:00:00:05 txqueuelen 1000 (Ethernet)
```
If you do not see a response on your host machine, you will most likely need to
connect your host to the virtual network created by the virtualization provider.
If you do see a network, but are still unable to ping the machine, check if your
VPN is blocking the request.
#### I just created the cluster, but I am getting authorization errors!
You probably have an incorrect ~/.kubernetes_vagrant_auth file for the cluster you are attempting to contact.
You probably have an incorrect ~/.kubernetes_vagrant_auth file for the cluster
you are attempting to contact.
```sh
```shell
rm ~/.kubernetes_vagrant_auth
```
After using kubectl.sh make sure that the correct credentials are set:
```console
$ cat ~/.kubernetes_vagrant_auth
```shell
cat ~/.kubernetes_vagrant_auth
```
```json
{
"User": "vagrant",
"Password": "vagrant"
@ -357,45 +364,88 @@ $ cat ~/.kubernetes_vagrant_auth
#### I just created the cluster, but I do not see my container running!
If this is your first time creating the cluster, the kubelet on each node schedules a number of docker pull requests to fetch prerequisite images. This can take some time and as a result may delay your initial pod getting provisioned.
If this is your first time creating the cluster, the kubelet on each node
schedules a number of docker pull requests to fetch prerequisite images. This
can take some time and as a result may delay your initial pod getting
provisioned.
#### I changed Kubernetes code, but it's not running!
#### I have Vagrant up but the nodes won't validate!
Are you sure there was no build error? After running `$ vagrant provision`, scroll up and ensure that each Salt state was completed successfully on each box in the cluster.
It's very likely you see a build error due to an error in your source files!
#### I have brought Vagrant up but the nodes won't validate!
Are you sure you built a release first? Did you install `net-tools`? For more clues, login to one of the nodes (`vagrant ssh node-1`) and inspect the salt minion log (`sudo cat /var/log/salt/minion`).
Log on to one of the nodes (`vagrant ssh node-1`) and inspect the salt minion
log (`sudo cat /var/log/salt/minion`).
#### I want to change the number of nodes!
You can control the number of nodes that are instantiated via the environment variable `NUM_NODES` on your host machine. If you plan to work with replicas, we strongly encourage you to work with enough nodes to satisfy your largest intended replica size. If you do not plan to work with replicas, you can save some system resources by running with a single node. You do this, by setting `NUM_NODES` to 1 like so:
You can control the number of nodes that are instantiated via the environment
variable `NUM_NODES` on your host machine. If you plan to work with replicas, we
strongly encourage you to work with enough nodes to satisfy your largest
intended replica size. If you do not plan to work with replicas, you can save
some system resources by running with a single node. You do this, by setting
`NUM_NODES` to 1 like so:
```sh
```shell
export NUM_NODES=1
```
#### I want my VMs to have more memory!
You can control the memory allotted to virtual machines with the `KUBERNETES_MEMORY` environment variable.
Just set it to the number of megabytes you would like the machines to have. For example:
You can control the memory allotted to virtual machines with the
`KUBERNETES_MEMORY` environment variable. Just set it to the number of megabytes
you would like the machines to have. For example:
```sh
```shell
export KUBERNETES_MEMORY=2048
```
If you need more granular control, you can set the amount of memory for the master and nodes independently. For example:
If you need more granular control, you can set the amount of memory for the
master and nodes independently. For example:
```sh
```shell
export KUBERNETES_MASTER_MEMORY=1536
export KUBERNETES_NODE_MEMORY=2048
```
#### I want to set proxy settings for my Kubernetes cluster boot strapping!
If you are behind a proxy, you need to install the Vagrant proxy plugin and set
the proxy settings:
```shell
vagrant plugin install vagrant-proxyconf
export KUBERNETES_HTTP_PROXY=http://username:password@proxyaddr:proxyport
export KUBERNETES_HTTPS_PROXY=https://username:password@proxyaddr:proxyport
```
You can also specify addresses that bypass the proxy, for example:
```shell
export KUBERNETES_NO_PROXY=127.0.0.1
```
If you are using sudo to make Kubernetes build, use the `-E` flag to pass in the
environment variables. For example, if running `make quick-release`, use:
```shell
sudo -E make quick-release
```
#### I ran vagrant suspend and nothing works!
`vagrant suspend` seems to mess up the network. It's not supported at this time.
`vagrant suspend` seems to mess up the network. It's not supported at this time.
#### I want vagrant to sync folders via nfs!
You can ensure that vagrant uses nfs to sync folders with virtual machines by
setting the KUBERNETES_VAGRANT_USE_NFS environment variable to 'true'. nfs is
faster than virtualbox or vmware's 'shared folders' and does not require guest
additions. See the
[vagrant docs](http://docs.vagrantup.com/v2/synced-folders/nfs.html) for details
on configuring nfs on the host. This setting will have no effect on the libvirt
provider, which uses nfs by default. For example:
```shell
export KUBERNETES_VAGRANT_USE_NFS=true
```
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/developer-guides/vagrant.md?pixel)]()