reshuffle installation topics

2024-08-08 10:22:08 +02:00
parent 04b3adc58e
commit 328334d2ba
6 changed files with 319 additions and 0 deletions
@@ -0,0 +1,148 @@
+# Installation
+
+# Example Installation
+
+In this section we describe the deployment of a new server from
+scratch.
+All the operations will be performed using `bob`, the command-line
+client for interacting with `sysdb`.
+
+The informations we need are:
+
+  - the server name: `logging-ra.psi.ch`
+  - the server MAC address: `23:3d:ef:33:11:22`
+  - optional static or dynamic IP: `static` (RHEL7 & RHEL8 only)
+  - the OS installer: `rhel8install`
+  - the server role: `role::logging_server`
+  - optional the server environment in puppet: `prod`
+  - the sysdb deployment environment: `daas`
+  - optional the group inside the sysdb environment (`default` if not specified): `logging`
+  - optional the subgroup inside the group: `collector`
+
+## Setting up bob
+
+The `bob` tool is already set up on `lxsup.psi.ch`. You might connect with `ssh` and use it from there.
+
+Altenatively you many have on your workstation a local copy of `bob`. This can be done by installing the RPM from the pli-misc repository - https://repos.psi.ch/rhel8/latest/pli-misc/
+
+You might need to set a `PSI_BOB_USER` environment variable (`export PSI_BOB_USER=<you-name-it>`) or use the option `--user` if your local user is different from the one on sysdb.
+
+## Sysdb configuration
+
+We add the node to the environment, specifing `netboot` as
+the boot action
+```bash
+bob node add logging-ra.psi.ch daas netboot
+```
+
+We setup its MAC address:
+```bash
+bob node add-mac logging-ra.psi.ch 23:3d:ef:33:11:22
+```
+
+Next decide how the IP address is configured (`dhcp` or `static`):
+```bash
+bob node set-attr logging-ra.psi.ch network=static
+```
+
+And which installer is used:
+```bash
+bob node set-attr logging-ra.psi.ch ipxe_installer=rhel8install
+```
+
+And we finally setup the puppet role and puppet environment:
+```bash
+bob node set-attr logging-ra.psi.ch puppet_role=role::log_server
+bob node set-attr logging-ra.psi.ch puppet_env=prod
+bob node set-attr logging-ra.psi.ch puppet_group=logging
+bob node set-attr logging-ra.psi.ch puppet_subgroup=collector
+```
+
+## Example
+
+Full example:
+
+```bash
+bob node add lx-test-02.psi.ch lx netboot
+bob node add-mac lx-test-02 00:50:56:9d:19:76
+bob node set-attr lx-test-02.psi.ch ipxe_installer=rhel8install puppet_role=role::server
+bob node netboot lx-test-02.psi.ch
+bob node list -v lx-test-02
+```
+
+Ensure that a potential previous puppet certificate for this server is deleted on the puppet server: https://puppet.psi.ch
+
+
+## Special Settings
+
+### Custom Kernel Commandline Arguments
+For custom kernel commandline arguments for the installer (e.g. to provide drivers) the sysdb attribute `kernel_cmdline` can be used:
+
+```bash
+bob node set-attr lx-test-02.psi.ch kernel_cmdline=inst.dd=https://linuxsoft.cern.ch/elrepo/dud/el8/x86_64/dd-megaraid_sas-07.725.01.00-1.el8_9.elrepo.iso
+```
+
+### Custom Partitioning
+
+Please check out the [Partitioning page](partitioning).
+
+
+
+
+Linux systems are generally deployed using PXE and Kickstart. We use iPXE, which
+can retrieve its configuration via HTTP(S) and therefore gives us a lot of
+flexibility, because the iPXE configuration can be generated on the fly with the
+specific settings needed by the booting client. In the same way the Kickstart
+configuration for the RHEL installer is auto-generated.
+
+The information used for generating the iPXE and Kickstart configurations is
+stored in the sysdb (see below). The sysdb is accessible through a web api, and
+a command line client is available.
+
+When PXE boot is not an option, e.g. in restricted networks, it is possible to
+start iPXE from a USB stick or other media.
+
+The general process for a deployment/installation is:
+
+1. Register the system with sysdb (only for new systems).
+2. Tell sysdb to perform an installation on the next boot.
+3. Reboot the system and trigger a PXE boot (usually by pressing F12 during
+   POST).
+
+The easiest way to interact with sysdb is to use `bob`, a command-line client, set up ready to use on `lxsup.psi.ch`.
+Alternatively it is possible to use the web API directly.
+
+First, add the new node:
+```bash
+bob node add $FQDN $ENV netboot
+```
+
+
+To be able to PXE boot we need to configure at least one MAC address for the new
+node:
+```bash
+bob node add-mac $FQDN 00:50:56:aa:fe:9b
+```
+
+
+Finally we need to configure the installer to use, and the Puppet-related
+parameters:
+```bash
+bob node set-attr $FQDN ipxe_installer=rhel8install
+bob node set-attr $FQDN puppet_role=role::server
+```
+
+and optional:
+```bash
+bob node set-attr $FQDN puppet_group=cluster
+bob node set-attr $FQDN puppet_subgroup=compute
+bob node set-attr $FQDN network=static
+bob node set-attr $FQDN puppet_env=prod
+```
+
+## Redeployment
+
+After the initial installation the boot mode has been reset from netboot to local so it will then always boot from the local disk. For a redeployment the netboot needs to be set anew (on UEFI based systems netboot also needs to be always selected by the UEFI menu)):
+```
+bob node netboot $FQDN
+```