From 276105f0020b72f5e0ca4d673e739a521cc6e695 Mon Sep 17 00:00:00 2001 From: Dimitris Poulopoulos Date: Thu, 2 May 2024 16:10:28 +0300 Subject: [PATCH] docs: Improve the K8s node deployment guide Improve the K8s node deployment guide by running the whole process through the terminal, without any UI. Signed-off-by: Dimitris Poulopoulos --- docs/source/manual-deployment/index.rst | 2 +- .../{debian-preseed.md => node-deployment.md} | 98 ++++------ infra/grub.cfg.j2 | 60 +++--- infra/k8s_preseed.cfg.j2 | 171 ++++++++++++++++++ infra/node1.xml | 10 +- 5 files changed, 251 insertions(+), 90 deletions(-) rename docs/source/manual-deployment/{debian-preseed.md => node-deployment.md} (66%) create mode 100644 infra/k8s_preseed.cfg.j2 diff --git a/docs/source/manual-deployment/index.rst b/docs/source/manual-deployment/index.rst index c678360..6a602d5 100644 --- a/docs/source/manual-deployment/index.rst +++ b/docs/source/manual-deployment/index.rst @@ -20,7 +20,7 @@ automate the Debian installation process using a preseed file. :maxdepth: 1 pxe-server - debian-preseed + node-deployment kubernetes longhorn kubeflow diff --git a/docs/source/manual-deployment/debian-preseed.md b/docs/source/manual-deployment/node-deployment.md similarity index 66% rename from docs/source/manual-deployment/debian-preseed.md rename to docs/source/manual-deployment/node-deployment.md index 25e7968..1109c03 100644 --- a/docs/source/manual-deployment/debian-preseed.md +++ b/docs/source/manual-deployment/node-deployment.md @@ -1,8 +1,8 @@ -# Deploy Debian on KVM +# Create a Kubernetes Node -This guide walks you through booting a VM from the network and installing Debian 12 (Bookworm), +This guide walks you through booting a VM from the network and installing Debian `12.x` (Bookworm), using a PXE server. Moreover, you will learn how to use a [preseed](https://wiki.debian.org/DebianInstaller/Preseed) -file to automate the installation of Debian 12 on any VM. +file to automate the installation of Debian `12.x` on any VM. ## Step 1: Define the Worker VM @@ -21,34 +21,17 @@ To complete this guide, you will need the following: Follow the steps below to define a new VM: -1. Change to root user: - - ```console - user:~$ sudo su - - root:~# - ``` - -1. Navigate to the project's root directory: - - ```console - root:~# cd /home/user/virtml - ``` - - ```{note} - Replace `/home/user/virtml` with the path to your project's root directory. - ``` - 1. Create a new `QCOW2` virtual disk for the VM: ```console - root:/home/user/virtml# qemu-img create -f qcow2 /var/lib/libvirt/images/node1.qcow2 96G + user:~/virtml$ qemu-img create -f qcow2 /var/lib/libvirt/images/node1.qcow2 96G Formatting '/var/lib/libvirt/images/node1.qcow2', fmt=qcow2 cluster_size=65536 extended_l2=off compression_type=zlib size=103079215104 lazy_refcounts=off refcount_bits=16 ``` 1. Define a new VM, using the XML file inside the `infra` directory: ```console - root:/home/user/virtml# virsh define --file infra/node1.xml + user:~/virtml$ virsh define --file infra/node1.xml Domain 'node1' defined from node1.xml ``` @@ -64,11 +47,11 @@ Verify that the VM has been defined correctly and is in the `shut off` state: 1. List the VMs you have defined: ```console - root:/home/user/virtml# virsh list --all - Id Name State + user:~/virtml$ virsh list --all + Id Name State ----------------------------- - 1 pxe-server running - - node1 shut off + 1 virtml-admin running + - node1 shut off ``` ## Step 2: Configure the PXE Server @@ -84,45 +67,40 @@ To complete this guide, you will need the following: ### Procedure -1. Change back to your user: +1. Decide on login credentials for the `root` user of new worker VM: ```console - root:/home/user/virtml# exit - user:~$ + user:~/virtml$ export ROOTPW_HASH=$(openssl passwd -6) ``` -1. Navigate to your project's directory: +1. Export your public SSH key: ```console - user:~$ cd virtml - ``` - - ```{note} - Replace `virtml` with the path to your project's root directory. + user:~/virtml$ export SSH_KEY=$(cat ~/.ssh/id_rsa.pub) ``` -1. Decide on login credentials for the `root` user of new worker VM: +1. Export the hostname of the node VM: ```console - user:~/virtml$ export ROOTPW_HASH=$(openssl passwd -6) + user:~/virtml$ export HOSTNAME=node1 ``` -1. Export your public SSH key: +1. Export the domain name of the node VM: ```console - user:~/virtml$ export SSH_KEY=$(cat ~/.ssh/id_rsa.pub) + user:~/virtml$ export DOMAIN=example.com ``` 1. Render the preseed file: ```console - user:~/virtml$ j2 infra/preseed.cfg.j2 > preseed.cfg + user:~/virtml$ j2 infra/k8s_preseed.cfg.j2 > infra/k8s_preseed.cfg ``` 1. Copy the preseed file onto the PXE Server: ```console - user:~/virtml$ scp preseed.cfg root@pxe-server:/srv/tftp/preseed.cfg + user:~/virtml$ scp infra/k8s_preseed.cfg root@virtml-admin:/srv/tftp/preseed.cfg ``` 1. Decide on the IP address and the hostname of the worker VM: @@ -130,7 +108,7 @@ To complete this guide, you will need the following: a. Set the VM's IP address: ```console - user:~/virtml$ export CLIENT_IP=192.168.1.16 + user:~/virtml$ export CLIENT_IP=192.168.20.101 ``` b. Set the VM's MAC address: @@ -148,31 +126,31 @@ To complete this guide, you will need the following: 1. Render the `dnsmasq` configuration: ```console - user:~/virtml$ j2 infra/dnsmasq.conf.j2 > dnsmasq.conf-01-${CLIENT_MAC//:/-} + user:~/virtml$ j2 infra/dnsmasq.conf.j2 > infra/dnsmasq.conf-01-${CLIENT_MAC//:/-} ``` 1. Copy the configuration file onto the PXE Server: ```console - user:~/virtml$ scp dnsmasq.conf-01-${CLIENT_MAC//:/-} root@pxe-server:/etc/dnsmasq.d/dnsmasq.conf-01-${CLIENT_MAC//:/-} + user:~/virtml$ scp infra/dnsmasq.conf-01-${CLIENT_MAC//:/-} root@virtml-admin:/etc/dnsmasq.d/dnsmasq.conf-01-${CLIENT_MAC//:/-} ``` 1. SSH into the PXE server VM: ```console - user:~/virtml$ ssh root@pxe-server + user:~/virtml$ ssh root@virtml-admin ``` 1. Restart the `dnsmasq` service: ```console - root@pxe-server:~# systemctl restart dnsmasq + root@virtml-admin:~# systemctl restart dnsmasq ``` 1. Log out the PXE Server: ```console - root@pxe-server:~# exit + root@virtml-admin:~# exit ``` ## Step 3: Start the worker VM @@ -187,25 +165,29 @@ Debian automatically. ### Procedure -1. Change to root user: - - ```console - user:~$ sudo su - - root:~# - ``` - 1. Start the worker VM: ```console - root:~# virsh start node1 + user:~/virtml$ virsh start node1 Domain 'node1' started ``` ### Verify -1. Connect to the worker VM through the "Virtual Machine Manager" UI and watch as the Debian - installer automatically installs the OS, without any human intervention. +1. Connect to the node1 through your terminal and watch as the Debian installer automatically + installs the OS, without any human intervention. + + ```console + user:~/virtml$ virsh console node1 + ``` + +1. SSH into the node1 VM: ```console - root:/home/user/virtml# virt-manager + user:~/virtml$ ssh root@node1 + ``` + + ```{note} + Replace `node1` with the IP address of the VM. Alternatively, you can set the hostname for the + VM in your `/etc/hosts` file. ``` diff --git a/infra/grub.cfg.j2 b/infra/grub.cfg.j2 index 75992c9..cd6fc01 100644 --- a/infra/grub.cfg.j2 +++ b/infra/grub.cfg.j2 @@ -16,6 +16,10 @@ if loadfont $font ; then terminal_output gfxterm fi +serial --unit=0 --speed=115200 --word=8 --parity=no --stop=1 +terminal_input serial +terminal_output serial + if background_image /isolinux/splash.png; then set color_normal=light-gray/black set color_highlight=white/black @@ -27,46 +31,46 @@ else set menu_color_highlight=white/blue fi -set default="1>2" # Sets the Automated install as the default entry -set timeout=5 # Sets the timeout to 5 seconds +set default="1>2" # Sets the Automated install as the default entry +set timeout=5 # Sets the timeout to 5 seconds insmod play play 960 440 1 0 4 440 1 menuentry 'Install' { set background_color=black - linux /debian-installer/amd64/linux vga=788 --- quiet + linux /debian-installer/amd64/linux console=ttyS0,115200n8 --- quiet initrd /debian-installer/amd64/initrd.gz } submenu --hotkey=a 'Advanced options ...' { set gfxpayload=keep menuentry '... Expert install' { set background_color=black - linux /debian-installer/amd64/linux priority=low vga=788 --- + linux /debian-installer/amd64/linux priority=low console=ttyS0,115200n8 --- initrd /debian-installer/amd64/initrd.gz } menuentry '... Rescue mode' { set background_color=black - linux /debian-installer/amd64/linux vga=788 rescue/enable=true --- quiet + linux /debian-installer/amd64/linux console=ttyS0,115200n8 rescue/enable=true --- quiet initrd /debian-installer/amd64/initrd.gz } menuentry '... Automated install' { set background_color=black - linux /debian-installer/amd64/linux auto=true priority=critical preseed/url=tftp://{{ PXE_SERVER }}/preseed.cfg vga=788 --- quiet + linux /debian-installer/amd64/linux auto=true priority=critical preseed/url=tftp://{{ PXE_SERVER }}/preseed.cfg console=ttyS0,115200n8 --- quiet initrd /debian-installer/amd64/initrd.gz } menuentry --hotkey=x '... Expert install with speech synthesis' { set background_color=black - linux /debian-installer/amd64/linux priority=low vga=788 speakup.synth=soft --- + linux /debian-installer/amd64/linux priority=low console=ttyS0,115200n8 speakup.synth=soft --- initrd /debian-installer/amd64/initrd.gz } menuentry --hotkey=r '... Rescue mode with speech synthesis' { set background_color=black - linux /debian-installer/amd64/linux vga=788 rescue/enable=true speakup.synth=soft --- quiet + linux /debian-installer/amd64/linux console=ttyS0,115200n8 rescue/enable=true speakup.synth=soft --- quiet initrd /debian-installer/amd64/initrd.gz } menuentry --hotkey=a '... Automated install with speech synthesis' { set background_color=black - linux /debian-installer/amd64/linux auto=true priority=critical vga=788 speakup.synth=soft --- quiet + linux /debian-installer/amd64/linux auto=true priority=critical console=ttyS0,115200n8 speakup.synth=soft --- quiet initrd /debian-installer/amd64/initrd.gz } submenu '... Desktop environment menu ...' { @@ -75,29 +79,29 @@ submenu --hotkey=a 'Advanced options ...' { set gfxpayload=keep menuentry '... Install' { set background_color=black - linux /debian-installer/amd64/linux desktop=gnome vga=788 --- quiet + linux /debian-installer/amd64/linux desktop=gnome console=ttyS0,115200n8 --- quiet initrd /debian-installer/amd64/initrd.gz } submenu '... GNOME advanced options ...' { set gfxpayload=keep menuentry '... Expert install' { set background_color=black - linux /debian-installer/amd64/linux desktop=gnome priority=low vga=788 --- + linux /debian-installer/amd64/linux desktop=gnome priority=low console=ttyS0,115200n8 --- initrd /debian-installer/amd64/initrd.gz } menuentry '... Automated install' { set background_color=black - linux /debian-installer/amd64/linux desktop=gnome auto=true priority=critical vga=788 --- quiet + linux /debian-installer/amd64/linux desktop=gnome auto=true priority=critical console=ttyS0,115200n8 --- quiet initrd /debian-installer/amd64/initrd.gz } menuentry --hotkey=x '... Expert install with speech synthesis' { set background_color=black - linux /debian-installer/amd64/linux desktop=gnome priority=low vga=788 speakup.synth=soft --- + linux /debian-installer/amd64/linux desktop=gnome priority=low console=ttyS0,115200n8 speakup.synth=soft --- initrd /debian-installer/amd64/initrd.gz } menuentry --hotkey=a '... Automated install with speech synthesis' { set background_color=black - linux /debian-installer/amd64/linux desktop=gnome auto=true priority=critical vga=788 speakup.synth=soft --- quiet + linux /debian-installer/amd64/linux desktop=gnome auto=true priority=critical console=ttyS0,115200n8 speakup.synth=soft --- quiet initrd /debian-installer/amd64/initrd.gz } } @@ -106,29 +110,29 @@ submenu --hotkey=a 'Advanced options ...' { set gfxpayload=keep menuentry '... Install' { set background_color=black - linux /debian-installer/amd64/linux desktop=kde vga=788 --- quiet + linux /debian-installer/amd64/linux desktop=kde console=ttyS0,115200n8 --- quiet initrd /debian-installer/amd64/initrd.gz } submenu '... KDE Plasma advanced options ...' { set gfxpayload=keep menuentry '... Expert install' { set background_color=black - linux /debian-installer/amd64/linux desktop=kde priority=low vga=788 --- + linux /debian-installer/amd64/linux desktop=kde priority=low console=ttyS0,115200n8 --- initrd /debian-installer/amd64/initrd.gz } menuentry '... Automated install' { set background_color=black - linux /debian-installer/amd64/linux desktop=kde auto=true priority=critical vga=788 --- quiet + linux /debian-installer/amd64/linux desktop=kde auto=true priority=critical console=ttyS0,115200n8 --- quiet initrd /debian-installer/amd64/initrd.gz } menuentry --hotkey=x '... Expert install with speech synthesis' { set background_color=black - linux /debian-installer/amd64/linux desktop=kde priority=low vga=788 speakup.synth=soft --- + linux /debian-installer/amd64/linux desktop=kde priority=low console=ttyS0,115200n8 speakup.synth=soft --- initrd /debian-installer/amd64/initrd.gz } menuentry --hotkey=a '... Automated install with speech synthesis' { set background_color=black - linux /debian-installer/amd64/linux desktop=kde auto=true priority=critical vga=788 speakup.synth=soft --- quiet + linux /debian-installer/amd64/linux desktop=kde auto=true priority=critical console=ttyS0,115200n8 speakup.synth=soft --- quiet initrd /debian-installer/amd64/initrd.gz } } @@ -137,29 +141,29 @@ submenu --hotkey=a 'Advanced options ...' { set gfxpayload=keep menuentry '... Install' { set background_color=black - linux /debian-installer/amd64/linux desktop=lxde vga=788 --- quiet + linux /debian-installer/amd64/linux desktop=lxde console=ttyS0,115200n8 --- quiet initrd /debian-installer/amd64/initrd.gz } submenu '... LXDE advanced options ...' { set gfxpayload=keep menuentry '... Expert install' { set background_color=black - linux /debian-installer/amd64/linux desktop=lxde priority=low vga=788 --- + linux /debian-installer/amd64/linux desktop=lxde priority=low console=ttyS0,115200n8 --- initrd /debian-installer/amd64/initrd.gz } menuentry '... Automated install' { set background_color=black - linux /debian-installer/amd64/linux desktop=lxde auto=true priority=critical vga=788 --- quiet + linux /debian-installer/amd64/linux desktop=lxde auto=true priority=critical console=ttyS0,115200n8 --- quiet initrd /debian-installer/amd64/initrd.gz } menuentry --hotkey=x '... Expert install with speech synthesis' { set background_color=black - linux /debian-installer/amd64/linux desktop=lxde priority=low vga=788 speakup.synth=soft --- + linux /debian-installer/amd64/linux desktop=lxde priority=low console=ttyS0,115200n8 speakup.synth=soft --- initrd /debian-installer/amd64/initrd.gz } menuentry --hotkey=a '... Automated install with speech synthesis' { set background_color=black - linux /debian-installer/amd64/linux desktop=lxde auto=true priority=critical vga=788 speakup.synth=soft --- quiet + linux /debian-installer/amd64/linux desktop=lxde auto=true priority=critical console=ttyS0,115200n8 speakup.synth=soft --- quiet initrd /debian-installer/amd64/initrd.gz } } @@ -175,7 +179,7 @@ submenu --hotkey=d 'Accessible dark contrast installer menu ...' { set gfxpayload=keep menuentry '... Install' { set background_color=black - linux /debian-installer/amd64/linux vga=788 theme=dark --- quiet + linux /debian-installer/amd64/linux console=ttyS0,115200n8 theme=dark --- quiet initrd /debian-installer/amd64/initrd.gz } submenu --hotkey=a '... Advanced options ...' { @@ -187,17 +191,17 @@ submenu --hotkey=d 'Accessible dark contrast installer menu ...' { set gfxpayload=keep menuentry '... Expert install' { set background_color=black - linux /debian-installer/amd64/linux priority=low vga=788 theme=dark --- + linux /debian-installer/amd64/linux priority=low console=ttyS0,115200n8 theme=dark --- initrd /debian-installer/amd64/initrd.gz } menuentry '... Rescue mode' { set background_color=black - linux /debian-installer/amd64/linux vga=788 rescue/enable=true theme=dark --- quiet + linux /debian-installer/amd64/linux console=ttyS0,115200n8 rescue/enable=true theme=dark --- quiet initrd /debian-installer/amd64/initrd.gz } menuentry '... Automated install' { set background_color=black - linux /debian-installer/amd64/linux auto=true priority=critical vga=788 theme=dark --- quiet + linux /debian-installer/amd64/linux auto=true priority=critical console=ttyS0,115200n8 theme=dark --- quiet initrd /debian-installer/amd64/initrd.gz } } diff --git a/infra/k8s_preseed.cfg.j2 b/infra/k8s_preseed.cfg.j2 new file mode 100644 index 0000000..625e4a6 --- /dev/null +++ b/infra/k8s_preseed.cfg.j2 @@ -0,0 +1,171 @@ +#_preseed_V1 + +## Contents of the preconfiguration file (for bookworm) + +### Localization +# Preseeding only locale sets language, country and locale. +d-i debian-installer/locale string en_US + +# Keyboard selection. +d-i keyboard-configuration/xkb-keymap select us + +### Network configuration +# netcfg will choose an interface that has link if possible. This makes it +# skip displaying a list if there is more than one interface. +d-i netcfg/choose_interface select auto + +# To set a different link detection timeout (default is 3 seconds). +# Values are interpreted as seconds. +d-i netcfg/link_wait_timeout string 10 + +# If you have a slow dhcp server and the installer times out waiting for +# it, this might be useful. +d-i netcfg/dhcp_timeout string 60 +d-i netcfg/dhcpv6_timeout string 60 + +# If you want the preconfiguration file to work on systems both with and +# without a dhcp server, uncomment these lines and the static network +# configuration below. +d-i netcfg/dhcp_failed note +d-i netcfg/dhcp_options select Configure network manually + +# Any hostname and domain names assigned from dhcp take precedence over +# values set here. However, setting the values still prevents the questions +# from being shown, even if values come from dhcp. +d-i netcfg/get_hostname string {{ HOSTNAME }} +d-i netcfg/get_domain string {{ DOMAIN }} + +# If you want to force a hostname, regardless of what either the DHCP +# server returns or what the reverse DNS entry for the IP is, uncomment +# and adjust the following line. +d-i netcfg/hostname string virtml-admin + +# Disable that annoying WEP key dialog. +d-i netcfg/wireless_wep string + +### Mirror settings +# Mirror protocol: +# If you select ftp, the mirror/country string does not need to be set. +# Default value for the mirror protocol: http. +#d-i mirror/protocol string ftp +d-i mirror/country string manual +d-i mirror/http/hostname string deb.debian.org +d-i mirror/http/directory string /debian +d-i mirror/http/proxy string + +### Account setup +# Skip creation of a root account (normal user account will be able to +# use sudo). +#d-i passwd/root-login boolean false +# Alternatively, to skip creation of a normal user account. +d-i passwd/make-user boolean false + +# Root password, either in clear text +#d-i passwd/root-password password r00tme +#d-i passwd/root-password-again password r00tme +# or encrypted using a crypt(3) hash. +d-i passwd/root-password-crypted password {{ ROOTPW_HASH }} + +### Clock and time zone setup +# Controls whether or not the hardware clock is set to UTC. +d-i clock-setup/utc boolean true + +# You may set this to any valid setting for $TZ; see the contents of +# /usr/share/zoneinfo/ for valid values. +d-i time/zone string Europe/Athens + +### Partitioning +## Partitioning using GPT +# Specify the method to use. +# The presently available methods are: +# - regular: use the usual partition types for your architecture +# - lvm: use LVM to partition the disk +# - crypto: use LVM within an encrypted partition +d-i partman-auto/method string regular + +# Set the partition table type to GPT +d-i partman-partitioning/default_label string gpt + +# Create a small `/boot/efi` partition, and use the rest of the space +# for the root partition: +d-i partman-auto/expert_recipe string \ + boot-root :: \ + 512 512 1024 free \ + $iflabel{ gpt } \ + $reusemethod{ } \ + method{ efi } \ + format{ } \ + . \ + 100% 100% 100% ext4 \ + $primary{ } \ + method{ format } format{ } \ + use_filesystem{ } filesystem{ ext4 } \ + mountpoint{ / } \ + . + +# Confirm that you don't want to create a swap partition. +d-i partman-basicfilesystems/no_swap boolean false + +# Choose the recipe to use for the partitioning. +d-i partman-auto/choose_recipe select boot-root + +# Confirm that you want to write the changes to the disks. +d-i partman-partitioning/confirm_write_new_label boolean true +d-i partman/choose_partition select finish +d-i partman/confirm_nooverwrite boolean true +d-i partman/confirm boolean true +d-i partman-md/confirm boolean true + +### Apt setup +# Choose, if you want to scan additional installation media +# (default: false). +d-i apt-setup/cdrom/set-first boolean false + +# You can choose to install non-free firmware. +d-i apt-setup/non-free-firmware boolean true + +# You can choose to install non-free and contrib software. +d-i apt-setup/non-free boolean true +d-i apt-setup/contrib boolean true + +# Select which update services to use; define the mirrors to be used. +# Values shown below are the normal defaults. +d-i apt-setup/services-select multiselect security, updates +d-i apt-setup/security_host string security.debian.org + +### Package selection +# Choose a minimal installation (only standard system utilities). +tasksel tasksel/first multiselect standard + +# Individual additional packages to install. +d-i pkgsel/include string openssh-server + +# You can choose, if your system will report back on what software you have +# installed, and what software you use. +popularity-contest popularity-contest/participate boolean false + +### Boot loader installation (Grub is the boot loader for x86). +# This is fairly safe to set, it makes grub install automatically to the UEFI +# partition/boot record if no other operating system is detected on the machine. +d-i grub-installer/only_debian boolean true + +# This one makes grub-installer install to the UEFI partition/boot record, if +# it also finds some other OS, which is less safe as it might not be able to +# boot that other OS. +#d-i grub-installer/with_other_os boolean true + +# Select devices to install the bootloader on: +d-i grub-installer/bootdev string /dev/vda + +### Finishing up the installation +# Avoid that last message about the install being complete. +d-i finish-install/reboot_in_progress note + +# This command is run just before the install finishes, but when there is +# still a usable /target directory. +# Authorize the SSH key for root. +d-i preseed/late_command string in-target mkdir -p /root/.ssh; \ +in-target /bin/sh -c "echo '{{ SSH_KEY }}' >> /root/.ssh/authorized_keys"; \ +in-target chown -R root:root /root/.ssh/; \ +in-target chmod 644 /root/.ssh/authorized_keys; \ +in-target chmod 700 /root/.ssh/ diff --git a/infra/node1.xml b/infra/node1.xml index 4e64bc5..6b6d470 100644 --- a/infra/node1.xml +++ b/infra/node1.xml @@ -16,6 +16,12 @@ /usr/bin/qemu-system-x86_64 + + + + + + @@ -23,12 +29,10 @@ - - + -