Commit 9f3344fb authored by Noe Nieto's avatar Noe Nieto 💬

Rename vm to box on message strings and comments; update and rework docs with...

Rename vm to box on message strings and comments;  update and rework docs with new  names. Related to !13 and
parent d8cfd102
# The box command
The `box` command is a small wrapper around Vagrant that allows you to manage virtual machines easily. Currently the supported providers are libvirt and Digital Ocean. 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
The `box` command uses `~/.config/ldh_developer/box/` as configuration directory.
The Shipwright's `box` command uses `~/.config/ldh_developer/box/` as configuration directory.
Every folder inside the `box` folder represents a box, so for a box with hostname `floyd` the `$VAGRANT_HOME` directory is `~/.config/lds_developer/box/floyd`:
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/box/
......@@ -14,9 +14,9 @@ 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`).
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` creates a box, you can manage it with the libvirt, digital ocean and vagrant tools of your choice. Recommended tools are:
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)
......@@ -25,38 +25,38 @@ Once `box` creates a box, you can manage it with the libvirt, digital ocean and
`box` supports these commands:
- `status`: report the status of the virtual machines created/managed by `box`.
- `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 `box`. Example:
Prints a summary of the state of all the boxes managed by `shipwright`. Example:
```
$ box 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.
```
$ box create usoland
$ shipwright box create usoland
Bringing machine 'usoland' up with 'libvirt' provider...
==> usoland: Checking if box 'debian/stretch64' is up to date...
[...]
......@@ -66,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:
```
$ box create usoland --cpus 4 --ram 1024
$ shipwright box create usoland --cpus 4 --ram 1024
Bringing machine 'usoland' up with 'libvirt' provider...
[...]
==> usoland: -- Cpus: 4
......@@ -83,12 +84,12 @@ Bringing machine 'usoland' up with 'libvirt' provider...
$
```
**Note**: Vagrant/libvirt needs 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 vm create starblade --provider digital_ocean --token 2f17c...808c50ae9
$ 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...
......@@ -105,42 +106,43 @@ Bringing machine 'starblade' up with 'digital_ocean' provider...
**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 machine 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.
**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, 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.
```
$ box 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.
```
box halt usoland
```bash
$ shipwright box halt usoland
==> usoland: Halting domain...
$
```
We can see that the VM status is `shutoff`:
```
$ box 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.
```
$ box 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.
......@@ -155,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.
```
$ box status
hostname State IP Address
usoland running 192.168.121.57
Total 1 machine(s)
Total 1 box(es)
$
```
......@@ -188,7 +190,7 @@ $
### The `ssh` command
The ssh command opens an ssh to the VM.
The ssh command opens an ssh to the box.
```bash
$ box ssh usoland
......@@ -209,7 +211,7 @@ $
### 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.
```
$ box which usoland
......@@ -220,24 +222,24 @@ $
### 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
./box 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 `box`:
This command allows you to run an ansible playbook against one of the boxess. For example: I have two oxes managed by `shipwright`:
```
./box 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:
......@@ -255,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`:
```
./box playbook going-merry rust.yaml
shipwright playbook going-merry rust.yaml
PLAY [Rust Playbook] *************************************************************************************
......@@ -270,10 +272,10 @@ going-merry : ok=2 changed=1 unreachable=0 failed=
```
Now I can use `rustc` on the VM:
Now I can use `rustc` inside the box:
```bash
./box 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;
......
......@@ -55,7 +55,7 @@ def only_if_box_exist(func):
if vagrant_wd.exists():
func(*args, **kwargs)
else:
print("Error: no vm managed by Shipwright has the hostname '{}'".format(hostname))
print("Error: no box managed by Shipwright has the hostname '{}'".format(hostname))
exit(1)
return wrapper
......@@ -70,9 +70,9 @@ def is_ipaddress(ip_addr):
def print_status():
"""
Prints the status of all the virtual machines managed by Shipwright
Prints the status of all the boxes managed by Shipwright
"""
vm_paths = [str(d) for d in XDG_BOX_CONFIG_HOME.iterdir() if d.is_dir()]
box_paths = [str(d) for d in XDG_BOX_CONFIG_HOME.iterdir() if d.is_dir()]
vgt_db = Path(
os.environ.get('VAGRANT_HOME', str(Path.home().joinpath('.vagrant.d'))),
'data', 'machine-index', 'index'
......@@ -83,7 +83,7 @@ def print_status():
db = json.loads(vgt_db.open().read())
for k, v in db['machines'].items():
vagrant_wd = v['vagrantfile_path']
if vagrant_wd in vm_paths:
if vagrant_wd in box_paths:
# get the ip address
cp = subprocess.run(
['vagrant','ssh-config'], cwd=vagrant_wd,
......@@ -99,16 +99,16 @@ def print_status():
break
print(f"{v['name']} \t {v['state']}\t {ip_addr}")
count+=1
print('Total {} machine(s)'.format(count))
print('Total {} box(es)'.format(count))
def vm_create(hostname, ram, cpus, provider, token):
def box_create(hostname, ram, cpus, provider, token):
"""
This creates a box using the template
"""
vagrant_wd = XDG_BOX_CONFIG_HOME.joinpath(hostname)
if vagrant_wd.exists():
print("Shipyard error: There's already a vm with that hostname")
print("Shipyard error: There's already a box with that hostname")
exit(0)
vagrant_wd.mkdir(parents=True)
......@@ -143,7 +143,7 @@ def vm_create(hostname, ram, cpus, provider, token):
@only_if_box_exist
def destroy_vm(hostname):
def box_destroy(hostname):
"""
Destroy a box, or all
"""
......@@ -155,7 +155,7 @@ def destroy_vm(hostname):
@only_if_box_exist
def run_playbook(hostname, playbook, retry_file=None):
"""
run an Ansible playbook against this vm
run an Ansible playbook against this box
"""
vagrant_wd = XDG_BOX_CONFIG_HOME.joinpath(hostname)
inventory_file = vagrant_wd.joinpath('.vagrant', 'provisioners', 'ansible', 'inventory', 'vagrant_ansible_inventory')
......@@ -172,18 +172,18 @@ def run_playbook(hostname, playbook, retry_file=None):
@only_if_box_exist
def start_vm(hostname):
def box_start(hostname):
"""
Starts the vm with the provided hostname
Starts the box with the provided hostname
"""
vagrant_wd = XDG_BOX_CONFIG_HOME.joinpath(hostname)
subprocess.run(['vagrant','up'], cwd=vagrant_wd)
@only_if_box_exist
def halt_vm(hostname):
def box_halt(hostname):
"""
Stops the vm with the provided hostname
Stops the box with the provided hostname
"""
vagrant_wd = XDG_BOX_CONFIG_HOME.joinpath(hostname)
subprocess.run(['vagrant','halt'], cwd=vagrant_wd)
......@@ -201,29 +201,29 @@ def invoke_shell(hostname):
@only_if_box_exist
def which(hostname):
"""
Print the directory of a vm by it's hostname
Print the directory of a box by it's hostname
"""
vagrant_wd = XDG_BOX_CONFIG_HOME.joinpath(hostname)
print(vagrant_wd)
@only_if_box_exist
def gio_open_vm(hostname):
def box_gio_open(hostname):
"""
Open the vm directory in nautilis or any other file manager
Open the box directory in nautilis or any other file manager
"""
vagrant_wd = XDG_BOX_CONFIG_HOME.joinpath(hostname)
subprocess.run(['gio','open', vagrant_wd])
COMMANDS = {
'status': "Prints the status of all the machines's managed by vm",
'create': 'Creates a new machine using either libvirt(default) or Digital Ocean',
'status': "Prints the status of all the boxes' managed by box",
'create': 'Creates a new box using either libvirt(default) or Digital Ocean',
'up': 'Start box',
'halt': 'Stop/shutdown a box',
'restart': 'Restarts the box',
'destroy': 'Destroy the box and do cleanup',
'ssh': 'Connect to the box using SSH',
'playbook': 'Run a playbook against a machine',
'playbook': 'Run a playbook against a box',
'which': 'Print the path to the Vagrantfile',
'open': 'Show the working directory of the box using the file manager.'
}
......@@ -231,8 +231,8 @@ COMMANDS = {
if __name__ == '__main__':
cmd_parser = argparse.ArgumentParser(
prog='vm',
description='This utility helps you mange virtual machines with Vagrant without dealing with configuration details',
prog='box',
description="This utility helps you mange virtual boxes'ith Vagrant without dealing with configuration details",
)
cmd_parser.add_argument('command', choices=COMMANDS,)
cmd_args = cmd_parser.parse_args(sys.argv[1:2])
......@@ -245,9 +245,9 @@ if __name__ == '__main__':
print_status()
sys.exit()
sub_parser = argparse.ArgumentParser(prog='vm',)
sub_parser = argparse.ArgumentParser(prog='box',)
if cmd_args.command == 'create':
sub_parser.usage = 'vm create <hostname> [--ram RAM] [--cpus CPUS] [--provider libvirt|digital_ocean] [--token]'
sub_parser.usage = 'box create <hostname> [--ram RAM] [--cpus CPUS] [--provider libvirt|digital_ocean] [--token]'
sub_parser.add_argument('hostname', help='This is the hostname for the new the box')
sub_parser.add_argument('--ram', help='Hoy much RAM for this box (default is 512MB for libvirt and 1GB for digital ocean.)', default=512)
sub_parser.add_argument('--cpus', help='Hoy many CPUs for this box (default is 1)', default=1)
......@@ -256,14 +256,14 @@ if __name__ == '__main__':
sub_args = sub_parser.parse_args(sys.argv[2:])
if sub_args.provider == 'digital_ocean' and sub_args.token is None:
print('Error: When using the digital_ocean provider you must provide the access token\n')
print('Example: shipwright vm create foobar --provider digital_ocean --token 0d74f0a...')
print('Example: shipwright box create foobar --provider digital_ocean --token 0d74f0a...')
sys.exit(1)
vm_create(sub_args.hostname, sub_args.ram, sub_args.cpus, sub_args.provider, sub_args.token)
box_create(sub_args.hostname, sub_args.ram, sub_args.cpus, sub_args.provider, sub_args.token)
sys.exit()
sub_parser.add_argument('hostname', help='This is the hostname of the box')
if cmd_args.command == 'playbook':
sub_parser.usage = 'vm playbook hostname path/to/playbook.yml'
sub_parser.usage = 'box playbook hostname path/to/playbook.yml'
sub_parser.add_argument('playbook', help='The path to the playbook file')
sub_parser.add_argument('--retry', help='The path to the playbook retry file.', required=False)
sub_args = sub_parser.parse_args(sys.argv[2:])
......@@ -272,20 +272,20 @@ if __name__ == '__main__':
sub_args = sub_parser.parse_args(sys.argv[2:])
if cmd_args.command == 'up':
start_vm(sub_args.hostname)
box_start(sub_args.hostname)
elif cmd_args.command == 'halt':
halt_vm(sub_args.hostname)
box_halt(sub_args.hostname)
elif cmd_args.command == 'restart':
halt_vm(sub_args.hostname)
start_vm(sub_args.hostname)
box_halt(sub_args.hostname)
box_start(sub_args.hostname)
elif cmd_args.command == 'destroy':
destroy_vm(sub_args.hostname)
box_destroy(sub_args.hostname)
elif cmd_args.command == 'ssh':
invoke_shell(sub_args.hostname)
elif cmd_args.command == 'which':
which(sub_args.hostname)
elif cmd_args.command == 'open':
gio_open_vm(sub_args.hostname)
box_gio_open(sub_args.hostname)
else:
cmd_parser.print_help()
exit(100)
......@@ -4,7 +4,7 @@ This is a library with ansible paybooks useful for any LDH developer.
## Using shipyard
If you are using `shipyard` to manage your VMs look at the following example. Lets run the playbook `liberty_shop.yml` to a VM with hostname `myserver`:
If you are using `shipyard` to manage your boxes look at the following example. Lets run the playbook `liberty_shop.yml` to a box with hostname `myserver`:
```
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment