Skip to content

Commit

Permalink
docs: Add docs/getting-started.md
Browse files Browse the repository at this point in the history 
Formerly a part of the main README the getting started guide is now
separate.

Change-Id: I7349f944aeb9cd086a49404130d857ce168d3ee2
Signed-off-by: Fabian Deutsch <[email protected]>
  • Loading branch information
@fabiand
fabiand committed Dec 16, 2016
1 parent 5ce1fd3 commit 1034843
Show file tree
Hide file tree
Showing 2 changed files with 202 additions and 150 deletions.
161 changes: 11 additions & 150 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,14 @@

KubeVirt is a virtual machine management architecture built around Kubernetes.


## Getting Started

This document contains some more background below.
If you want to get started right away, make sure to continue with our
[Getting Started Guide](docs/getting-started.md).


## Technical Overview

Kubernetes allows for extensions to its architecture in the form of 3rd party
Expand All @@ -13,7 +21,9 @@ This project provides a Vagrant setup with the requisite components already
installed. To boot a vanilla kubernetes environment as base for kubevirt,
simply type `vagrant up` from the root directory of the git tree, which can be
found here:
<!-- FIXME: <place URL to public git repository here> -->

<https://github.com/kubevirt/kubevirt>

Once the Vagrant provisioning script has completed, run `./cluster/sync.sh` to
build and deploy KubeVirt specific components to the Vagrant nodes.

Expand Down Expand Up @@ -55,152 +65,3 @@ therefore required. For best results, use this path:
need to be run separately.
* `cluster/quickcheck.sh`: This script will run a series of tests to ensure
the system is set up correctly.

## Example

```
$ ./cluster/kubectl.sh create -f cluster/vm.json
vm "testvm" created
$ ./cluster/kubectl.sh get pods
NAME READY STATUS RESTARTS AGE
haproxy 1/1 Running 4 10h
virt-api 1/1 Running 1 10h
virt-controller 1/1 Running 1 10h
virt-handler-z90mp 1/1 Running 1 10h
virt-launcher-testvm9q7es 1/1 Running 0 10s
$ ./cluster/kubectl.sh get vms
NAME LABELS DATA
testvm kubevirt.io/nodeName=master {"apiVersion":"kubevirt.io/v1alpha1","kind":"VM","...
$ ./cluster/kubectl.sh get vms -o json
{
"kind": "List",
"apiVersion": "v1",
"metadata": {},
"items": [
{
"apiVersion": "kubevirt.io/v1alpha1",
"kind": "VM",
"metadata": {
"creationTimestamp": "2016-12-09T17:54:52Z",
"labels": {
"kubevirt.io/nodeName": "master"
},
"name": "testvm",
"namespace": "default",
"resourceVersion": "102534",
"selfLink": "/apis/kubevirt.io/v1alpha1/namespaces/default/vms/testvm",
"uid": "7e89280a-be62-11e6-a69f-525400efd09f"
},
"spec": {
...
```

## Cockpit

Cockpit is exposed on <http://192.168.200.2:9090>
The default login is `root:vagrant`

It can be used to verify the running state of components within the cluster.
More information can be found on that project's site:

http://cockpit-project.org/guide/latest/feature-kubernetes.html

### Setup

First make sure you have [govendor](https://github.com/kardianos/govendor),
`j2cli` and `libvirt-devel` installed.

To install govendor in your `$GOPATH/bin` simply run

```bash
go get -u github.com/kardianos/govendor
```

If you don't have the `$GOPATH/bin` folder on your path, do

```bash
export PATH=$PATH:$GOPATH/bin
```

`j2cli` can be installed with

```bash
sudo pip install j2cli
```

On Fedora `libvirt-devel` can be installed with

```bash
sudo dnf install libvirt-devel
```

### Building

First clone the project into your `$GOPATH`:

```bash
git clone https://github.com/kubevirt/kubevirt.git $GOPATH/src/kubevirt.io/kubevirt
cd $GOPATH/src/kubevirt.io/kubevirt
```

To build the whole project, type

```bash
make
```

To build all docker images type

```bash
make docker
```

It is also possible to target only specific modules. For instance to build only
the `virt-controller`, type

```bash
make build WHAT=virt-controller
```

### Testing

Type

```bash
make test
```

to run all tests.

### Vagrant

Sets up a kuberentes cluster with a master and a node:

```bash
vagrant up
```

Build and deploy kubevirt:

```bash
bash cluster/sync.sh
```

Finally start a VM called `testvm`:

```bash
# this can be done from your GIT repo, no need to log into a vagrant VM
$ ./cluster/kubectl.sh create -f cluster/vm.json
```

This will start a VM on master or node with a macvtap and a tap networking
device attached.

Basic verification is possible by running

```
bash cluster/quickcheck.sh
```
191 changes: 191 additions & 0 deletions docs/getting-started.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
# Getting Started

A quick start guide to get KubeVirt up and running inside Vagrant.

**Note**: This guide was tested on Fedora 23 and Fedora 25.

**Note:** Fedora 24 is known to have a bug which affects our vagrant setup.


## Building

### Go

[Go](https://golang.org) needs to be setup to be able to compile the sources.

**Note:** Go is pretty picky about paths, thus use the suggested ones.

```bash
# If you haven't set it already, set a GOPATH
echo "export GOPATH=~/go" >> ~/.bashrc
echo "export PATH=$PATH:$GOPATH/bin" >> ~/.bashrc
source ~/.bashrc

mkdir -p ~/go

sudo dnf install golang
```


### Vagrant

[Vagrant](https://www.vagrantup.com/) is used to bring up a development and
demo environment:

```bash
sudo dnf install vagrant vagrant-libvirt
```

That's it for now with vagrant, it will be used further down.


### Build dependencies

Now we can finally get to the sources, before building KubeVirt we'll need
to install a few build requirements:

```bash
# We are interfacing with libvirt
sudo dnf install libvirt-devel

sudo dnf install python-pip
sudo pip install j2cli


cd $GOPATH
# First we setup govendor which is used to track dependencies
go get -u github.com/kardianos/govendor
```

### Sources

Now we can clone the project into your `$GOPATH`:

```bash
git clone https://github.com/kubevirt/kubevirt.git $GOPATH/src/kubevirt.io/kubevirt
cd $GOPATH/src/kubevirt.io/kubevirt
```

And finally build all required artifacts and finally launch the
Vagrant environment:

```bash
# Building and deploying kubevirt in Vagrant
vagrant up
cluster/sync.sh
```

You could also run some build steps individually:

```bash
# To build all binaries
make

# Or to build just one binary
make build WHAT=virt-controller

# To build all docker images
make docker
```

### Testing

After a succefull build you can run the testsuite using:

```bash
make test
```


## Use

Congratulationsyou are still with us and you have build KubeVirt.

Now it's time to get hands on and give it a try.

### Cockpit

Cockpit is exposed on <http://192.168.200.2:9090>
The default login is `root:vagrant`

It can be used to view the cluster and verify the running state of
components within the cluster.
More information can be found on that [project's site](http://cockpit-project.org/guide/latest/feature-kubernetes.html).

### Create a first Virtual Machine

Finally start a VM called `testvm`:

```bash
# This can be done from your GIT repo, no need to log into a vagrant VM
# You might want to watch the Cockpit Cluster topology while running these commands

# Create a VM
./cluster/kubectl.sh create -f cluster/vm.json

# Sure? Let's list all created VMs
./cluster/kubectl.sh get vms

# Enough, let's get rid of it
./cluster/kubectl.sh delete -f cluster/vm.json


# You can actually use kubelet.sh to introspect the cluster in general
./cluster/kubectl.sh get pods
```

This will start a VM on master or node with a macvtap and a tap networking
device attached.

Basic verification is possible by running

```bash
bash cluster/quickcheck.sh
```

#### Example

```bash
$ ./cluster/kubectl.sh create -f cluster/vm.json
vm "testvm" created

$ ./cluster/kubectl.sh get pods
NAME READY STATUS RESTARTS AGE
haproxy 1/1 Running 4 10h
virt-api 1/1 Running 1 10h
virt-controller 1/1 Running 1 10h
virt-handler-z90mp 1/1 Running 1 10h
virt-launcher-testvm9q7es 1/1 Running 0 10s

$ ./cluster/kubectl.sh get vms
NAME LABELS DATA
testvm kubevirt.io/nodeName=master {"apiVersion":"kubevirt.io/v1alpha1","kind":"VM","...
$ ./cluster/kubectl.sh get vms -o json
{
"kind": "List",
"apiVersion": "v1",
"metadata": {},
"items": [
{
"apiVersion": "kubevirt.io/v1alpha1",
"kind": "VM",
"metadata": {
"creationTimestamp": "2016-12-09T17:54:52Z",
"labels": {
"kubevirt.io/nodeName": "master"
},
"name": "testvm",
"namespace": "default",
"resourceVersion": "102534",
"selfLink": "/apis/kubevirt.io/v1alpha1/namespaces/default/vms/testvm",
"uid": "7e89280a-be62-11e6-a69f-525400efd09f"
},
"spec": {
...
```

0 comments on commit 1034843

Please sign in to comment.