Skip to content

Commit 2e45d90

Browse files
slackslack
committed
chore(vagrant): document vagrant quickstart
1 parent af41a7d commit 2e45d90

3 files changed

Lines changed: 234 additions & 17 deletions

File tree

‎src/quickstart/provider/vagrant/boot.md‎

Lines changed: 141 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,143 @@
1-
export KUBERNETES_PROVIDER=vagrant
1+
# Booting Kubernetes Using Vagrant
22

3-
kubectl should be working
3+
This guide will walk you through the process of installing a small development
4+
Kubernetes cluster on your local machine.
45

5-
[next install workflow](install-vagrant.md)
6+
## Pre-requisites
7+
8+
1. Install latest version >= 1.7.4 of vagrant from http://www.vagrantup.com/downloads.html
9+
2. Install one of:
10+
1. The latest version of [Virtual Box](https://www.virtualbox.org/wiki/Downloads)
11+
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)
12+
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)
13+
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/)
14+
3. At least 4GB of RAM for the virtual machines.
15+
16+
## Download and Unpack Kubernetes
17+
18+
First, make a directory to hold the Kubernetes release files:
19+
20+
```
21+
$ mkdir my-first-cluster
22+
$ cd my-first-cluster
23+
```
24+
25+
Download Kubernetes release v1.2.4, and extract the archive on your machine.
26+
27+
This archive has everything that you need to launch Kubernetes. It weighs in around 500MB, so it may take some time to download:
28+
29+
```
30+
$ curl -sSL https://storage.googleapis.com/kubernetes-release/release/v1.2.4/kubernetes.tar.gz -O
31+
$ tar -xvzf kubernetes.tar.gz
32+
$ cd kubernetes
33+
$ ls
34+
LICENSES README.md Vagrantfile cluster/ contrib/ docs/ examples/ platforms/ server/ third_party/ version
35+
```
36+
37+
## Configure the Kubernetes Environment
38+
39+
Before calling the Kubernetes setup scripts, we need to change a few defaults so that Deis Workflow works best. Type
40+
each of these commands into your terminal application before calling `kube-up.sh`.
41+
42+
First, enable insecure registry support for Docker and use Vagrant as the provider:
43+
```
44+
$ export KUBE_ENABLE_INSECURE_REGISTRY=true
45+
$ export KUBERNETES_PROVIDER=vagrant
46+
```
47+
48+
For evaluation, we find that the worker nodes need a bit more memory than the default 1GB. We will allocate 1.5GB for
49+
the master node and 4GB for the worker node:
50+
51+
```
52+
export KUBERNETES_MASTER_MEMORY=1536
53+
export KUBERNETES_NODE_MEMORY=4096
54+
```
55+
56+
Double check the configured environment variables:
57+
58+
```
59+
$ env | grep KUBE
60+
KUBE_ENABLE_INSECURE_REGISTRY=true
61+
KUBERNETES_PROVIDER=vagrant
62+
KUBERNETES_NODE_MEMORY=4096
63+
KUBERNETES_MASTER_MEMORY=1536
64+
```
65+
66+
## Boot Your First Cluster
67+
68+
We are now ready to boot our first Kubernetes cluster on AWS!
69+
70+
Since this script does a **lot** of stuff, we'll break it into sections.
71+
72+
```
73+
kubernetes $ ./cluster/kube-up.sh
74+
... Starting cluster using provider: vagrant
75+
... calling verify-prereqs
76+
... calling kube-up
77+
Bringing machine 'master' up with 'virtualbox' provider...
78+
Bringing machine 'node-1' up with 'virtualbox' provider...
79+
==> master: Box 'kube-fedora23' could not be found. Attempting to find and install...
80+
81+
...REDACTED...
82+
83+
```
84+
85+
Two machines have been created via vagrant, `master` and `node-1`. The step downloads a load of packages and sets up
86+
Kubernetes so it can take some time.
87+
88+
```
89+
cluster "vagrant" set.
90+
user "vagrant" set.
91+
context "vagrant" set.
92+
switched to context "vagrant".
93+
user "vagrant-basic-auth" set.
94+
Wrote config for vagrant to /Users/jhansen/.kube/config
95+
Each machine instance has been created/updated.
96+
Now waiting for the Salt provisioning process to complete on each machine.
97+
This can take some time based on your network, disk, and cpu speed.
98+
It is possible for an error to occur during Salt provision of cluster and this could loop forever.
99+
Validating master
100+
Validating node-1
101+
```
102+
103+
Now that the master is up and ready, `kube-up.sh` automatically configures `kubectl` on your machine with appropriate
104+
authentication and endpoint information.
105+
106+
```
107+
Kubernetes cluster is running.
108+
109+
The master is running at:
110+
111+
https://10.245.1.2
112+
113+
Administer and visualize its resources using Cockpit:
114+
115+
https://10.245.1.2:9090
116+
117+
For more information on Cockpit, visit http://cockpit-project.org
118+
119+
The user name and password to use is located in /Users/jhansen/.kube/config
120+
121+
... calling validate-cluster
122+
Found 1 node(s).
123+
NAME STATUS AGE
124+
kubernetes-node-1 Ready 1m
125+
Flag --api-version has been deprecated, flag is no longer respected and will be deleted in the next release
126+
Validate output:
127+
NAME STATUS MESSAGE ERROR
128+
controller-manager Healthy ok
129+
scheduler Healthy ok
130+
etcd-1 Healthy {"health": "true"}
131+
etcd-0 Healthy {"health": "true"}
132+
Cluster validation succeeded
133+
Done, listing cluster services:
134+
135+
Kubernetes master is running at https://10.245.1.2
136+
Heapster is running at https://10.245.1.2/api/v1/proxy/namespaces/kube-system/services/heapster
137+
KubeDNS is running at https://10.245.1.2/api/v1/proxy/namespaces/kube-system/services/kube-dns
138+
kubernetes-dashboard is running at https://10.245.1.2/api/v1/proxy/namespaces/kube-system/services/kubernetes-dashboard
139+
Grafana is running at https://10.245.1.2/api/v1/proxy/namespaces/kube-system/services/monitoring-grafana
140+
InfluxDB is running at https://10.245.1.2/api/v1/proxy/namespaces/kube-system/services/monitoring-influxdb
141+
```
142+
143+
You are now ready to [install Deis Workflow](install-vagrant.md)

‎src/quickstart/provider/vagrant/dns.md‎

Lines changed: 73 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,76 @@
1-
panic
1+
## Find Your Load Balancer Address
22

3-
exit with `DEIS_HOSTNAME` set
3+
During installation, Deis Workflow specifies that Kubernetes should provision and attach a load balancer to the router
4+
component. The router component is responsible for routing HTTP and HTTPS requests from outside the cluster to
5+
applications that are managed by Deis Worfklow. In cloud environments Kubernetes provisions and attaches a load balancer
6+
for you. Since we are running in a local environment, we need to do a little bit of extra work to manage routes into the
7+
Kubernetes overlay network.
8+
9+
First, determine the ip address allocated to your worker node.
10+
11+
```
12+
$ kubectl get nodes
13+
NAME STATUS AGE
14+
kubernetes-node-1 Ready 4h
15+
$ kubectl describe node kubernetes-node-1 | egrep Addresses
16+
Addresses: 10.245.1.3,10.245.1.3
17+
```
18+
19+
Here, our node address is `10.254.1.3`.
20+
21+
Next, determine the ip address of the Deis Workflow router component:
22+
23+
```
24+
$ kubectl --namespace=deis describe service deis-router | egrep IP
25+
IP: 10.247.114.249
26+
```
27+
28+
The service address for the router is `10.247.114.249`.
29+
30+
Last, we need to inform your machine how to reach the service address:
31+
32+
```
33+
$ sudo route add 10.247.114.249 10.245.1.3
34+
Password:
35+
add host 10.247.114.249: gateway 10.245.1.3
36+
```
37+
38+
This tells your machine that the service address `10.247.114.249` can be reached by forwarding the packets to the worker
39+
node found at `10.245.1.3`.
40+
41+
**Remember when you are finished experimenting, you should remove the route so you aren't confused later:**
42+
43+
```
44+
$ sudo route delete 10.247.114.249 10.245.1.3
45+
delete host 10.247.114.249: gateway 10.245.1.3
46+
```
47+
48+
## Prepare the Hostname
49+
50+
Now that you have the ip address of your service and routing configured we can use the `nip.io` DNS service to route
51+
arbitrary hostnames to the Deis Workflow edge router. This lets us point the Workflow CLI at your cluster without having
52+
to either use your own domain or update DNS!
53+
54+
To verify the Workflow API server and nip.io, construct your hostname by taking the ip address for your load balancer
55+
and adding `nip.io`. For our example above, the address would be: `10.247.114.249`.
56+
57+
Nip answers with the ip address no matter the hostname:
58+
```
59+
$ host 10.247.114.249.nip.io
60+
10.247.114.249.nip.io has address 10.247.114.249
61+
$ host something-random.10.247.114.249.nip.io
62+
something-random.10.247.114.249.nip.io has address 10.247.114.249
63+
```
64+
65+
By default, any HTTP traffic for the hostname `deis` will be sent to the Workflow API service. To test that everything is connected properly you may validate connectivity using `curl`:
66+
67+
```
68+
$ curl http://deis.10.247.114.249.nip.io/v2/ && echo
69+
{"detail":"Authentication credentials were not provided."}
70+
```
71+
72+
You should see a failed request because we provided no credentials to the API server.
73+
74+
Remember the hostname, we will use it in the next step.
475

