Plunder quickstart

This is a quick guide to building a basic and quick plunder deployment environment.

Environment

Networking Architecture

The most typical environment for a deployment server consists of a machine that spans or bridges two networks:

Deployment Operating System

This guide will use Ubuntu 16.04 (due to some NAT issues that the author lacked the skill to fix)..

Once the basic Operating System has been deployed with the openSSH packages installed, it will need it's networking configuration set:

/etc/network/interfaces =>

# The primary network interface or management interface
auto ens160
iface ens160 inet static
   address 192.168.0.100
   gateway 192.168.0.1
   netmask 255.255.255.0
   network 192.168.0.0
   dns-nameservers 192.168.0.15 8.8.8.8
   dns-search fnnrn.me

# The deployment network interface
auto ens192
iface ens192 inet static
   address 172.16.1.1
   gateway 172.16.1.1
   netmask 255.255.255.0

The above configuration specifies the following:

SSH Keys

The Deployment server will need to have SSH keys created if they don't already exist, these keys are needed so that the plunder server can interact with it's newly deployed servers. Also, if this step isn't followed then other interactions with plunder will typicall generate the warning:

WARN[0000] Failed to find default ssh key, if this is overridden by a deployment configuration this error can be ignored

To generate a new SSH key pair, we use the ssh-keygen command to generate a private and public key.

Enable routing / nat

This is required for an internet facing deployment, during the installation of machines on the deployment network they will need to pull packages from the internet. In order to do this they will attempt to route through their gateway 172.16.1.1 in order to access the package repositories.

This script (enable_internet.sh) will enable internet traffic to hosts on the deployment network.

#!/bin/sh
    echo 1 > /proc/sys/net/ipv4/ip_forward
    iptables -A FORWARD -i ens192 -o ens160 -j ACCEPT
    iptables -A FORWARD -i ens160 -o ens192 -m state --state ESTABLISHED,RELATED \
             -j ACCEPT
    iptables -t nat -A POSTROUTING -o ens160 -j MASQUERADE

Enable NFS (optional)

If the deployment ISOs exist on an external share, then the NFS packages will need installing on the deployment server.

$ sudo apt-get update
$ sudo apt-get install nfs-common

We can now see mounts on an external system with the following command:

$ showmount -e nassmall
Export list for nassmall:
/volume1/products 192.168.0.0/16

Finally we'll create a new mount point /nfs and mount this locally:

dan@plunder:~$ sudo mkdir /nfs
dan@plunder:~$ sudo mount nassmall:/volume1/products /nfs

Deployment summary

At this point we have should have a deployment server that sits over a managment network and a deployment network and we have access to installation ISOs and internet networking enabled.

Plunder

Install plunder

[TODO] get from github releases (> 0.5.0)

Configure plunder

The following steps will generate all of the configuration details that plunder requires in order to enable:

API Server

Step One:

Generate the API Server certificate, that is used to generate the client certificates and to authenticate a client wishing to interact with Plunder:

./plunder config apiserver server
WARN[0000] Failed to find default ssh key, if this is overridden by a deployment configuration this error can be ignored 

