Skip to content
Snippets Groups Projects

Replacement MR for defunct MR13

Merged Replacement MR for defunct MR13
noe.nieto/ldh_developer:master into master
Merged Noe Nieto requested to merge noe.nieto/ldh_developer:master into master
Viewing commit 9f3344fb
Prev Next
Show latest version
3 files
+ 85
− 83
Compare changes
  • Side-by-side
  • Inline
Files
3
shipyard/README.md → box/README.md
+ 82
− 60
# The shipyard
# The box command
The `shipyard` is a small wrapper around vagrant and libvirt that allows you to manage virtual machines easily. For most commands you only need to provide the hostname.
The Shipwright's `box` command is a small wrapper around Vagrant that allows you to easily manage boxes eithar as virtual machines with `libvirt` or droplets with Digital Ocean. For most commands you only need to provide the hostname.
## How it works
Shipyard uses `~/.config/ldh_developer/shipyard` as configuration directory.
Every folder inside the `shipyard` folder represents a vagrant box, so for a box with hostname `floyd` the `$VAGRANT_HOME` directory is `~/.config/lds_developer/shipyard/floyd`:
The Shipwright's `box` command uses `~/.config/ldh_developer/box/` as configuration directory.
Every folder inside the `box` folder contains the necessary configuration files; so for a box with hostname `floyd` the `$VAGRANT_HOME` directory is `~/.config/lds_developer/box/floyd`:
```bash
ls -l ~/.config/ldh_developer/shipyard/
ls -l ~/.config/ldh_developer/box/
total 8
drwxr-xr-x 3 nnieto nnieto 4.0K Nov 27 21:46 floyd/
```
The `floyd` folder contains two files (`Vagrantfile` and `shim.yml`) and the vagrant hidden folder(`.vagrant`).
Once `shipyard` creates a box, you can manage it with the libvirt and vagrant tools of your choice. Recommended tools are:
The `floyd` folder contains two files (`Vagrantfile` and `shim.yml`) and the vagrant hidden folder(`.vagrant`). This directory is also used to store more configuration files or support files if needed (i.e. Ansible).
Once `box` command finishes building the box, you can manage it with the tools of your choice. Recommended tools are:
- [GNOME Vagrant Indicator](https://github.com/fffilo/gnome-vagrant-indicator)
- virt-manager (apt install virt-manager)
## Commands
`shipyard` supports these commands:
`box` supports these commands:
- `status`: report the status of the virtual machines created/managed by `shipyard`.
- `create`: create a new VM. You only need to provide the hostname.
- `up`: starts a VM.
- `halt`: stops a VM.
- `destroy`: destroys the VM
- `ssh`: opens a ssh session directly to the VM as `vagrant` user.
- `playbook`: provisions a VM with an ansible playbook.
- `which`: prints the configuration directory path of a VM.
- `open`: opens the configuration directory of a VM with the current file manager (nautilus, dolphin, etc.)
- `status`: report the status of the boxes created/managed by `shipwright`.
- `create`: create a new box. You only need to provide the hostname.
- `up`: starts a box.
- `halt`: stops a box.
- `destroy`: destroys the box
- `ssh`: opens a ssh session directly to the box as `vagrant` user.
- `playbook`: provisions a box with an ansible playbook.
- `which`: prints the configuration directory path of a box.
- `open`: opens the configuration directory of a box with the current file manager (nautilus, dolphin, etc.)
### The `status` command
Prints a summary of the state of all VM's managed by `shipyard`. Example:
Prints a summary of the state of all the boxes managed by `shipwright`. Example:
```
$ shipyard status
$ shipwright box status
hostname State IP Address
nina running 192.168.121.185
pinta shutoff <N/A>
stmaria running 192.168.121.178
Total 3 machine(s)
Total 3 box(es)
$
```
### The `create` command
This command creates a new VM. You only need to provide the hostname. But you can specify the ram size and the number of cpus.
This command creates a new box. You only need to provide the hostname. But you can also specify the ram size and the number of cpus.
The following example creates a VM with the hostname `usoland`. The default values for ram size is 512 MB, and 1 CPU.
The following example creates a box with the hostname `usoland`. The default values are libvirt as provider, ram size is 512 MB, and 1 CPU.
```
$ shipyard create usoland
$ shipwright box create usoland
Bringing machine 'usoland' up with 'libvirt' provider...
==> usoland: Checking if box 'debian/stretch64' is up to date...
[...]
@@ -67,10 +66,11 @@ Bringing machine 'usoland' up with 'libvirt' provider...
[...]
```
The following example creates a VM with the hostname `usoland` with 4 cpus and 1GB of ram:
The following example creates a box with the hostname `usoland` with 4 cpus and 1GB of ram:
```
$ shipyard create usoland --cpus 4 --ram 1024
$ shipwright box create usoland --cpus 4 --ram 1024
Bringing machine 'usoland' up with 'libvirt' provider...
[...]
==> usoland: -- Cpus: 4
@@ -84,43 +84,65 @@ Bringing machine 'usoland' up with 'libvirt' provider...
$
```
**Note**: Vagrant/libvirt need root access to create and modify networks on the machine. Vagrant will try to use sudo and will request your passowrd.
**Note**: Vagrant/libvirt needs root access to create and modify networks on the box. Vagrant will try to use sudo and will request your passowrd.
Finally the following example creates a box using Digital Ocean as provider.
```
$ shipwright box create starblade --provider digital_ocean --token 2f17c...808c50ae9
Creating ssh key required by Vagrant's Digital Ocean plugin ...
Bringing machine 'starblade' up with 'digital_ocean' provider...
==> starblade: Using existing SSH key: Vagrant
==> starblade: Creating a new droplet...
==> starblade: Assigned IP address: 104.248.176.67
[...]
Bringing machine 'starblade' up with 'digital_ocean' provider...
==> starblade: Creating new SSH key: Vagrant...
==> starblade: Creating a new droplet...
==> starblade: Assigned IP address: 178.128.79.235
[...]
```
**Known issue**: The create command freezes on this message: `==> starblade: Assigned IP address: ...` for some minutes before continuing to destroy the droplet. If you hit Ctrl-C shortly after the `.. Assigned IP adress [..]` messages, the droplet stays alive.
**default provider**: The default provider is `libvirt`, you need to specify `--provider digital_ocean` and `--token` on the command line to spin the droplet in Digital Ocean. If you don't have a token yet, you ca generate one on _Manage_ / _API_ section in your DO's control panel.
### The `up`, `halt` and `restart` commands
Use these commands to start and shutdown, or restart the VM's. As an example, the previous section we created one vm. If we check the status we find that it's running.
Use these commands to start, shutdown, or restart a box. As an example, the previous section we created one. If we check the status we find that it's running.
```
$ shipyard status
```bash
$ shipwright box status
hostname State IP Address
usoland running 192.168.121.57
Total 1 machine(s)
Total 1 box(es)
$
```
Now, let's use the `halt` command.
```
shipyard halt usoland
```bash
$ shipwright box halt usoland
==> usoland: Halting domain...
$
```
We can see that the VM status is `shutoff`:
```
$ shipyard status
We can see that the box status is `shutoff`:
```bash
$ shipwright box status
hostname State IP Address
usoland shutoff <N/A>
Total 1 machine(s)
Total 1 box(es)
$
```
We use the `up` command to start the VM again.
We use the `up` command to start the box again.
```
$ shipyard up usoland
```bash
$ shipwright box up usoland
Bringing machine 'usoland' up with 'libvirt' provider...
==> usoland: Checking if box 'debian/stretch64' is up to date...
==> usoland: Starting domain.
@@ -135,13 +157,13 @@ Bringing machine 'usoland' up with 'libvirt' provider...
$
```
Now `status` shows that the vm is running.
Now `status` shows that the box is running.
```
$ shipyard status
$ box status
hostname State IP Address
usoland running 192.168.121.57
Total 1 machine(s)
Total 1 box(es)
$
```
@@ -149,7 +171,7 @@ $
Now, `restart` is very straightforward.
```
$ shipyard restart starblade
$ box restart starblade
==> starblade: Halting domain...
Bringing machine 'starblade' up with 'libvirt' provider...
==> starblade: Checking if box 'debian/stretch64' is up to date...
@@ -168,10 +190,10 @@ $
### The `ssh` command
The ssh command opens an ssh to the VM.
The ssh command opens an ssh to the box.
```bash
$ shipyard ssh usoland
$ box ssh usoland
Linux usoland 4.9.0-8-amd64 #1 SMP Debian 4.9.130-2 (2018-10-27) x86_64
The programs included with the Debian GNU/Linux system are free software;
@@ -189,35 +211,35 @@ $
### The `which` command
The `which` command prints the full path to the `$VAGRANT_HOME` directory of the VM.
The `which` command prints the full path to the `$VAGRANT_HOME` directory of the box.
```
$ shipyard which usoland
/home/nnieto/.config/ldh_developer/shipyard/usoland
$ box which usoland
/home/nnieto/.config/ldh_developer/box/usoland
$
```
### The `open` command
This command opens a new window of your file manager pointing to the `$VAGRANT_HOME` of the VM.
This command opens a new window of your file manager pointing to the `$VAGRANT_HOME` of the box.
```bash
./shipyard open --hostname=starone0
shipwright open open --hostname=starone0
[... nautilis shows up ...]
```
### The `ansible` command
This command allows you to run an ansible playbook against one of the VMs. For example: I have two VM's managed by `shipyard`:
This command allows you to run an ansible playbook against one of the boxess. For example: I have two oxes managed by `shipwright`:
```
./shipyard status
```bash
$ shipwright box status
hostname State IP Address
usoland shutoff <N/A>
going-merry running 192.168.121.89
Total 2 machine(s)
Total 2 box(es)
```
Let's install rust on`going-merry`. The playbook looks like this:
@@ -235,7 +257,7 @@ Let's install rust on`going-merry`. The playbook looks like this:
Let's save it as `rust.yml` and run the playbook against `going-merry`:
```
./shipyard playbook going-merry rust.yaml
shipwright playbook going-merry rust.yaml
PLAY [Rust Playbook] *************************************************************************************
@@ -246,14 +268,14 @@ TASK [Install Rust] ************************************************************
changed: [going-merry]
PLAY RECAP ***********************************************************************************************
going-merry : ok=2 changed=1 unreachable=0 failed=0
going-merry : ok=2 changed=1 unreachable=0 failed=0
```
Now I can use `rustc` on the VM:
Now I can use `rustc` inside the box:
```bash
./shipyard ssh going-merry
shipwright ssh going-merry
Linux going-merry 4.9.0-8-amd64 #1 SMP Debian 4.9.130-2 (2018-10-27) x86_64
The programs included with the Debian GNU/Linux system are free software;