getting_started.md 5.06 KB
Newer Older
1
2
3
4
# Quick Start Guide

This document will show you how to get up and running with this multi node
[Vagrant](https://www.vagrantup.com/ "Vagrant") environment. If you are not
Cogline.v3's avatar
Cogline.v3 committed
5
familiar with Vagrant, then you should read the [Vagrant Documentation](https://www.vagrantup.com/docs/index.html "Vagrant Documentation") too.
6
7
8
9


## Requirements

Cogline.v3's avatar
Cogline.v3 committed
10
This setup was tested under Windows 10 with the following components: 
11

12
* [VirtualBox = 6.0.14](https://www.virtualbox.org/)
Cogline.v3's avatar
Cogline.v3 committed
13
* [Vagrant = 2.2.6](https://www.vagrantup.com/)
14
* [Ansible = 2.8.2](http://docs.ansible.com/ansible/) within [Cygwin 2.10.0](https://www.cygwin.com/), see [Jeff Geerling's](https://www.jeffgeerling.com/) Blog to [Running Ansible within Windows](http://www.jeffgeerling.com/blog/running-ansible-within-windows)
15

16
and under Ubuntu 16.04 LTS (Xenial Xerus) and Ubuntu 18.04 LTS (Bionic Beaver) with:
Cogline.v3's avatar
Cogline.v3 committed
17

18
* [VirtualBox = 6.0.10](https://www.virtualbox.org/)
Cogline.v3's avatar
Cogline.v3 committed
19
* [libvirt = 4.0.0](https://libvirt.org/index.html)
Cogline.v3's avatar
Cogline.v3 committed
20
* [Vagrant = 2.2.6](https://www.vagrantup.com/)
21
* [Ansible = 2.9.0](http://docs.ansible.com/ansible/)
Cogline.v3's avatar
Cogline.v3 committed
22

Cogline.v3's avatar
Cogline.v3 committed
23
24
25
preinstalled.


26
!!! Note
Cogline.v3's avatar
Cogline.v3 committed
27
    This document does not explain how to install these components. You have to do it yourself by reading the installation guides of these components.
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


## Get the Vagrant Environment

For the next steps open a bash (under Windows a cygwin bash) on the virtual host system.

### Download Vagrant box configuration

```bash
git clone https://gitlab.com/cogline_vagrant/ansible-development.git
cd ansible-development
```

### Get Ansible roles for provisioning

Now install Ansible roles defined under `provisioning/requirements.yml`:

```bash
ansible-galaxy install -r provisioning/requirements.yml -p provisioning/roles
```

Cogline.v3's avatar
Cogline.v3 committed
49
### Install vagrant plugins
50

Cogline.v3's avatar
Cogline.v3 committed
51
Before using this Vagrant environment, you still need to install the following plugins.
52
53
54

```bash
vagrant plugin install vagrant-vbguest
Cogline.v3's avatar
Cogline.v3 committed
55
56
57
vagrant plugin install vagrant-hostmanager
```

58
59
If you use Vagrant with libvirt under Linux, you also need to install the
following plugins
Cogline.v3's avatar
Cogline.v3 committed
60
61
62
```bash
vagrant plugin install vagrant-libvirt
vagrant plugin install vagrant-mutate
63
```
64
65
66
67
and the NFS kernel server:
```bash
# on Debian/Ubuntu systems
sudo apt install -y nfs-kernel-server
68
69
# on Enterprise Linux (CentOS/RedHat)
sudo yum -y install nfs-utils
70
```
71

72
73
74
75
## Define Ansible Client(s)

Your Ansible development environment requires at least one virtual machine 
(Vagrant box) with a [supported operating system](/#supported-operating-systems "Supported Operating Systemѕ").
76
Open the file `boxes.yml` and enter your Ansible clients here, e.g.:
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

!!! Note "boxes.yml"
    ```yaml
    ---
    - image: generic/centos8
      start: true
      hostname: el8-node
      vbox_name: 'EL8 - Node'
      nodes: 3
    - image: generic/debian10
      start: true
      hostname: debian-buster-node
      vbox_name: 'Debian (Buster) - Node'
      nodes: 1

    ```

This will start three nodes with CentOS 8 and one node with Debian Buster. See
section "[Define Vagrant Boxes](/vagrantfile/#define-vagrant-boxes)" for more
96
details on configuring the `boxes.yml` file.
97
98


99
100
## Initial Provisioning

101
The next step will start all Ansible Clients and the Ansible
102
103
104
management node. While starting the first time Vagrant will be run any
configured provisioners against the running managed machines.

105
106
107
108
109
110
111
112
!!! Note "This will take a few minutes"
    The first time this step takes a while. All required Vagrant Boxes will be
    downloaded from the [Vagrant Cloud](https://app.vagrantup.com/boxes/search
    "Vagrant Cloud"). Depending on the speed of your internet connection, this
    will take a few minutes. Subsequently, the individual systems are started
    and provisioned in sequence. Then the environment is ready for the
    development and testing of new Ansible playbooks and roles.

113
### Provisioning with provider VirtualBox
114
115

The Vagrant environment can be started with the provider VirtualBox as follows.
116

117
118
119
120
```bash
vagrant up
```

121
### Provisioning with provider libvirt
122

Cogline.v3's avatar
Cogline.v3 committed
123
124
If you want to use vagrant with libvirt instead of VirtualBox, use
```bash
125
VAGRANT_DEFAULT_PROVIDER=libvirt vagrant up --no-parallel
Cogline.v3's avatar
Cogline.v3 committed
126
127
```

128
129
130
131
132
!!! attention "libvirt: Switch off the parallel installation the first time"
    The provider libvirt usually performs the installation of virtual machines
    in parallel. It happens that Ansible Provisioner is running on the master
    node before all Ansible clients are up and running. Therefore, the Ansible
    Provisioner sometimes can not reach all clients through SSH from the master
133
    node, and Ansible fails for the affected clients. That's why when starting
134
135
136
137
138
139
    the environment for the first time, the parallel installation should be
    suppressed using the vagrant option `--no-parallel`.
    
    If you have not turned off the parallel installation and the Ansible
    provisioner fails, then the provisioning on the master node can be
    re-executed with the following command after all clients are up and running.
140
141
142
143

    ```bash
    VAGRANT_DEFAULT_PROVIDER=libvirt vagrant provision master
    ```