(If this warning appears, then you've not generated your SSH key pair)

Step Two:

Generate an API Server Client certificate, which is used for clients to interact with plunder.

./plunder config apiserver client
ls -la ./plunderclient.yaml 
-rw------- 1 dan dan 2780 Nov 21 11:58 ./plunderclient.yaml

Services Configuration

To generate an "example" configuration that is printed out to the console we can use the following command:

./plunder config server -o yaml
adapter: ens160
addressHTTP: 192.168.0.100
addressTFTP: 192.168.0.100
[...]

We can see by default that it's selected to expose it's services on the wrong interface, in order to correct that we can specify which interface (with the -n <interface>) to generate a configuration for.

./plunder config server -n ens192 -o yaml
adapter: ens192
addressHTTP: 172.16.1.1
addressTFTP: 172.16.1.1

We can save this configuration to a local file services.yaml with a console redirect > operator.

./plunder config server -n ens192 -o yaml > services.yaml
ls -la services.yaml
-rw-rw-r-- 1 dan dan 387 Nov 21 12:08 services.yaml

Finally, by default no services (http,DHCP and tftp) are enabled so these will need enabling for Plunder to work correctly. To do this we will need to edit our new configuration services.yaml and modify the enable<SERVICE>: false so that the services are set to true.

We can test that this configuration looks as expected by starting plunder with this configuration (ctrl + c to quit):

sudo ./plunder server --config ./services.yaml 
[sudo] password for dan: 
INFO[0000] Reading configuration from [./services.yaml] 
INFO[0000] Starting Remote Boot Services, press CTRL + c to stop 
INFO[0000] Plunder Services --> Starting DHCP           
INFO[0000] Plunder Services --> Starting TFTP           
INFO[0000] Opening and caching undionly.kpxe            
WARN[0000] No local undionly.kpxe found, falling back to embedded version which may be out of date 
INFO[0000] Plunder Services --> Starting HTTP           
INFO[0000] Starting API server on port 60443

Deployment Configuration

To generate a baseline or example configuration we can have plunder generate one and then modify it to match our environment:

./plunder config deployment -o yaml > deployments.yaml

An example deployment will be populated under the "deployments" section, however the main section is the globalConfig.

Global Configuration

The globalConfig is a configuration that plunder will use to populate any missing configuration from a deployment. Effectively we can think of the global configuration being the template for all deployments and then anything specific about a deployment being the parts that change (IP addresses/ hostnames etc..).

More details can be found here => https://github.com/plunder-app/plunder/blob/master/docs/deployment.md

For the configuation described above the globalConfig should look like the following:

globalConfig:
  adapter: ens192
  gateway: 172.16.1.1
  mirrordir: /ubuntu
  nameserver: 172.16.1.1
  ntpserver: 172.16.1.1
  packages: openssh-server
  password: pass
  repoaddress: 172.16.1.1
  sshkeypath: /home/dan/.ssh/id_pub.rsa
  subnet: 255.255.255.0
  username: user

This points all installations to default to using our local network configuration and to use our ssh key when being deployed.

Start Plunder

NOTE: Before we start plunder we need to consider the default behaviour of our new machines.. Some new machines may boot and then hang if they're not given deployment (correct DHCP/PXE) information. To circumvent this, plunder has teh capabilty to provision a profile that will force server to reboot if there is no deployment configuraiton for them.. This is done through the --defaultBoot flag, with the reboot option (Wake On Lan coming soon :-) ).

We can now start plunder as a service on our deployment machine, with the configuration for the services and the deployment config for our new host deployments.

sudo ./plunder server --config ./services.yaml --deployment ./deployment.yaml --defaultBoot reboot
INFO[0000] Reading deployment configuration from [./deployment.yaml] 
INFO[0000] Reading configuration from [./services.yaml] 
INFO[0000] Starting Remote Boot Services, press CTRL + c to stop 
INFO[0000] Plunder Services --> Starting DHCP           
INFO[0000] Updating the Deployment Configuration        
INFO[0000] Updating of deployment configuration complete 
INFO[0000] Plunder Services --> Starting TFTP           
INFO[0000] Opening and caching undionly.kpxe            
WARN[0000] No local undionly.kpxe found, falling back to embedded version which may be out of date 
INFO[0000] Plunder Services --> Starting HTTP           
INFO[0000] Starting API server on port 60443

Using Plunder

At this point plunder is up and running with all the relevant infrastructure configuration that it needs to deploy.. at this point we will need to test APIserver connectivity from another host.

So hopping to another machine that can access the management network we will need to install pldrctl and grab the plunder config:

Below we're SCPing the client configuration and using the pldrctl tool to see the example deployment.

$ scp plunder:plunderclient.yaml .
plunderclient.yaml                                                                                                                                                 100% 2780     2.2MB/s   00:00    
$ pldrctl get deployments
Mac Address        Deploymemt  Hostname  IP Address
00:11:22:33:44:55  default     Server01  192.168.0.2

Creating a boot configuration

(FINAL STEP)

We will need to create a boot configuration so that new hosts know what to boot from.

We can see the default boot configuration that was created above:

$ pldrctl get boot
Config Name  Kernel Path  Initrd Path  Command Line
default      /kernelPath  /initPath    cmd=options

We will need to create a new Ubuntu (preseed) configuration that uses an ubuntu ISO on the nfs share, and maps to a kernel and initrd within the ISO.

$ pldrctl create boot \
--name preseed \
--isoPath /nfs/Operating Systems/Ubuntu/ubuntu-16.04.5-server-amd64.iso \
--isoPrefix ubuntu \
--kernel ubuntu/install/netboot/ubuntu-installer/amd64/linux \
--initrd ubuntu/install/netboot/ubuntu-installer/amd64/initrd.gz

We can now verify that with the following:

$ pldrctl get boot
Config Name  Kernel Path                                          Initrd Path                                              Command Line
default      /kernelPath                                          /initPath                                                cmd=options
preseed      ubuntu/install/netboot/ubuntu-installer/amd64/linux  ubuntu/install/netboot/ubuntu-installer/amd64/initrd.gz  

Provision a server

(THE ULTIMATE TEST)

Any hosts that are booting on the deployment network will be already given PXE information that forces them to reboot, we can see them by looking for "unleased" servers:

$ pldrctl get unleased -c
Mac Address        Hardware Vendor  Time Seen                 Time since
00:50:56:a5:d9:78  VMware, Inc.     Thu Nov 21 18:03:26 2019  6s

Lets provision this server with the preseed boot configuration and a static ip address on the deployment network 172.16.1.100.

$ pldrctl  create deployment -a 172.16.1.100 -c preseed -m 00:50:56:a5:d9:78 -n example
$ pldrctl get deployments
Mac Address        Deploymemt  Hostname            IP Address
00:11:22:33:44:55  default     Server01            192.168.0.2
00:50:56:a5:d9:78  preseed     example             172.16.1.100

When this server finishes a reboot, the next PXE configuration will provision the server.