576
[next: deploy your first app](../../deploy-an-app.md)

‎src/quickstart/provider/vagrant/install-vagrant.md‎

Lines changed: 20 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
# Installing Deis Workflow
1+
# Installing Deis Workflow on Vagrant
22

33
## Check Your Setup
44

5-
First check that the `helm` command is available and the version is 0.6 or newer.
5+
First check that the `helm` command is available and the version is 0.7 or newer.
66

77
```
88
$ helmc --version
@@ -17,21 +17,13 @@ $ helmc target
1717
Kubernetes master is running at https://10.245.1.2
1818
Heapster is running at https://10.245.1.2/api/v1/proxy/namespaces/kube-system/services/heapster
1919
KubeDNS is running at https://10.245.1.2/api/v1/proxy/namespaces/kube-system/services/kube-dns
20-
KubeUI is running at https://10.245.1.2/api/v1/proxy/namespaces/kube-system/services/kube-ui
20+
kubernetes-dashboard is running at https://10.245.1.2/api/v1/proxy/namespaces/kube-system/services/kubernetes-dashboard
2121
Grafana is running at https://10.245.1.2/api/v1/proxy/namespaces/kube-system/services/monitoring-grafana
2222
InfluxDB is running at https://10.245.1.2/api/v1/proxy/namespaces/kube-system/services/monitoring-influxdb
2323
```
2424

2525
If you see a list of targets like the one above, `helm` can communicate with the Kubernetes master.
2626

27-
Deis Workflow requires Kubernetes 1.2 or higher. You can test that by running:
28-
29-
```
30-
$ kubectl version
31-
Client Version: version.Info{Major:"1", Minor:"2", GitVersion:"v1.2.3", GitCommit:"882d296a99218da8f6b2a340eb0e81c69e66ecc7", GitTreeState:"clean"}
32-
Server Version: version.Info{Major:"1", Minor:"2", GitVersion:"v1.2.3", GitCommit:"882d296a99218da8f6b2a340eb0e81c69e66ecc7", GitTreeState:"clean"}
33-
```
34-
3527
## Add the Deis Chart Repository
3628

3729
The [Deis Chart Repository](https://github.com/deis/charts) contains everything you
@@ -68,6 +60,22 @@ If you would like `kubectl` to automatically update as the pod states change, ru
6860
$ kubectl get pods --namespace=deis -w
6961
```
7062

63+
Depending on the order in which the Workflow components start, you may see a few components restart. This is common during the installation process, if a component's dependencies are not yet available the component will exit and Kubernetes will automatically restart the containers.
64+
65+
```
66+
$ kubectl --namespace=deis get pods
67+
NAME READY STATUS RESTARTS AGE
68+
deis-builder-lrb54 1/1 Running 1 2m
69+
deis-controller-lto6v 1/1 Running 1 2m
70+
deis-database-2jh3w 1/1 Running 0 2m
71+
deis-logger-fluentd-9hm06 1/1 Running 0 2m
72+
deis-logger-yxhwk 1/1 Running 0 2m
73+
deis-minio-p384q 1/1 Running 0 2m
74+
deis-registry-l9l6g 1/1 Running 2 2m
75+
deis-router-yc3rb 1/1 Running 0 2m
76+
deis-workflow-manager-fw5vq 1/1 Running 0 2m
77+
```
78+
7179
Once you see all of the pods in the `READY` state, Deis Workflow is up and running!
7280

73-
Next, [configure dns](dns.md) so you can register your first user.
81+
Next, [configure dns](dns.md) so you can register your first user and deploy an application.

0 commit comments

Comments
 (0)