diff --git a/_toc.yml b/_toc.yml index 36bc1f1..c5246cd 100644 --- a/_toc.yml +++ b/_toc.yml @@ -27,13 +27,13 @@ chapters: - file: admin-guide/index sections: - file: admin-guide/guidelines - - file: admin-guide/deployment + - file: admin-guide/installation sections: - - file: admin-guide/deployment/sample - - file: admin-guide/deployment/consoles - - file: admin-guide/deployment/dmz - - file: admin-guide/deployment/reinstall - - file: admin-guide/deployment/partitioning + - file: admin-guide/installation/installation + - file: admin-guide/installation/reinstall + - file: admin-guide/installation/partitioning + - file: admin-guide/installation/consoles + - file: admin-guide/installation/dmz - file: admin-guide/configuration sections: - file: admin-guide/configuration/icinga2 diff --git a/admin-guide/deployment.md b/admin-guide/deployment.md deleted file mode 100644 index 9745d0f..0000000 --- a/admin-guide/deployment.md +++ /dev/null @@ -1,62 +0,0 @@ -# Deployment - -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 -``` - -```{tableofcontents} -``` diff --git a/admin-guide/deployment/sample.md b/admin-guide/deployment/sample.md deleted file mode 100644 index 94c6d2d..0000000 --- a/admin-guide/deployment/sample.md +++ /dev/null @@ -1,82 +0,0 @@ -# Sample deployment of a new server - -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=`) 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 - - bob node add logging-ra.psi.ch daas netboot - -We setup its MAC address: - - 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`): - - bob node set-attr logging-ra.psi.ch network=static - -And which installer is used: - - bob node set-attr logging-ra.psi.ch ipxe_installer=rhel8install - -And we finally setup the puppet role and puppet environment: - - 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: - - 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: - -``` -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 System Disk and Partitioning - -Please check out the [Partitioning page](partitioning). - diff --git a/admin-guide/installation.md b/admin-guide/installation.md new file mode 100644 index 0000000..cb7ead0 --- /dev/null +++ b/admin-guide/installation.md @@ -0,0 +1,4 @@ +# Installation + +```{tableofcontents} +``` diff --git a/admin-guide/deployment/consoles.md b/admin-guide/installation/consoles.md similarity index 100% rename from admin-guide/deployment/consoles.md rename to admin-guide/installation/consoles.md diff --git a/admin-guide/deployment/dmz.md b/admin-guide/installation/dmz.md similarity index 100% rename from admin-guide/deployment/dmz.md rename to admin-guide/installation/dmz.md diff --git a/admin-guide/installation/installation.md b/admin-guide/installation/installation.md new file mode 100644 index 0000000..afe6f6f --- /dev/null +++ b/admin-guide/installation/installation.md @@ -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=`) 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 +``` diff --git a/admin-guide/deployment/partitioning.md b/admin-guide/installation/partitioning.md similarity index 55% rename from admin-guide/deployment/partitioning.md rename to admin-guide/installation/partitioning.md index fdb5783..8fa1476 100644 --- a/admin-guide/deployment/partitioning.md +++ b/admin-guide/installation/partitioning.md @@ -1,7 +1,5 @@ # Partitioning -## Default Partitioning - Partitions system are configured with a standard schema using LVM, so that they can be possibly changed afterwards. By default the whole space available on the first block device is used and any existing partition is removed. @@ -12,7 +10,10 @@ Alternatively you might set the sysdb attribute `system_disk` with the device na bob node set-attr $FQDN system_disk=md126 ``` -### RHEL7 +It is also possible to customize the partitioning by using the `partitions` attribute on sysdb. See https://git.psi.ch/linux-infra/bob for more details. + + +## RHEL7 The default partition schema for RHEL7 is: - create one primary ``/boot`` partition of 1Gb; @@ -23,20 +24,15 @@ The default partition schema for RHEL7 is: - ``lv_var_log`` of 2 Gb size for ``/var/log``; - ``lv_tmp`` of 2 Gb size for ``/tmp``. -### RHEL8 +## RHEL8 The default partition schema for RHEL8 is: - - create one primary ``/boot`` partition of 1Gb; - - create the ``vg_root`` Volume Group that uses the rest of the disk; - - on ``vg_root`` create the following logical volumes: - - ``lv_root`` of 14 Gb size for ``/root``; - - ``lv_home`` of 2 Gb size for ``/home``; - - ``lv_var`` of 8 Gb size for ``/var``; - - ``lv_var_log`` of 3 Gb size for ``/var/log``; - - ``lv_var_tmp`` of 2 Gb size for ``/var/log``; - - ``lv_tmp`` of 2 Gb size for ``/tmp``. - - -# Custom Partitioning - -It is possible to customize the partitioning by using the `partitions` attribute on sysdb. See https://git.psi.ch/linux-infra/bob for more details. +- create one primary ``/boot`` partition of 1Gb; +- create the ``vg_root`` Volume Group that uses the rest of the disk; +- on ``vg_root`` create the following logical volumes: + - ``lv_root`` of 14 Gb size for ``/root``; + - ``lv_home`` of 2 Gb size for ``/home``; + - ``lv_var`` of 8 Gb size for ``/var``; + - ``lv_var_log`` of 3 Gb size for ``/var/log``; + - ``lv_var_tmp`` of 2 Gb size for ``/var/log``; + - ``lv_tmp`` of 2 Gb size for ``/tmp``. diff --git a/admin-guide/deployment/reinstall.md b/admin-guide/installation/reinstall.md similarity index 100% rename from admin-guide/deployment/reinstall.md rename to admin-guide/installation/reinstall.md