Advanced Kadeploy: Difference between revisions

From Grid5000
Jump to navigation Jump to search
(→‎Deploy on additional disks: Ajout d'un warning)
(→‎Disk partitioning: clarify GPT scheme)
(41 intermediate revisions by 7 users not shown)
Line 3: Line 3:
{{TutorialHeader}}
{{TutorialHeader}}


{{Warning|text=Please mind also reading the [[Environments creation using Kameleon and Puppet]] tutorial, which gives automated mechanisms to build kadeploy environnements}}
{{Warning|text=Please mind also reading the [[Environment creation]] guide, which gives automated mechanisms to build kadeploy environnements}}


= What you need to know before starting =
= What you need to know before starting =
Line 27: Line 27:


== How can I make my own environment? ==
== How can I make my own environment? ==
To create our own environment there are two main ways. One way is to deploy an existing environment and the other way is to create an environment from scratch from a classical ISO installation. In both situations you can customize and save your environment in order to use it again later.
To create our own environment, there are two main ways:
* One way is to deploy an existing environment, customize it and save it with <code class="command">tgz-g5k</code>
* The other one is to built the environment from a recipe, just like the Grid'5000 supported reference environments. See [[Environment creation]].
 
== Disk partitioning ==
 
Environments are deployed on the (first) local disk of each node (each Grid'5000 node is equipped with at least one hard drive). The following partitioning scheme is used:
 
; Legacy / DOS
 
{|
|-
!style="background: lightgrey;"| Device
!style="background: lightgrey;"| Role
|-
| <code>sda1</code>
| Linux swap
|-
| <code>sda2</code>
| Standard environment (default environment installed on nodes)
|-
| <code>sda3</code>
| User's environment (when Kadeploy is used)
|-
| <code>sda4</code>
| MS-DOS extended partition (container for the logical partitions, cannot be used)
|-
| <code>sda5</code>
| Remaining disk space made available in <code class="file">/tmp</code>
|}
 
; GPT / UEFI
 
This new partition scheme is applied to recent clusters that boot using UEFI (as of 2020: "gemini" and "pyxis" at Lyon)
 
{|
|-
!style="background: lightgrey;"| Device
!style="background: lightgrey;"| Role
|-
| <code>sda1</code>
| Linux swap
|-
| <code>sda2</code>
| Standard environment (default environment installed on nodes)
|-
| <code>sda3</code>
| User's environment (when Kadeploy is used)
|-
| <code>sda4</code>
| EFI system partition (used to store boot images)
|-
| <code>sda5</code>
| Remaining disk space made available in <code class="file">/tmp</code>
|}
 
; Notes
 
* Some clusters have more than one local disk. On some clusters, those disks can be reserved apart from the node itself. See [[Disk_reservation]] to find out how to use them.
* Kadeploy allows deployments on other partitions than <code>sda3</code> or even creating a custom partitioning scheme. See below for details.


= Search and deploy an existing environment =
= Search and deploy an existing environment =
Line 33: Line 92:
== Search an environment ==
== Search an environment ==


Grid'5000 maintains several reference environments directly available on any site. These environments are based on various versions of debian. And for each debian version you will find different variants of reference environments.<br>
Grid'5000 maintains several reference environments directly available in all sites. These environments are based on Debian, Ubuntu and Centos.  
They are called ''reference'' environments because they can be used to generate customized environments. You will find different variants of reference environments, depending on which version of debian they are based on.<br>


The description of the reference environments can be found here : {{Link|[[Getting_Started#Deploying_nodes_with_Kadeploy]]}}
For Debian, different variants of reference environments are offered. For Ubuntu and Centos, only environment with a minimal system are offered.


An environment library is maintained on each site in the <code class="dir">/grid5000</code> directory of the <code class="host">frontend</code> node. So all environments available on each site are stored in that directory.
They are called ''reference'' environments because they can be used to generate customized environments.
 
; The description of the reference environments can be found here: {{Link|[[Getting_Started#Deploying_nodes_with_Kadeploy]]}}
 
An environment registry is maintained in each site (see <code class="command">kaenv3</code>), with the associated filesystem images stored in the <code class="dir">/grid5000</code> directory of the <code class="host">frontend</code>.


To deploy a registered environment, you must know its name as registered in the Kadeploy database. It is the first information on the environment description page. This tutorial uses the <code class="env">debian10-x64-base</code> environment.
To deploy a registered environment, you must know its name as registered in the Kadeploy database. It is the first information on the environment description page. This tutorial uses the <code class="env">debian10-x64-base</code> environment.


You can also list all available environment in a site by using the <code class="command">kaenv3</code> command :
You can also list all available environment in a site by using the <code class="command">kaenv3</code> command:
{{term|location=frontend|cmd=<code class="command">kaenv3</code> <code>-l</code>}}
{{term|location=frontend|cmd=<code class="command">kaenv3</code> <code>-l</code>}}
This command lists all public as well as your private environments.
This command lists all public as well as your private environments.


We distinguish three levels of visibility for an environment :
We distinguish three levels of visibility for an environment:


* ''public'': All users can see those environments. Only administrators can tag them this way.
* ''public'': All users can see those environments. Only administrators can tag them this way.
Line 54: Line 116:
* ''private'': The environment is only visible by the user the environment belongs to.
* ''private'': The environment is only visible by the user the environment belongs to.


For example, a shared environment added by user <code class="replace">user</code> is listed this way :
For example, a shared environment added by user <code class="replace">user</code> is listed this way:
{{Term|location=frontend|cmd=<code class="command">kaenv3</code> -l -u <code class="replace">user</code>}}
{{Term|location=frontend|cmd=<code class="command">kaenv3</code> -l -u <code class="replace">user</code>}}


You can also look for a specific version with the <code>--env-version</code> option. All the versions of the environments can be found in <code>/grid5000/images</code>. The version number is the last part of the tgz file.
You can also look for a specific version with the <code>--env-version</code> option. All the versions of the environments can be found in <code>/grid5000/images</code>. The version number is the last part of the tgz file.


For example : <code>debian10-x64-min-2019100414.tgz</code> => it's the min debian10-x64 reference environment version <code>2019100414</code>.
For example: <code>debian10-x64-min-2019100414.tgz</code> => it's the min debian10-x64 reference environment version <code>2019100414</code>.


Being able to reproduce the experiments that are done is a desirable feature. Therefore, you should always try to control as much as possible the environment the experiment is done in. Therefore, we will attempt to check that the environment that was chosen in the environment directory is the one available on a given cluster. On the cluster you would like to deploy, type the following command to print information about an environment :
Being able to reproduce the experiments that are done is a desirable feature. Therefore, you should always try to control as much as possible the environment the experiment is done in. Therefore, we will attempt to check that the environment that was chosen in the environment directory is the one available on a given cluster. On the cluster you would like to deploy, type the following command to print information about an environment:
{{Term|location=frontend|cmd=<code class="command">kaenv3</code> <code>-p</code> <code class="env">debian10-x64-base</code> <code>-u deploy</code>}}
{{Term|location=frontend|cmd=<code class="command">kaenv3</code> <code>-p</code> <code class="env">debian10-x64-base</code> <code>-u deploy</code>}}


Line 93: Line 155:




In order to be able to connect to the node (as <code>root</code>), you must use the <code>-k</code> option and proceed by two ways :
In order to be able to connect to the node (as <code>root</code>), you must use the <code>-k</code> option and proceed by two ways:
* You can either specify the public key that will be copied in <code class=file>/root/.ssh/authorized_keys</code> on the deployed nodes :
* You can either specify the public key that will be copied in <code class=file>/root/.ssh/authorized_keys</code> on the deployed nodes:
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -e debian10-x64-base -f <code class="env">$OAR_FILE_NODES</code> -k ~/.ssh/my_special_key.pub}}
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -e debian10-x64-base -f <code class="env">$OAR_FILE_NODES</code> -k ~/.ssh/my_special_key.pub}}
* Or you can supply the <code>-k</code> option without argument. This will automatically copy your <code class=file>~/.ssh/authorized_keys</code> and replace the <code class=file>/root/.ssh/authorized_keys</code> file on the deployed nodes.  
* Or you can supply the <code>-k</code> option without argument. This will automatically copy your <code class=file>~/.ssh/authorized_keys</code> and replace the <code class=file>/root/.ssh/authorized_keys</code> file on the deployed nodes.  
Line 101: Line 163:
Once kadeploy has run successfully, the allocated node is deployed under <code>debian10-x64-base</code> environment. It will then be possible to tune this environment according to your needs.
Once kadeploy has run successfully, the allocated node is deployed under <code>debian10-x64-base</code> environment. It will then be possible to tune this environment according to your needs.


{{Note|text=It is not necessary here, but you can specify destination partition with the -p option. You can find on the [[Grid5000:Node storage]] page all informations about the partitions table used on G5K}}
{{Note|text=It is not necessary here, but you can specify destination partition with the -p option}}


== Connect to the deployed environment and customize it ==
== Connect to the deployed environment and customize it ==
'''1. Connection'''
;1. Connection


On reference environments managed by the staff, you can use <code>root</code> account for login through <code>ssh</code> (kadeploy checks that sshd is running before declaring a deployment successful). To connect to the node type :
On reference environments managed by the staff, you can use <code>root</code> account for login through <code>ssh</code> (kadeploy checks that sshd is running before declaring a deployment successful). To connect to the node type:
{{Term|location=frontend|cmd=<code class="command">ssh</code> root@<code class="replace">node.site</code>.grid5000.fr}}
{{Term|location=frontend|cmd=<code class="command">ssh</code> root@<code class="replace">node.site</code>.grid5000.fr}}


In case this doesn't work, please take a look at the [[FAQ#Deployment related issues|kadeploy section]] of the [[FAQ|Sidebar > FAQ]]
In case this doesn't work, please take a look at the [[FAQ#Deployment related issues|kadeploy section]] of the [[FAQ|Sidebar > FAQ]]


'''2. Adding software to an environment'''
;2. Adding software to an environment


''Where you learn to install software using the package repository of your distribution on Grid'5000''
''Where you learn to install software using the package repository of your distribution on Grid'5000''
Line 122: Line 184:
The first step to create an environment is to create an archive of the node you just customized. Because of the various implementations of the <code class="dir">/dev</code> filesystem tree, this can be a more or less complex operation.  
The first step to create an environment is to create an archive of the node you just customized. Because of the various implementations of the <code class="dir">/dev</code> filesystem tree, this can be a more or less complex operation.  


'''1. Use the provided tools'''
;1. Use the provided tools


You can use <code class=command>tgz-g5k</code> to extract a Grid'5000 environment tarball from a running node.
You can use <code class=command>tgz-g5k</code> to extract a Grid'5000 environment tarball from a running node.
Line 135: Line 197:
*You can find more information on <code class=command>tgz-g5k</code> (e.g., available options, command line examples) by executing <code class=command>tgz-g5k -h</code>. Some implementation details are also available on the man page (<code class=command>man tgz-g5k</code>).}}
*You can find more information on <code class=command>tgz-g5k</code> (e.g., available options, command line examples) by executing <code class=command>tgz-g5k -h</code>. Some implementation details are also available on the man page (<code class=command>man tgz-g5k</code>).}}


'''2. Describe the newly created environment for deployments'''
;2. Describe the newly created environment for deployments


Kadeploy3 works using an environment description. The easiest way to create a description for your new environment is to change the description of the environment it is based on. We have based this tutorial on the <code>debian10-x64-base</code> environment of user <code>deploy</code>. We therefore print its description to a file that will be used as a good basis:
Kadeploy3 works using an environment description. The easiest way to create a description for your new environment is to change the description of the environment it is based on. We have based this tutorial on the <code>debian10-x64-base</code> environment of user <code>deploy</code>. We therefore print its description to a file that will be used as a good basis:
Line 153: Line 215:
With <code class=command>kaenv3</code> command, you can manage your environments at your ease. Please refer to its documentation for an overview of its features.
With <code class=command>kaenv3</code> command, you can manage your environments at your ease. Please refer to its documentation for an overview of its features.


= Deploy an environment from a classical ISO installation =
= Deployment options =
== Multisite deployment ==
In order to achieve a deployment on nodes from differents sites, you can use the multiserver option of kadeploy, using the <code class="command">-M</code>
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> '''-M''' -f <code class="file">file_with_all_nodes</code> -e <code class="replace">debian10-x64-std</code>}}
 
== Deploy on other partition of disk(s) ==
Kadeploy default handling of partitions may be too limited for some usage. One may need to use disks differently (e.g. to deploy our environment in an optimal way). Kadeploy offers several options to simply deploy on another existing partition (sda2 or sda5), or if required to repartition disks entirely and/or use several disks (on nodes with many disks).
 
=== Deploy on sda2 or sda5 ===
First, as this kind of deployment will break node standard operation, you must tell to OAR that it should be redeployed entirely after the reservation with the <code class="command">-t destructive</code> option:
{{Term|location=frontend|cmd=<code class="command">oarsub</code> -t deploy -t destructive -l nodes=1,walltime=1 -p "cluster='hercule'" -I}}
Then you can deploy on sda2 or sda5 with the <code class="command">-p 2</code> or <code class="command">-p 5</code> option:
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -e debian10-x64-nfs -f $OAR_NODEFILE -p <code class="replace">2</code> -k}}


First of all, this method is OS independant, so you can create Kadeploy3 tgz (linux based systems) or ddgz (other systems) images for any kind of OS from a CD/DVD ISO.
=== Deploy on additional disks ===
{{Warning|text=Currently broken}}
First, as this kind of deployment will break node standard operation, you must tell to OAR that it should be redeployed entirely after the reservation with the <code class="command">-t destructive</code> option:
{{Term|location=frontend|cmd=<code class="command">oarsub</code> -t deploy -t destructive -l nodes=1,walltime=1 -p "cluster='hercule'" -I}}
Then you can deploy on an additional disk such as sdb with the <code class="command">-b sdb</code> option:
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -e debian10-x64-base -f $OAR_NODEFILE -b <code class="replace">sdb</code> -k}}


This procedure is based on the usage of virtualization (KVM) mechanism to boot the CD/DVD iso of the OS installer. The system will be installed on a physical partition of a node and then copied as a Kadeploy3 system image.
Disks can also be handled differently by modifying the deployment automata, see below.


To be sure the installed system will be bootable, we will make the OS installer install the system on the Grid'5000 deployment partition (sda3).
= Tuning the Kadeploy3 deployment workflow =


To make this possible, we will deploy the hypervisor's system on the temporary partition and then install the system on the deployment partition.
<code class="command">kadeploy3</code> allows to fully modify the deployment workflow.


== Preparation ==
First of all you have to understand the different steps of a deployment. There are 3 macro-steps:
* Download your the CD/DVD ISO of your OS installer (say <code class="replace">OS_ISO</code>) and upload it on the frontend of the target site [[SSH#Copying_files|help here]]
# <code class="env">SetDeploymentEnv</code>: this step aims at setting up the deployment environment that contains all the required tools to perform a deployment ;
{{Term|location=local|cmd=<code class="command">scp</code> <code class="replace">OS_ISO USERNAME</code>@<code class="host">access</code>.<code class="host">grid5000.fr</code>:<code class="replace">SITE</code>/}}
# <code class="env">BroadcastEnv</code>: this step aims at broadcasting the new environment to the nodes and writing it to disk;
# <code class="env">BootNewEnv</code>: this step aims at rebooting the nodes on their new environment.


* Make a reservation with 1 node, with the deployment mode and the destructive mode (to be able to deploy on the temporary partition), two hours should be enough.
<code class="command">kadeploy3</code> provides several implementations for each of those 3 macro-steps. You can consult that list in the kadeploy3 page.
{{Term|location=frontend|cmd=<code class="command">oarsub</code> -I -t deploy -t destructive -l nodes=1,walltime=<code class="replace">2</code>}}
In Grid'5000, we use the following steps by default in all our clusters:
* <code class="env">SetDeploymentEnv</code> -> <code class=file>SetDeploymentEnvUntrusted</code>: use an embedded deployment environment
* <code class="env">BroadcastEnv</code> -> <code class=file>BroadcastEnvKascade</code>: use the Kascade tool to broadcast the environment
* <code class="env">BootNewEnv</code> -> <code class=file>BootNewEnvKexec</code>: the nodes use kexec to reboot (if it fails, a <code class=file>BootNewEnvClassical</code>, classical reboot, will be performed)


* Deploy a minimal system on the node's temporary partition, use your ssh key (since Grid'5000 is more Debian friendly, let's say Debian 10 Buster)
Each one of these implementations is divided in micro steps. You can can see the name of those micro-steps if you use the kadeploy3 option <code>--verbose-level 4</code>. And to see what is actually executed during those micro-steps you can add the debug option of kadeploy3 <code>-d</code>
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -e <code class="env">debian10-x64-min</code> -p 5 -k -f $OAR_NODEFILE}}


* Connect to the node and install the needed packages
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -f <code class=file>$OAR_FILE_NODES</code> -k -e debian10-x64-base --verbose-level 4 -d  &#62; <code class=file>~/kadeploy3_steps</code>}}
{{Term|location=frontend|cmd=<code class="command">ssh</code> root@<code class="replace">NODE</code>}}


== Run the CD/DVD OS installer using KVM/VNC ==
This command will store the kadeploy3 standard output in the file <code class=file>~/kadeploy3_steps</code>. Lets analyse its content:  
* Preparation
*: Copy the OS's ISO to the node
{{Term|location=frontend|cmd=<code class="command">scp</code> <code class="replace">OS_ISO</code> root@<code class="replace">NODE</code>:}}
*: Connect to the node and install ''tigervnc-viewer'', ''parted'' and ''kvm'' on the system.
First update the packages definition
{{Term|location=NODE|cmd=<code class="command">apt-get</code> -y update}}
Then install the needed packages
{{Term|location=NODE|cmd=<code class="command">apt-get</code> install -y tigervnc-viewer parted kvm}}
*: Clean the old system's partition <code class="file">/dev/sda3</code>
{{Term|location=NODE|cmd=<code class="command">echo</code><nowiki> -e 'd\n3\nn\np\n\n\nt\n3\n0\nw\n' | fdisk /dev/sda && sync && partprobe /dev/sda</nowiki>}}
* Launch the virtual machine, booting on the OS's ISO, using VNC output'''
{{Term|location=NODE|cmd=<code class="command">kvm</code> -drive file=<code class="file">/dev/sda</code> -cpu host -m 1024 -net nic,model=e1000 -net user -k fr -vnc :1 -boot d -cdrom <code class="replace">OS_ISO</code>}}
{{Note|text=This is currently hard to build an image from KVM for nodes that network devices need specific drivers (bnx2, ...)}}


To be sure your node network device is compatible with the ''e1000e'' driver you can check the API using:
{{Term|location=frontend|cmd=<code class="command">grep</code> "Time in" <code class=file>~/kadeploy3_steps</code>}}
{{Term|location=frontend|cmd=<code class="command">curl</code> -s -k <nowiki>https://api.grid5000.fr/stable/grid5000/sites/</nowiki><code class="replace">SITE</code>/clusters/<code clas="replace">CLUSTERS</code>/nodes/<code class="replace">NODE</code>}}
(The node has to be specified by basename: ''griffon-42.nancy.grid5000.fr'' &rarr; ''griffon-42'')
* Connect to the frontend using SSH X11 forwarding and get the screen of our virtual machine using VNC
{{Term|location=laptop|cmd=<code class="command">ssh</code> -Y root@<code class="replace">NODE</code>.<code class="replace">SITE</code>.g5k 'vncviewer :1'}}
{{Note|text=If your OS installer is changing the screen resolution, your ''vncviewer'' will be closed, you'll just have to relaunch the command to get the screen back}}
{{Warning|text=Installation process IMPORTANT instructions:
*You MUST not format the <code class="file">/dev/sda</code> disk. When you are asked about partitioning the disk, select ''manual'' (and not ''guided'').
*You MUST install your system on <code class="file">/dev/sda3</code>. Create the partition, if it does not exist. The mount point of this partition should be "/"<br>
*The system size of this partition should be limited to Grid'5000's deployment partition default size (16GiB)<br>
*You must install an SSH server<br>
*A bootloader should be installed on the partition <code class="file">/dev/sda3</code> and not on the MBR<br>}}
* Install the system
{{Note|text=after the installation process, the virtual machine will fail to boot, it's normal. You can close ''vncviewer'' and ''kvm''}}


== Customize the OS ==
This command will print on the terminal all the micro-steps executed during the deployment process, and the time spent for each execution. Here are the micro-steps that you should see:
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">switch_pxe</code>: Configures the PXE server so that this node will boot on an environment that contains all the required tools to perform the deployment,
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">reboot</code>: Sends a reboot signal to the node
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">wait_reboot</code>: Waits for the node to restart.
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">send_key_in_deploy_env</code>: Sends kadeploy's user's ssh public key into the node's authorized_keys to ease the following ssh connections,
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">create_partition_table</code>: Creates the partition table
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">format_deploy_part</code>: Format the partition where your environment will be installed. This partition is by default /dev/sda3
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">mount_deploy_part</code>: Mounts the deployment partition in a local directory.
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">format_tmp_part</code>: Format the partition defined as tmp (by default, /dev/sda5)
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">format_swap_part</code>: Format the swap partition
# <code class=file>BroadcastEnvKascade</code>-<code class="replace">send_environment</code>: Sends your environments into the node and untar it into the deployment partition.
# <code class=file>BroadcastEnvKascade</code>-<code class="replace">manage_admin_post_install</code>: Execute post installation instructions defined by the site admins, in general to adapt to the specificities of the cluster: console baud rate, Infiniband,...
# <code class=file>BroadcastEnvKascade</code>-<code class="replace">manage_user_post_install</code>: Execute user defined post installation instructions to automatically configure its node depending on its cluster, site, network capabilities, disk capabilities,...
# <code class=file>BroadcastEnvKascade</code>-<code class="replace">send_key</code>: Sends the user public ssh key(s) to the node (if the user specified it with the option <code>-k</code>).
# <code class=file>BroadcastEnvKascade</code>-<code class="replace">install_bootloader</code>: Properly configures the bootloader
# <code class=file>BootNewEnvKexec</code>-<code class="replace">switch_pxe</code>: Configure the PXE server so that this node will boot on the partition where your environment has been installed
# <code class=file>BootNewEnvKexec</code>-<code class="replace">umount_deploy_part</code>: Umount the deployment partition from the directory where it has been mounted during the step 7.
# <code class=file>BootNewEnvKexec</code>-<code class="replace">mount_deploy_part</code>: ReMount the deployment partition
# <code class=file>BootNewEnvKexec</code>-<code class="replace">kexec</code>: Perform a kexec reboot on the node
# <code class=file>BootNewEnvKexec</code>-<code class="replace">set_vlan</code>: Properly configure the node's VLAN
# <code class=file>BootNewEnvKexec</code>-<code class="replace">wait_reboot</code>: Wait for the node to be up.


* Create the mounting point directory
That is it. You now know all the default micro-steps used to deploy your environments.
{{Term|location=frontend|cmd=<code class="command">ssh</code> root@<code class="replace">NODE</code> '<code class="command>mkdir</code> -p <code class="file">/mnt/myos</code>'}}
* Mount the partition
{{Term|location=frontend|cmd=<code class="command">ssh</code> root@<code class="replace">NODE</code> '<code class="command>partprobe</code>'}}
{{Term|location=frontend|cmd=<code class="command">ssh</code> root@<code class="replace">NODE</code> '<code class="command>mount</code> <code class="file">/dev/sda3 /mnt/myos</code>'}}
{{Note|text=If this command fails, you can try to use this command first: ''partprobe /dev/sda''}}
* If you want to :
** add a custom script that dynamically setup your node's hostname, you can take a look at  /mnt/myos/etc/dhcp/dhclient-enter-hooks.d/.
** disable selinux: example for Centos, put "SELINUX=disable" in /mnt/myos/etc/selinux/config
** modifying the DNS by editing  /etc/resolv.conf
* Unmount the partition
{{Term|location=frontend|cmd=<code class="command">ssh</code> root@<code class="replace">NODE</code> '<code class="command>umount</code> <code class="file">/mnt/myos</code>'}}


== Create a Kadeploy3 image of the filesystem of our OS ==
== Adjusting timeout for some environments ==
Since <code class="command">kadeploy3</code> provides multiple macro-steps and micro-steps, its is important to detect when a step in failing its execution. This error detection is done by using timeout on each step. When a timeout is reached, the nodes that have not completed the given step are discarded from the deployment process.<br>
The value of those timeouts varies from one cluster to another since they depend on the hardware configuration (network speed, hard disk speed, reboot speed, ...).
All defaults timeouts are entered in the configurations files on the kadeploy3 server. But you can consult the default timeouts of each macro-steps by using the command <code class="command">kastat3</code>


* Save the filesystem in a tgz archive with tgz-g5k (tgz-g5k documentation is available [[TGZ-G5K|here]])
{{Term|location=frontend|cmd=<code class="command">kastat3</code> -I}}
{{Term|location=frontend|cmd=<code class="command">tgz-g5k</code> -m <code class="replace">NODE</code> -r /dev/sda3 -f <code class="replace">IMAGE_FILE</code>.tgz}}
  Kadeploy server configuration:
<!--*FIXME (<b>released in tgz-g5k 1.0.9</b>):
  Custom PXE boot method: PXElinux
{{Term|location=frontend|cmd=<code class="command">ssh</code> root@<code class="replace">NODE</code> '<code class="command">wget</code> -q -O - <nowiki>http://public.nancy.grid5000.fr/~lsarzyniec/kaimg/tgz-g5k | bash -s - --root /mnt/myos</nowiki>' > <code class="replace">IMAGE_FILE</code>.tgz}}
  Automata configuration:
-->
    hercule:
* Create an environment description file <code class="replace">IMAGE_DESC_FILE</code> such as:
      SetDeploymentEnv: SetDeploymentEnvUntrusted,1,600
<pre>
      BroadcastEnv: BroadcastEnvKascade,0,1000
---
      BootNewEnv: BootNewEnvKexec,0,180; BootNewEnvHardReboot,0,900
name: IMAGE_NAME
    nova:
version: 1
      SetDeploymentEnv: SetDeploymentEnvUntrusted,1,600
description: My OS Image
      BroadcastEnv: BroadcastEnvKascade,0,1000
author: me@domain.tld
      BootNewEnv: BootNewEnvKexec,0,150; BootNewEnvHardReboot,0,600
visibility: private
   ...
destructive: false
os: linux
image:  
   kind: tar
  compression: gzip
  file: /path/to/IMAGE_FILE.tgz
postinstalls:
- archive: server:///grid5000/postinstalls/g5k-postinstall.tgz
  compression: gzip
  script: g5k-postinstall --net debian
boot:
  kernel: /path/to/the/kernel/in/the/image
  initrd: /path/to/the/initrd/in/the/image
multipart: false
filesystem: ext4
partition_type: 0x83
</pre>


{{Note|text=You can use Grid'5000 files for the postinstall}}
{{Note|
text=For linux systems, most of times the path to the kernel file is <code class="file">/vmlinuz</code> and the path to the initrd is <code class="file">/initrd.img</code>. You can locate those files by connecting to <code class="replace">NODE</code> (like in the previous section using <code class="command">mount</code>) and checking the <code class="file">/mnt/myos</code> directory.}}


* Test it !
<code class="command">kadeploy3</code> allow users to change timeouts in the command line. In some cases, when you try to deploy an environment with a large tarball or with a post-install that lasts too long, you may get discarded nodes. This false positive behavior can be avoided by manually modifying the timeouts for each step at the deployment time.
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -a <code class="replace">IMAGE_DESC_FILE</code> -m <code class="replace">NODE</code> -k}}


* Add it to kadeploy (so that you can use the parameter -e <code class="replace">IMAGE_NAME</code> like the default g5k environments)
For instance, in our previous example, the timeout of each steps are:
* <code class=file>SetDeploymentEnvUntrusted</code>: 143
* <code class=file>BroadcastEnvKascade</code>: 111
* <code class=file>BootNewEnvKexec</code>: 33


{{Term|location=frontend|cmd=<code class="command">kaenv3</code> -a <code class="replace">IMAGE_DESC_FILE</code>}}
You can increase the timeout of the second step to 1200 seconds with the following command:
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -e my_big_env -f <code class="env">$OAR_FILE_NODES</code> -k --force-steps "SetDeploymentEnv&#124;SetDeploymentEnvUntrusted:1:450&BroadcastEnv&#124;BroadcastEnvKascade:1:1200&BootNewEnv&#124;BootNewEnvClassical:1:400"}}


= Use disk(s) as I want =
== Set Break-Point during deployment ==
In some cases, kadeploy default handling of partitions is too limited and we need to use disks as we want (e.g. to deploy our environment in an optimal way). To do that there are two main ways:
As mentioned in the section above, a deployment is a succession of micro steps that can be consulted and modified.<br>
* simply deploy on another existing partition (sda2 or sda5)
Moreover, <code class="command">kadeploy3</code> allows user to set a break-point during deployment.  
* repartition disks entirely and/or use several disks (such as sdb or sdc on hercule cluster)


== Deploy on sda2 or sda5 ==
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -f <code class="env">$OAR_FILE_NODES</code> -k -e debian10-x64-base --verbose-level 4  -d --breakpoint <code class=file>BroadcastEnvKascade</code>:<code class="replace">manage_user_post_install</code>}}
First, as this kind of deployment will break node standard operation, you must tell to OAR that it should be redeployed entirely after the reservation with the <code class="command">-t destructive</code> option:
{{Term|location=frontend|cmd=<code class="command">oarsub</code> -t deploy -t destructive -l nodes=1,walltime=1 -p "cluster='hercule'" -I}}
Then you can deploy on sda2 or sda5 with the <code class="command">-p [2,5]</code> option:
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -e debian10-x64-nfs -f $OAR_NODEFILE -p <code class="replace">2</code> -k}}


== Deploy on additional disks ==
This command can be used for debugging purpose. It performs a deployment with the maximum verbose level and it asks to stop the deployment workflow just '''''before''''' executing the ''manage_user_post_install''  micro-step of the ''BroadcastEnvKascade''  macro-step. Thus you will be able to connect in the deployment environment and to manually run the user post install script to debug it.


{{Warning|text=Bug en cours https://intranet.grid5000.fr/bugzilla/show_bug.cgi?id=11036}}
{{Warning|text=At the current state of <code class="command">kadeploy3</code>, it is not possible to resume the deployment from the break-point step. Thus you will have to redeploy you environment from the first step. This feature will be implemented in future version of <code class="command">kadeploy3</code>.}}
First, as this kind of deployment will break node standard operation, you must tell to OAR that it should be redeployed entirely after the reservation with the <code class="command">-t destructive</code> option:
{{Term|location=frontend|cmd=<code class="command">oarsub</code> -t deploy -t destructive -l nodes=1,walltime=1 -p "cluster='hercule'" -I}}
Then you can deploy on an additional disk such as sdb with the <code class="command">-b sdb</code> option:
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -e debian10-x64-base -f $OAR_NODEFILE -b <code class="replace">sdb</code> -k}}


== Format additional disks ==
== Modify the deployment workflow with custom operations ==
In Kadeploy3, we can easily customize the deployment's automata. It's possible to add custom ''pre, post or substitute operations'' to each steps. In a custom operation it's possible to: ''send'' a file, ''execute'' a command or ''run'' a script.
In Kadeploy3, we can easily customize the deployment's automata. It's possible to add custom ''pre, post or substitute operations'' to each steps. In a custom operation it's possible to: ''send'' a file, ''execute'' a command or ''run'' a script.


This feature is explained in Kadeploy3's documentation (available on [https://gforge.inria.fr/frs/?group_id=2026 Kadeploy3's website]) in the section ''4.2.2, Use Case 10'' and ''4.7''.
This feature in explained in Kadeploy3's documentation (available on [https://gforge.inria.fr/frs/?group_id=2026 Kadeploy3's website]) in the section ''4.2.2, Use Case 10'' and ''4.7''.


This is illustrated in the following sub-sections.
{{Note|text=When running a custom script, Kadeploy will export different variables, you can get a list of them by running <code class="command">kadeploy3 -I</code>.<br>A description of each of this variables is available in Kadeploy3's documentation ([https://gforge.inria.fr/frs/?group_id=2026 on Kadeploy3 website]) in the section ''4.4''}}
=== Format additional disks ===
In this example, we will add some custom operations to the deployment workflow: our nodes have two additional hard disks and we want them to be formated during the deployment process.
In this example, we will add some custom operations to the deployment workflow: our nodes have two additional hard disks and we want them to be formated during the deployment process.


Line 298: Line 344:
The three following sections describe how to perform such an operation.
The three following sections describe how to perform such an operation.


'''1. Make the reservation in destructive mode'''
;1. Make the reservation in destructive mode


First of all, when you do your reservation, you must tell to OAR that it should redeploy the node entirely after the reservation with the <code class="command">-t destructive</code> parameter:
First of all, when you do your reservation, you must tell to OAR that it should redeploy the node entirely after the reservation with the <code class="command">-t destructive</code> parameter:
{{Term|location=frontend|cmd=<code class="command">oarsub</code> -t deploy -t destructive -l nodes=1,walltime=2 -p "cluster='hercule'" -I}}
{{Term|location=frontend|cmd=<code class="command">oarsub</code> -t deploy -t destructive -l nodes=1,walltime=2 -p "cluster='hercule'" -I}}


'''2. Describe the custom operations'''
;2. Describe the custom operations


After that you have to create a file that describe the custom operations you want to be performed during the deployment.
After that you have to create a file that describe the custom operations you want to be performed during the deployment.
In our example we will first repartition the additional disks (using parted) and then format them (using the script format.sh).
In our example we will first repartition the additional disks (using parted) and then format them (using the script format.sh).
* The operation description file (let's say '''custom-partitioning.yml''') should look like something like this:
* The operation description file (let's say '''custom-partitioning.yml''') should look like something like this:
<pre>
<syntaxhighlight lang="yaml">
---
---
# Our custom steps should be performed during the SetDeploymentEnv macro-step
# Our custom steps should be performed during the SetDeploymentEnv macro-step
Line 342: Line 388:
           name: format_disks
           name: format_disks
           file: format.sh
           file: format.sh
</pre>
</syntaxhighlight>
* The file '''sdb.parted''' will look like something like this:
* The file '''sdb.parted''' will look like something like this:
<pre>
<syntaxhighlight lang="bash">
mklabel msdos
mklabel msdos
u GB mkpart primary ext4 0% 100%
u GB mkpart primary ext4 0% 100%
align-check optimal 1
align-check optimal 1
</pre>
</syntaxhighlight>
* The file '''sdc.parted''' will look like something like this:
* The file '''sdc.parted''' will look like something like this:
<pre>
<syntaxhighlight lang="bash">
mklabel msdos
mklabel msdos
u GB mkpart primary ext2 0% 100%
u GB mkpart primary ext2 0% 100%
align-check optimal 1
align-check optimal 1
</pre>
</syntaxhighlight>
* The file '''format.sh''' will look like something like this:
* The file '''format.sh''' will look like something like this:
<pre>
<syntaxhighlight lang="bash">
#!/bin/sh
#!/bin/sh
set -e
set -e
Line 363: Line 409:
# formating /dev/sdc
# formating /dev/sdc
mkfs -t ext2 -b 4096 -O sparse_super,filetype,resize_inode,dir_index -q /dev/sdc1
mkfs -t ext2 -b 4096 -O sparse_super,filetype,resize_inode,dir_index -q /dev/sdc1
</pre>
</syntaxhighlight>


'''3. Run the deployment'''
;3. Run the deployment


Now you can deploy you environment with this custom operation:
Now you can deploy you environment with this custom operation:
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -e debian10-x64-min -f $OAR_NODE_FILE -k --custom-steps ./custom-partitioning.yml}}
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -e debian10-x64-min -f $OAR_NODE_FILE -k --custom-steps ./custom-partitioning.yml}}
{{Warning|text=In some cases you should increase the step's timeout (for some long formatting for example) see [[Advanced_Kadeploy#Adjusting timeout for some environments]] for details.}}
{{Warning|text=In some cases you should increase the step timeout (for some long formatting for example) see [[Advanced_Kadeploy#Adjusting timeout for some environments]] for details.}}


'''Note:''' Both partitions are not mounted on boot. To mount those partitions you should do:
'''Note:''' Both partitions are not mounted on boot. To mount those partitions you should do:
Line 377: Line 423:
{{Term|location=NODE|cmd=<code class="command">mount</code> /dev/sdc1 /media/data2}}
{{Term|location=NODE|cmd=<code class="command">mount</code> /dev/sdc1 /media/data2}}


== Use a custom partitioning scheme ==
=== Use a custom partitioning scheme ===
In Kadeploy3, we can customize the deployment's automata. It's possible to add custom ''pre, post or substitute operations'' to each steps. In a custom operation it's possible to: ''send'' a file, ''execute'' a command or ''run'' a script.
==== Example 1: Deploy on the whole disk ====
In this example, we will modify the deployment workflow to deploy the system on a unique disk partition ( '/' on sda1 )
 
;1. Make the reservation in destructive mode
 
As you will change partitioning of the disk, you must tell to OAR that it should redeploy the node entirely after the reservation with the <code class="command">-t destructive</code> parameter:
{{Term|location=frontend|cmd=<code class="command">oarsub</code> -t deploy -t destructive -l nodes=1,walltime=2 -I}}
 
;2. Describe the custom operations
 
After that you have to create a file that describe the custom operations you want to be performed during the deployment.
In this example we will create our custom partitioning scheme and bypass some steps that are not necessary to deploy the system on a unique partition.
 
* The operation description file (let's say '''custom-partitioning.yml''') should look like something like this:
<syntaxhighlight lang="yaml">
---
# Our custom steps should be performed during the SetDeploymentEnv macro-step
SetDeploymentEnvUntrusted:
  # Custom partitioning step that is substituted to the create_partition_table micro-step
  create_partition_table:
    substitute:
      # We send a file on the node
      - action: send
        file: map.parted
        # The variable $KADEPLOY_TMP_DIR will be substituted by Kadeploy
        destination: $KADEPLOY_TMP_DIR
        name: send_partition_map
      # Then we execute the parted command using the previously sent file
      - action: exec
        name: partitioning
        # The variable $KADEPLOY_TMP_DIR will be substituted by Kadeploy
        command: parted -a optimal /dev/sda --script $(cat $KADEPLOY_TMP_DIR/map.parted)
# Hack to disable useless steps
  format_tmp_part:
    substitute:
      - action: exec
        name: remove_format_tmp_part_step
        command: /bin/true
  format_swap_part:
    substitute:
      - action: exec
        name: remove_format_swap_part_step
        command: /bin/true
</syntaxhighlight>
 
* The file '''map.parted''', which will be passed to '''parted''', will look like this:
<syntaxhighlight lang="bash">
mklabel gpt
mkpart partition-system ext4 0% 100%
toggle 1 boot
align-check optimal 1
</syntaxhighlight>
 
;3. Customize the environment's postinstall
In order for our new partitions to be mounted at boot time we will modify the Grid'5000 postinstall files.
 
* Create and go in your public directory:
{{Term|location=frontend|cmd=mkdir public/custom-postinstall && cd public/custom-postinstall}}
* Then decompress the postinstall archive:
{{Term|location=frontend|cmd=<code class="command">tar</code> xzf <code class="replace">/grid5000/postinstalls/g5k-postinstall.tgz</code>}}
* Add your custom /etc/fstab file in this directory, named '''fstab''':
<syntaxhighlight lang="bash">
/dev/sda1      /          ext4    defaults 1      2
</syntaxhighlight>
When you will pass "--fstab custom" option to the postinstall, it will copy this file in /etc/fstab
* Regenerate the postinstall archive:
{{Term|location=frontend|cmd=<code class="command">tar</code> -czvf <code class="replace">~/public/g5k-postinstall-custom.tgz</code> *}}
* Make some cleanup:
* Create the environment's description file (let's say '''custom-env.dsc''') based on the reference one:
** use kaenv3 -p debian10-x64-base to have an example of environment description.
Your '''custom-env.dsc''' should look like this:
<syntaxhighlight lang="yaml">
---
name: custom-env
version: 1
description: Custom env based on Debian 10
author: me@domain.tld
visibility: shared
destructive: true
os: linux
image:
  file: server:///grid5000/images/debian10-x64-base-2020012812.tgz
  kind: tar
  compression: gzip
postinstalls:
- archive: http://public/~<login>/g5k-postinstall-custom.tgz
  compression: gzip
  script: g5k-postinstall --net debian --fstab custom
boot:
  kernel: "/vmlinuz"
  initrd: "/initrd.img"
filesystem: ext4
partition_type: 131
multipart: false
</syntaxhighlight>
 
;4. Run the deployment
 
Finally, we deploy our custom environment with your custom operations:
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -a custom-env.dsc -f $OAR_NODE_FILE -p 1 -k --custom-steps custom-partitioning.yml}}
{{Note|text=In some case you should increase the step timeout (for some long formatting for example) see [[Advanced_Kadeploy#Adjusting timeout for some environments]] for details.}}
 
==== Example 2: Deploy on multiple partitions ====
In this example, we will modify the deployment workflow: a different partition will be used for each of the ''/'', ''/home'', ''/opt'' and ''/tmp'' directories.
In this example, we will modify the deployment workflow: a different partition will be used for each of the ''/'', ''/home'', ''/opt'' and ''/tmp'' directories.
Imagine that you want to make your own partitioning scheme like that:
Imagine that you want to make your own partitioning scheme like that:
Line 389: Line 537:
| / || /dev/sda2 || 18G || ext4
| / || /dev/sda2 || 18G || ext4
|-
|-
| /home || /dev/sda3 || 30G || ext4
| /var || /dev/sda3 || 30G || ext4
|-
|-
| /opt || /dev/sda4 || 20G || ext4
| /opt || /dev/sda4 || 20G || ext4
Line 398: Line 546:
The four following sections describe how to perform such an operation.
The four following sections describe how to perform such an operation.


'''1. Make the reservation in destructive mode'''
;1. Make the reservation in destructive mode


First of all, when you do your reservation, you must tell to OAR that it should redeploy the node entirely after the reservation with the <code class="command">-t destructive</code> parameter:
First of all, when you do your reservation, you must tell to OAR that it should redeploy the node entirely after the reservation with the <code class="command">-t destructive</code> parameter:
{{Term|location=frontend|cmd=<code class="command">oarsub</code> -t deploy -t destructive -l nodes=1,walltime=2 -I}}
{{Term|location=frontend|cmd=<code class="command">oarsub</code> -t deploy -t destructive -l nodes=1,walltime=2 -I}}
'''2. Describe the custom operations'''
 
;2. Describe the custom operations


After that you have to create a file that describe the custom operations you want to be performed during the deployment.
After that you have to create a file that describe the custom operations you want to be performed during the deployment.
Line 408: Line 557:


* The operation description file (let's say '''custom-partitioning.yml''') should look like something like this:
* The operation description file (let's say '''custom-partitioning.yml''') should look like something like this:
<pre>
<syntaxhighlight lang="yaml">
---
---
# Our custom steps should be performed during the SetDeploymentEnv macro-step
# Our custom steps should be performed during the SetDeploymentEnv macro-step
Line 451: Line 600:
         name: remove_format_swap_part_step
         name: remove_format_swap_part_step
         command: /bin/true
         command: /bin/true
</pre>
</syntaxhighlight>
{{Note|text=In order for Kadeploy to be able to perform the installation correctly, every partitions have to be mounted before the installation process which is done in the macro-step BroadcastEnv}}
{{Note|text=In order for Kadeploy to be able to perform the installation correctly, every partitions have to be mounted before the installation process which is done in the macro-step BroadcastEnv}}
* The file '''map.parted''' will look like something like this:
* The file '''map.parted''' will look like something like this:
<pre>
<syntaxhighlight lang="bash">
mklabel gpt
mklabel gpt
u GB mkpart partition-swap linux-swap 0% 2
u GB mkpart partition-swap linux-swap 0% 2
u GB mkpart partition-system ext4 2 20
u GB mkpart partition-system ext4 2 20
u GB mkpart partition-home ext4 20 50
u GB mkpart partition-var ext4 20 50
u GB mkpart partition-opt ext4 50 70
u GB mkpart partition-opt ext4 50 70
u GB mkpart partition-tmp ext4 70 100%
u GB mkpart partition-tmp ext4 70 100%
Line 467: Line 616:
align-check optimal 4
align-check optimal 4
align-check optimal 5
align-check optimal 5
</pre>
</syntaxhighlight>


* The file '''format.sh''' will look like something like this:
* The file '''format.sh''' will look like something like this:
<pre>
<syntaxhighlight lang="bash">
#!/bin/sh
#!/bin/sh
set -e
set -e
Line 480: Line 629:
mkswap ${KADEPLOY_BLOCK_DEVICE}1
mkswap ${KADEPLOY_BLOCK_DEVICE}1
# / will be formated by Kadeploy since we will precise the -p 2 option
# / will be formated by Kadeploy since we will precise the -p 2 option
# formating /home
# formating /var
mkfs -t ext4 -b ${ext4_blocksize} -O ${mkfs_opts} -q ${KADEPLOY_BLOCK_DEVICE}3
mkfs -t ext4 -b ${ext4_blocksize} -O ${mkfs_opts} -q ${KADEPLOY_BLOCK_DEVICE}3
# formating /opt
# formating /opt
Line 486: Line 635:
# formating /tmp
# formating /tmp
mkfs -t ext4 -b ${ext4_blocksize} -O ${mkfs_opts} -q ${KADEPLOY_BLOCK_DEVICE}5
mkfs -t ext4 -b ${ext4_blocksize} -O ${mkfs_opts} -q ${KADEPLOY_BLOCK_DEVICE}5
</pre>
</syntaxhighlight>
{{Note|text=When running a custom script, Kadeploy will export different variables, you can get a list of them by running "kadeploy -i".}}
{{Note|text=When running a custom script, Kadeploy will export different variables, you can get a list of them by running "kadeploy -i".}}
* The file '''mount.sh''' will look like something like this:
* The file '''mount.sh''' will look like something like this:
<pre>
<syntaxhighlight lang="bash">
#!/bin/sh
#!/bin/sh
set -e
set -e


# / will be mounted in ${KADEPLOY_ENV_EXTRACTION_DIR} by Kadeploy
# / will be mounted in ${KADEPLOY_ENV_EXTRACTION_DIR} by Kadeploy
# mount /home
# mount /var
mkdir ${KADEPLOY_ENV_EXTRACTION_DIR}/home
mkdir ${KADEPLOY_ENV_EXTRACTION_DIR}/var
mount ${KADEPLOY_BLOCK_DEVICE}3 ${KADEPLOY_ENV_EXTRACTION_DIR}/home/
mount ${KADEPLOY_BLOCK_DEVICE}3 ${KADEPLOY_ENV_EXTRACTION_DIR}/var/
# mount /opt
# mount /opt
mkdir ${KADEPLOY_ENV_EXTRACTION_DIR}/opt
mkdir ${KADEPLOY_ENV_EXTRACTION_DIR}/opt
Line 503: Line 652:
mkdir ${KADEPLOY_ENV_EXTRACTION_DIR}/tmp
mkdir ${KADEPLOY_ENV_EXTRACTION_DIR}/tmp
mount ${KADEPLOY_BLOCK_DEVICE}5 ${KADEPLOY_ENV_EXTRACTION_DIR}/tmp/
mount ${KADEPLOY_BLOCK_DEVICE}5 ${KADEPLOY_ENV_EXTRACTION_DIR}/tmp/
</pre>
</syntaxhighlight>


'''3. Customize the environment's postinstall.'''
;3. Customize the environment's postinstall


In order for our new partitions to be mounted at boot time we can modify the Grid'5000 postinstall files (this customization can also be done by adding another custom operation).
In order for our new partitions to be mounted at boot time we can modify the Grid'5000 postinstall files (this customization can also be done by adding another custom operation).
{{Warning|text=Since new post-installation method, ''/etc/fstab'' modification is changing, so mount points containing system files (like ''/usr'') can not be easily separated.}}


* Create and go in a temporary directory:
* Create and go in a temporary directory:
Line 515: Line 663:
{{Term|location=frontend|cmd=<code class="command">tar</code> xzf <code class="replace">/grid5000/postinstalls/g5k-postinstall.tgz</code>}}
{{Term|location=frontend|cmd=<code class="command">tar</code> xzf <code class="replace">/grid5000/postinstalls/g5k-postinstall.tgz</code>}}
{{Note|text=We assume that the current shell is BASH, if not please replace the "export" instruction}}
{{Note|text=We assume that the current shell is BASH, if not please replace the "export" instruction}}
* Add mount points to ''/etc/fstab'' target file modifying '''lib/g5k-postinstall/config.rb''' file:
* Add your custom /etc/fstab file in this temporary directory, named '''fstab''':
{{Warning|text=''site-specific'' Kadeploy option hack
<syntaxhighlight lang="bash">
<pre>
/dev/sda1      none          swap    sw      0      0
  'MY_CLUSTER_SITE' => {
/dev/sda3      /var          ext4   defaults 1     2
    'dirs' => %w{/home /opt /tmp},
/dev/sda4      /opt         ext4   defaults 1     2
    'fstab' => <<-EOF
/dev/sda5      /tmp         ext4   defaults 1     2
/dev/sda3      /home          ext4   defaults   1       2
</syntaxhighlight>
/dev/sda4      /opt           ext4   defaults   1       2
/ will be added by Kadeploy since we will precise the <code class="command">-p 2</code> option
/dev/sda5      /tmp ext4   defaults   1       2
    EOF
  },
</pre>
Note that the default ''/tmp'' mount point remains in ''/etc/fstab'':
<pre>
/dev/sda5      /tmp    auto    defaults                0      0
</pre>
}}
* Regenerate the postinstall archive:
* Regenerate the postinstall archive:
{{Term|location=frontend|cmd=<code class="command">tar</code> -czvf <code class="replace">~/g5k-postinstall-custom.tgz</code> *}}
{{Term|location=frontend|cmd=<code class="command">tar</code> -czvf <code class="replace">~/g5k-postinstall-custom.tgz</code> *}}
Line 539: Line 678:
{{Term|location=frontend|cmd=<code class="command">kaenv3</code> -p debian10-x64-base -u deploy <nowiki>|</nowiki> sed -e "s/archive:.*$/archive: <code class="replace">\/home\/${USER}\/g5k-postinstall-custom.tgz</code>/" -e 's/public/shared/' > custom-env.yml}}
{{Term|location=frontend|cmd=<code class="command">kaenv3</code> -p debian10-x64-base -u deploy <nowiki>|</nowiki> sed -e "s/archive:.*$/archive: <code class="replace">\/home\/${USER}\/g5k-postinstall-custom.tgz</code>/" -e 's/public/shared/' > custom-env.yml}}
and customize the '''custom-env.yml''' file to suit your needs (especially your archive path):
and customize the '''custom-env.yml''' file to suit your needs (especially your archive path):
<pre>
 
<syntaxhighlight lang="yaml">
---  
---  
name: custom-env
name: custom-env
Line 546: Line 686:
author: me@domain.tld
author: me@domain.tld
visibility: shared
visibility: shared
destructive: false
destructive: true
os: linux
os: linux
image:
image:
Line 555: Line 695:
- archive: /home/me/g5k-postinstall-custom.tgz
- archive: /home/me/g5k-postinstall-custom.tgz
   compression: gzip
   compression: gzip
   script: g5k-postinstall --net debian --fstab site-specific
   script: g5k-postinstall --net debian --fstab custom
boot:
boot:
   kernel: "/vmlinuz"
   kernel: "/vmlinuz"
Line 562: Line 702:
partition_type: 131
partition_type: 131
multipart: false
multipart: false
</pre>
</syntaxhighlight>


{{Warning|text=Do not forget the ''--fstab site-specific'' option to g5k-postinstall.}}
{{Warning|text=Do not forget the <code class="command">--fstab custom</code> option to g5k-postinstall.}}


'''4. Run the deployment'''
;4. Run the deployment


Finally, we deploy our custom environment with your custom operations:
Finally, we deploy our custom environment with your custom operations:
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -a custom-env.yml -f $OAR_NODE_FILE -p 2 -k --custom-steps custom-partitioning.yml}}
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -a custom-env.yml -f $OAR_NODE_FILE -p 2 -k --custom-steps custom-partitioning.yml}}
{{Warning|text=Verify '''/etc/fstab''' file on the deployed environment.}}
{{Note|text=In some case you should increase the step timeout (for some long formatting for example) see [[Advanced_Kadeploy#Adjusting timeout for some environments]] for details.}}
{{Note|text=In some case you should increase the step's timeout (for some long formatting for example) see [[Advanced_Kadeploy#Adjusting timeout for some environments]] for details.}}


= Tuning the Kadeploy3 deployment workflow =
= Customizing the postinstalls =
In Kadeploy3, postinstalls are scripts that are executed after the copy of the image file in order to customize site-specific or cluster-specific aspects.
Since the beginning on 2018, on Grid'5000 the same postinstall script (called g5k-postinstall) is used for all reference environments (and is thus compatible with all supported Debian versions and distributions). That script takes parameters in order to define its behaviour (for example, to choose the style of network configuration to use).
== Using g5k-postinstall ==
The source code for g5k-postinstall is [https://gitlab.inria.fr/grid5000/g5k-postinstall/tree/master/g5k-postinstall available on gitlab.inria.fr]. Its parameters at the time of writing are:
{{Term|location=frontend|cmd=<code class=command>g5k-postinstall</code> --help}}
<syntaxhighlight lang="text">
Usage: g5k-postinstall [options]


<code class="command">kadeploy3</code> allows to fully modify the deployment workflow.
Options:
    -d, --debug                      Run in debug mode, with output to terminal
    -n, --net n1,n2,n3              Network configuration specification
    -f, --fstab f1,f2,f3            Filesystems configuration specification
    -r, --restrict-user MODE        User restriction mode
        --inittab PATTERN            Configure console in inittab.
        --no-ref-api                Do not use the Reference API
        --disable-hacks h1,h2,h3    Hacks to disable


First of all you have to understand the different steps of a deployment. There are 3 macro-steps:
Valid tags for network specification:
# <code class="env">SetDeploymentEnv</code>: this step aims at setting up the deployment environment that contains all the required tools to perform a deployment ;
  debian              write config in /etc/network/interfaces
# <code class="env">BroadcastEnv</code>: this step aims at broadcasting the new environment to the nodes and writing it to disk;
  debian-bridged      write config in /etc/network/interfaces, with a bridge
# <code class="env">BootNewEnv</code>: this step aims at rebooting the nodes on their new environment.
                      setup (for the std env)
  netplan              write config in /etc/netplan/01-netcfg.yaml
                      (https://wiki.ubuntu.com/Netplan)
  redhat              write config in /etc/sysconfig/network-scripts/*
  traditional-names    use traditional NIC naming (e.g. eth0) instead of
                      predictable
  force-ref-api-names  force the use of the name provided in the reference API
                      (by default, the predictable name determined by the
                      kernel is used)
  hpc                  add support for HPC (eg InfiniBand) interfaces
Example: --net debian-bridged,traditional-names,hpc


<code class="command">kadeploy3</code> provides several implementations for each of those 3 macro-steps. You can consult that list in the kadeploy3 page.
Valid tags for filesystems configuration in fstab:
In Grid'5000, we use the following steps by default in all our clusters :
  nfs            include generic NFS mounts (/home with autofs, /grid5000)
* <code class="env">SetDeploymentEnv</code> -> <code class=file>SetDeploymentEnvUntrusted</code> : use an embedded deployment environment
  no-autofs      do not use autofs, just mount the user's NFS directory
* <code class="env">BroadcastEnv</code> -> <code class=file>BroadcastEnvKascade</code> : use the Kascade tool to broadcast the environment
  site-specific  include site-specific NFS mounts (e.g. /softs)
* <code class="env">BootNewEnv</code> -> <code class=file>BootNewEnvKexec</code> : the nodes use kexec to reboot (if it fails, a <code class=file>BootNewEnvClassical</code>, classical reboot, will be performed)
  custom        include custom mounts for custom partitionning. Need fstab
                file included in postinstall archive.
Example: --fstab nfs,site-specific


Each one of these implementations is divided in micro steps. You can can see the name of those micro-steps if you use the kadeploy3 option <code>--verbose-level 4</code>. And to see what is actually executed during those micro-steps you can add the debug option of kadeploy3 <code>-d</code>


{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -f <code class=file>$OAR_FILE_NODES</code> -k -e debian10-x64-base --verbose-level 4 -d  &#62; <code class=file>~/kadeploy3_steps</code>}}
Valid modes for user restriction:
  std        if deployed on production partition, restrict to root,oar. else,
              restrict to the current user (see below)
  current    restrict to root and the user having currently reserved the node
  login:jdoe  restrict to a specific login (e.g. jdoe)
  none        no restriction (DEFAULT)


This command will store the kadeploy3 standard output in the file <code class=file>~/kadeploy3_steps</code>. Lets analyse its content:
Inittab option:
  Needed for non-systemd systems.
  Example of pattern: s0:12345:respawn:/sbin/agetty -L SPEED TTYSX vt100
  Where SPEED and TTYSX are replaced by g5k-postinstall using information
  retieved from the parameters which are passed in /proc/cmdline.


{{Term|location=frontend|cmd=<code class="command">grep</code> "Time in" <code class=file>~/kadeploy3_steps</code>}}
No reference API option:
  Do not use the Reference API. This is useful during initial configuration of
  new clusters.


This command will print on the terminal all the micro-steps executed during the deployment process, and the time spent for each execution. Here are the micro-steps that you should see:
Disable hacks option:
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">switch_pxe</code>: Configures the PXE server so that this node will boot on an environment that contains all the required tools to perform the deployment,
   g5k-postinstall includes hacks that can optionally be disabled. Current
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">reboot</code>: Sends a reboot signal to the node
  hacks are:
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">wait_reboot</code>: Waits for the node to restart.
  - oot-i40e          install the i40e driver on chifflot and chiclet (lille)
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">send_key_in_deploy_env</code>: Sends kadeploy's user's ssh public key into the node's authorized_keys to ease the following ssh connections,
  - beegfs-gr520     configure beegfs shares on grcinq and grvingt (nancy)
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">create_partition_table</code>: Creates the partition table
Example: --disable-hacks oot-i40e
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">format_deploy_part</code>: Format the partition where your environment will be installed. This partition is by default /dev/sda3
</syntaxhighlight>
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">mount_deploy_part</code>: Mounts the deployment partition in a local directory.
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">format_tmp_part</code>: Format the partition defined as tmp (by default, /dev/sda5)
# <code class=file>SetDeploymentEnvUntrusted</code>-<code class="replace">format_swap_part</code>: Format the swap partition
# <code class=file>BroadcastEnvKascade</code>-<code class="replace">send_environment</code>: Sends your environments into the node and untar it into the deployment partition.
# <code class=file>BroadcastEnvKascade</code>-<code class="replace">manage_admin_post_install</code>: Execute post installation instructions defined by the site admins, in general to adapt to the specificities of the cluster: console baud rate, Infiniband,...
# <code class=file>BroadcastEnvKascade</code>-<code class="replace">manage_user_post_install</code>: Execute user defined post installation instructions to automatically configure its node depending on its cluster, site, network capabilities, disk capabilities,...
# <code class=file>BroadcastEnvKascade</code>-<code class="replace">send_key</code>: Sends the user public ssh key(s) to the node (if the user specified it with the option <code>-k</code>).
# <code class=file>BroadcastEnvKascade</code>-<code class="replace">install_bootloader</code>: Properly configures the bootloader
# <code class=file>BootNewEnvKexec</code>-<code class="replace">switch_pxe</code>: Configure the PXE server so that this node will boot on the partition where your environment has been installed
# <code class=file>BootNewEnvKexec</code>-<code class="replace">umount_deploy_part</code> : Umount the deployment partition from the directory where it has been mounted during the step 7.
# <code class=file>BootNewEnvKexec</code>-<code class="replace">mount_deploy_part</code> : ReMount the deployment partition
# <code class=file>BootNewEnvKexec</code>-<code class="replace">kexec</code>: Perform a kexec reboot on the node
# <code class=file>BootNewEnvKexec</code>-<code class="replace">set_vlan</code>: Properly configure the node's VLAN
# <code class=file>BootNewEnvKexec</code>-<code class="replace">wait_reboot</code>: Wait for the node to be up.
 
That is it. You now know all the default micro-steps used to deploy your environments.
{{Note|text=It is recommended to consult the [[Grid5000:Node storage]] page to understand which partition is used at which step.}}
 
== Adjusting timeout for some environments ==
Since <code class="command">kadeploy3</code> provides multiple macro-steps and micro-steps, its is important to detect when a step in failing its execution. This error detection is done by using timeout on each step. When a timeout is reached, the nodes that have not completed the given step are discarded from the deployment process.<br>
The value of those timeouts varies from one cluster to another since they depend on the hardware configuration (network speed, hard disk speed, reboot speed, ...).
All defaults timeouts are entered in the configurations files on the kadeploy3 server. But you can consult the default timeouts of each macro-steps by using the command <code class="command">kastat3</code>
 
{{Term|location=frontend|cmd=<code class="command">kastat3</code> -I}}
   Kadeploy server configuration:
  Custom PXE boot method: PXElinux
  Automata configuration:
    hercule:
      SetDeploymentEnv: SetDeploymentEnvUntrusted,1,600
      BroadcastEnv: BroadcastEnvKascade,0,1000
      BootNewEnv: BootNewEnvKexec,0,180; BootNewEnvHardReboot,0,900
    nova:
      SetDeploymentEnv: SetDeploymentEnvUntrusted,1,600
      BroadcastEnv: BroadcastEnvKascade,0,1000
      BootNewEnv: BootNewEnvKexec,0,150; BootNewEnvHardReboot,0,600
  ...
 
 
<code class="command">kadeploy3</code> allow users to change timeouts in the command line. In some cases, when you try to deploy an environment with a large tarball or with a post-install that lasts too long, you may get discarded nodes. This false positive behavior can be avoided by manually modifying the timeouts for each step at the deployment time.
 
For instance, in our previous example, the timeout of each steps are:
* <code class=file>SetDeploymentEnvUntrusted</code>: 143
* <code class=file>BroadcastEnvKascade</code>: 111
* <code class=file>BootNewEnvKexec</code>: 33
 
You can increase the timeout of the second step to 1200 seconds with the following command :
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -e my_big_env -f <code class="env">$OAR_FILE_NODES</code> -k --force-steps "SetDeploymentEnv&#124;SetDeploymentEnvUntrusted:1:450&BroadcastEnv&#124;BroadcastEnvKascade:1:1200&BootNewEnv&#124;BootNewEnvClassical:1:400"}}
 
== Set Break-Point during deployment ==
As mentioned in the section above, a deployment is a succession of micro steps that can be consulted and modified.<br>
Moreover, <code class="command">kadeploy3</code> allows user to set a break-point during deployment.
 
{{Term|location=frontend|cmd=<code class="command">kadeploy3</code> -f <code class="env">$OAR_FILE_NODES</code> -k -e debian10-x64-base --verbose-level 4  -d --breakpoint <code class=file>BroadcastEnvKascade</code>:<code class="replace">manage_user_post_install</code>}}
 
This command can be used for debugging purpose. It performs a deployment with the maximum verbose level and it asks to stop the deployment workflow just '''''before''''' executing the ''manage_user_post_install''  micro-step of the ''BroadcastEnvKascade''  macro-step. Thus you will be able to connect in the deployment environment and to manually run the user post install script to debug it.
 
{{Warning|text=At the current state of <code class="command">kadeploy3</code>, it is not possible to resume the deployment from the break-point step. Thus you will have to redeploy you environment from the first step. This feature will be implemented in future version of <code class="command">kadeploy3</code>.}}
 
== Modify the deployment workflow with custom operations ==
In Kadeploy3, we can easily customize the deployment's automata. It's possible to add custom ''pre, post or substitute operations'' to each steps. In a custom operation it's possible to: ''send'' a file, ''execute'' a command or ''run'' a script.
 
This feature in explained in Kadeploy3's documentation (available on [https://gforge.inria.fr/frs/?group_id=2026 Kadeploy3's website]) in the section ''4.2.2, Use Case 10'' and ''4.7''.
 
You can find examples of deployment workflow tuning in the following sections:
* Add some custom steps to the workflow: [[Advanced_Kadeploy#Format additional disks]]
* Modify the workflow: [[Advanced_Kadeploy#Use a custom partitioning scheme]]
 
{{Note|text=When running a custom script, Kadeploy will export different variables, you can get a list of them by running <code class="command">kadeploy3 -I</code>.<br>A description of each of this variables is available in Kadeploy3's documentation ([https://gforge.inria.fr/frs/?group_id=2026 on Kadeploy3 website]) in the section ''4.4''}}
 
= Customizing the postinstalls =
In Kadeploy3, postinstalls are scripts that are executed after the copy of the image file in order to customize site-specific or cluster-specific aspects.
Since the beginning on 2018, on Grid'5000 the same postinstall script (called g5k-postinstall) is used for all reference environments (and is thus compatible with all supported Debian versions and distributions). That script takes parameters in order to define its behaviour (for example, to choose the style of network configuration to use).
 
The source code for g5k-postinstall is [https://gitlab.inria.fr/grid5000/g5k-postinstall/tree/master/g5k-postinstall available on gitlab.inria.fr]. Its parameters at the time of writing are:
g5k-postinstall [options]
     -d, --debug                      Run in debug mode, with output to terminal
    -n, --net t1,t2,t3              Network configuration specification
Valid tags for network specification:
  debian - write config in /etc/network/interfaces
  debian-bridged - write config in /etc/network/interfaces, with a bridge setup (for the std env)
  netplan - write config in /etc/netplan/01-netcfg.yaml (https://wiki.ubuntu.com/Netplan)
  redhat - write config in /etc/sysconfig/network-scripts/*
  traditional-names - use traditional NIC naming (e.g. eth0) instead of predictable
  force-ref-api-names - force the use of the name provided in the reference API
                        (by default, the predictable name determined by the kernel is used)
  hpc - add support for HPC (eg InfiniBand) interfaces
Example: --net debian-bridged,traditional-names,hpc
    -f, --fstab t1,t2,t3            Filesystems configuration specification
Valid tags for filesystems configuration in fstab:
  nfs - include generic NFS mounts (/home, /grid5000)
  site-specific - include site-specific NFS mounts (e.g. /softs)
Example: --fstab nfs,site-specific
    -r, --restrict-user MODE        User restriction mode
Valid modes for user restriction:
  std - if deployed on production partition, restrict to root,oar. else, restrict to the current user (see below)
  current - restrict to root and the user having currently reserved the node
  login:jdoe - restrict to a specific login (e.g. jdoe)
  none - no restriction (DEFAULT)
        --inittab PATTERN
                                      Configure console in inittab.
This is needed for non-systemd systems. Parameters in /proc/cmdline are used.
Example pattern: s0:12345:respawn:/sbin/agetty -L SPEED TTYSX vt100
SPEED and TTYSX are replaced by g5k-postinstall.
        --no-ref-api
                                      Do not use the Reference API
This is useful during initial configuration of new clusters.
        --disable-hacks h1,h2,h3
                                      Hacks to disable
g5k-postinstall includes a number of dirty hacks that can optionally be disabled.
  yeti-megaraid - install the megaraid_sas driver on yeti
Example: --disable-hacks yeti-megaraid


An example environment description using g5k-postinstall is:
An example environment description using g5k-postinstall is:
$ kaenv3 -p debian10-x64-min
<syntaxhighlight lang="yaml" highlight='13-16'>
---
---
name: debian10-x64-min
name: debian10-x64-min
version: 2019100414
version: 2019100414
Line 744: Line 803:
partition_type: 131
partition_type: 131
multipart: false
multipart: false
</syntaxhighlight>


Things that you can do are:
Things that you can do from there:
* Use a customized postinstall script: just point the postinstalls/archive/ field to another tar archive. (see [https://gitlab.inria.fr/grid5000/g5k-postinstall/blob/master/g5k-postinstall/README.md README.md] and [[TechTeam:Postinstalls]] for details)
* Use different parameters to change the behaviour of the postinstall. Example parameters for various situations are:
* Use different parameters to change the behaviour of the postinstall. Example parameters for various situations are:
** Debian min environment with traditional NIC naming: <tt>g5k-postinstall --net debian --net traditional-names</tt>
** Debian min environment with traditional NIC naming: <tt><code class=command>g5k-postinstall</code> --net debian --net traditional-names</tt>
** Debian min environment with predictable NIC naming: <tt>g5k-postinstall --net debian</tt>
** Debian min environment with predictable NIC naming: <tt><code class=command>g5k-postinstall</code> --net debian</tt>
** Debian NFS environment (mount /home, setup LDAP, restrict login to user who reserved the node): <tt>g5k-postinstall --net debian --fstab nfs --restrict-user current</tt>
** Debian NFS environment (mount /home, setup LDAP, restrict login to user who reserved the node): <tt><code class=command>g5k-postinstall</code> --net debian --fstab nfs --restrict-user current</tt>
** Debian big environment (NFS + setup HPC networks and mount site-specific directories): <tt>g5k-postinstall --net debian --net traditional-names --net hpc --fstab nfs --fstab site-specific</tt>
** Debian big environment (NFS + setup HPC networks and mount site-specific directories): <tt><code class=command>g5k-postinstall</code> --net debian --net traditional-names --net hpc --fstab nfs --fstab site-specific</tt>
** RHEL/Centos style for network configuration: <tt>g5k-postinstall --net redhat --net traditional-names</tt>
** RHEL/Centos style for network configuration: <tt><code class=command>g5k-postinstall</code> --net redhat --net traditional-names</tt>
** Ubuntu 1710 or later: NetPlan for network configuration: <tt>g5k-postinstall --net netplan</tt>
** Ubuntu 1710 or later: NetPlan for network configuration: <tt><code class=command>g5k-postinstall</code> --net netplan</tt>
** Do not do any network configuration (useful for Gentoo), but force serial console settings: <tt>g5k-postinstall --net=none --inittab='s0:12345:respawn:/sbin/agetty -L SPEED TTYSX vt100'</tt>
** Do not do any network configuration (useful for Gentoo), but force serial console settings: <tt><code class=command>g5k-postinstall</code> --inittab='s0:12345:respawn:/sbin/agetty -L SPEED TTYSX vt100'</tt>
* Use a customized version of g5k-postinstall: after building a modified g5k-postinstall, just point the postinstalls/archive/ field to the new tar archive. See [https://gitlab.inria.fr/grid5000/g5k-postinstall/blob/master/g5k-postinstall/README.md README.md] and [[TechTeam:Postinstalls]] for details on g5k-postinstall internals.
* Add additional postinstall to execute after g5k-postinstall. That way, the additionnal postinstall can be written in any language (e.g. just a shell script) and complement what is already done by g5k-postinstall, see below.


= Multisite deployment =
== Adding an extra postinstall ==
Modifying <code class="command">g5k-postinstall</code> may for some purpose not be relevant (or overkill), for instance if actions are independent and can be executed after <code class="command">g5k-postinstall</code> is run. In such a case, it is very easy to provide an additional postinstall that for instance may just be a shell script:
 
Assuming <code class="file">additional-postinstall.sh</code> is a script located at the root of the <code class="file">/home/jdoe/public/debiantesting-x64-additional-postinstall.tar.gz</code> archive, we just have to declare the additional postinstall in the environment description as follows:
 
<syntaxhighlight lang="yaml" highlight="21-23">
---
author: John Doe
boot:
  initrd: /initrd.img
  kernel: /vmlinuz
description: debian testing with some customizations
destructive: false
filesystem: ext4
image:
  compression: gzip
  file: local:///home/jdoe/public/debiantesting-x64-custom.tar.gz
  kind: tar
multipart: false
name: debiantesting-x64-custom
os: linux
partition_type: 131
postinstalls:
- archive: server:///grid5000/postinstalls/g5k-postinstall.tgz
  compression: gzip
  script: g5k-postinstall --net debian --fstab nfs --restrict-user current
- archive: local:///home/jdoe/public//debiantesting-x64-additional-postinstall.tar.gz
  compression: gzip
  script: additional-postinstall.sh
version: 2020071009
visibility: shared
</syntaxhighlight>


In order to do a deployment on nodes from differents sites you just have to use the multiserver option of kadeploy : -M
Both postinstalls will execute during the deployment, the one after the other.
So to do a deployment:
kadeploy -M -f file_with_all_nodes -e debian10-x64-std

Revision as of 09:39, 24 September 2020

Note.png Note

This page is actively maintained by the Grid'5000 team. If you encounter problems, please report them (see the Support page). Additionally, as it is a wiki page, you are free to make minor corrections yourself if needed. If you would like to suggest a more fundamental change, please contact the Grid'5000 team.

Warning.png Warning

Please mind also reading the Environment creation guide, which gives automated mechanisms to build kadeploy environnements

What you need to know before starting

The first thing to understand is that by using kadeploy3, you will be running a command that attempts to remotely reboot many nodes at the same time, and boot them using configuration files hosted on a server. On some clusters, there is a failure rate associated with this operation that is not null. You might therefore experience failures on some operations during this tutorial. In this case, retry. The system doesn't retry for you as this implies waiting for long timeouts in all cases, even those where a 90% success rate is sufficient.

What is an Environment?

Where we describe what exactly is image, kernel, initrd and postinstall

An environment in kadeploy3 is a set of file describing a fully functional Operating System. To be able to setup a Operating System, kadeploy3 needs at least 4 files in the most common cases

  1. An image
    • An image is a file containing all the Operating System files. It can be a compressed archive (ie tgz file) or a dump of a device (ie dd file). In this tutorial, you will learn to build new images for Kadeploy3
  2. A kernel file
    • For the Unix based environment, the kernel file specifies which kernel to boot. It is the full path of the kernel file.
  3. initrd file (optional)
    • For the Linux based environment, the optional initrd file allows to use an initial ramdisk which will be used as the root filesytem at the boot sequence. More information: Initrd on Wikipedia
  4. A postinstall file (optional)
    • The postinstall file allows you to correctly configure all specificity on each cluster. It is not mandatory to specify it for Kadeploy3 environment but if you know what you are doing, feel free to define it.

Once you have this set of files, you can describe your environment to kadeploy3. This description represents an environment in the kadeploy3 sense.

How can I make my own environment?

To create our own environment, there are two main ways:

  • One way is to deploy an existing environment, customize it and save it with tgz-g5k
  • The other one is to built the environment from a recipe, just like the Grid'5000 supported reference environments. See Environment creation.

Disk partitioning

Environments are deployed on the (first) local disk of each node (each Grid'5000 node is equipped with at least one hard drive). The following partitioning scheme is used:

Legacy / DOS
Device Role
sda1 Linux swap
sda2 Standard environment (default environment installed on nodes)
sda3 User's environment (when Kadeploy is used)
sda4 MS-DOS extended partition (container for the logical partitions, cannot be used)
sda5 Remaining disk space made available in /tmp
GPT / UEFI

This new partition scheme is applied to recent clusters that boot using UEFI (as of 2020: "gemini" and "pyxis" at Lyon)

Device Role
sda1 Linux swap
sda2 Standard environment (default environment installed on nodes)
sda3 User's environment (when Kadeploy is used)
sda4 EFI system partition (used to store boot images)
sda5 Remaining disk space made available in /tmp
Notes
  • Some clusters have more than one local disk. On some clusters, those disks can be reserved apart from the node itself. See Disk_reservation to find out how to use them.
  • Kadeploy allows deployments on other partitions than sda3 or even creating a custom partitioning scheme. See below for details.

Search and deploy an existing environment

Search an environment

Grid'5000 maintains several reference environments directly available in all sites. These environments are based on Debian, Ubuntu and Centos.

For Debian, different variants of reference environments are offered. For Ubuntu and Centos, only environment with a minimal system are offered.

They are called reference environments because they can be used to generate customized environments.

The description of the reference environments can be found here
Link.png Getting_Started#Deploying_nodes_with_Kadeploy

An environment registry is maintained in each site (see kaenv3), with the associated filesystem images stored in the /grid5000 directory of the frontend.

To deploy a registered environment, you must know its name as registered in the Kadeploy database. It is the first information on the environment description page. This tutorial uses the debian10-x64-base environment.

You can also list all available environment in a site by using the kaenv3 command:

Terminal.png frontend:
kaenv3 -l

This command lists all public as well as your private environments.

We distinguish three levels of visibility for an environment:

  • public: All users can see those environments. Only administrators can tag them this way.
  • shared: Every users can see the environment provided they use the -u option to specify the user the environment belongs to.
  • private: The environment is only visible by the user the environment belongs to.

For example, a shared environment added by user user is listed this way:

Terminal.png frontend:
kaenv3 -l -u user

You can also look for a specific version with the --env-version option. All the versions of the environments can be found in /grid5000/images. The version number is the last part of the tgz file.

For example: debian10-x64-min-2019100414.tgz => it's the min debian10-x64 reference environment version 2019100414.

Being able to reproduce the experiments that are done is a desirable feature. Therefore, you should always try to control as much as possible the environment the experiment is done in. Therefore, we will attempt to check that the environment that was chosen in the environment directory is the one available on a given cluster. On the cluster you would like to deploy, type the following command to print information about an environment:

Terminal.png frontend:
kaenv3 -p debian10-x64-base -u deploy

You must specify the user option. In our case, all public environments belong to user deploy.

In theory, you should also check the post-install script. A post-install script adapts an environment to the site it is deployed on.

If everything seems ok, please proceed to the next step.

Make a job on a deployable node

By default, Grid'5000 nodes are running on the production environment, which already contains most of the important features and can be used to run experiments. But you will not have administrative privileges (root privileges) on these nodes. So you will not be able to customize these environments at will. In fact, only reference environments can be customized at will. But to have the right to deploy a reference environment on a node, you must supply the option -t deploy when submitting your job.

For this part of the tutorial, job made will be interactive (-I), of the deploy type (-t deploy), on only one machine (-l nodes=1) to do environment customization (we will give ourselves 3 hours with -l walltime=3), which gives us the following command, that will open a new shell session on the frontend node:

Terminal.png frontend:
oarsub -I -t deploy -l nodes=1,walltime=3

Since all Grid'5000 nodes do not necessary have console access, it is recommended in the context of this tutorial to add the option rconsole="YES" to your reservation command.

Terminal.png frontend:
oarsub -I -t deploy -l {"rconsole='YES'"}/nodes=1,walltime=3

Indeed, when you submit a job of the deploy type, a new shell is opened on the frontend node and not on the first machine of the job as for standard jobs. When you exit from this shell, the job ends. The shell is populated with OAR_* environment variables. You should look at the list of available variables to get an idea of the information you can use to script deployment later. As usual, if the job is successfull, you will get the name of the machine allocated to your job with:

Terminal.png frontend:
cat $OAR_FILE_NODES
Warning.png Warning

At the end of a reservation with the options -t deploy, the reserved nodes will be restarted to boot on the standard environment and thus be available to any other user. So you should only use this option -t deploy when you actually intend to deploy a reference environment on the reserved nodes.

Deploy a reference environment

To deploy your environment, you must discover the nodes you were allocated by OAR. The simplest way of doing this is to look at the content of the file whose name is stored in $OAR_FILE_NODES (this variable is labelled $OAR_NODE_FILE too) or the messages displayed when the job was made. This variable $OAR_NODE_FILE simply stores the url of the file containing the FQDN of all your reserved nodes. Deployment happens when you run the following command:

Terminal.png frontend:
kadeploy3 -e debian10-x64-base -m node.site.grid5000.fr

You can automate this to deploy on all nodes of your job with the -f option:

Terminal.png frontend:
kadeploy3 -e debian10-x64-base -f $OAR_FILE_NODES


In order to be able to connect to the node (as root), you must use the -k option and proceed by two ways:

  • You can either specify the public key that will be copied in /root/.ssh/authorized_keys on the deployed nodes:
Terminal.png frontend:
kadeploy3 -e debian10-x64-base -f $OAR_FILE_NODES -k ~/.ssh/my_special_key.pub
  • Or you can supply the -k option without argument. This will automatically copy your ~/.ssh/authorized_keys and replace the /root/.ssh/authorized_keys file on the deployed nodes.
Terminal.png frontend:
kadeploy3 -e debian10-x64-base -f $OAR_FILE_NODES -k

The second case is actually the simplest way. One of its advantages is that after deployments, you will be able to connect directly from your local computer to the deployed nodes, the same way you connect to the frontend of the site were those nodes are.
Once kadeploy has run successfully, the allocated node is deployed under debian10-x64-base environment. It will then be possible to tune this environment according to your needs.

Note.png Note

It is not necessary here, but you can specify destination partition with the -p option

Connect to the deployed environment and customize it

1. Connection

On reference environments managed by the staff, you can use root account for login through ssh (kadeploy checks that sshd is running before declaring a deployment successful). To connect to the node type:

Terminal.png frontend:
ssh root@node.site.grid5000.fr

In case this doesn't work, please take a look at the kadeploy section of the Sidebar > FAQ

2. Adding software to an environment

Where you learn to install software using the package repository of your distribution on Grid'5000

You can therefore update your environment (to add missing libraries that you need, or remove packages that you don't so that sizes down the image and speeds up the deployment process, etc.) using:

Terminal.png node:
apt-get update
apt-get upgrade
apt-get install list of desired packages and libraries
apt-get --purge remove list of unwanted packages
apt-get clean

Create a new environment from a customized environment

We now need to save this customized environment, where you have a user account, to be able to use this account again each time you deploy it.
The first step to create an environment is to create an archive of the node you just customized. Because of the various implementations of the /dev filesystem tree, this can be a more or less complex operation.

1. Use the provided tools

You can use tgz-g5k to extract a Grid'5000 environment tarball from a running node.

Terminal.png frontend:
tgz-g5k -m node -f ~/path_to_myimage.tgz

This will create a file path_to_image.tgz into your home directory on frontend.

Note.png Note

Please consider the following:

  • If you want to extract a tarball from the Grid'5000 standard environment (i.e., a non-deployed job), you will need to add the option -o to use oarsh/oarcp instead of ssh/scp
  • If you want tgz-g5k to access the node with a custom user id, you can use the option -u myCustomeId (default is root)
  • You can find more information on tgz-g5k (e.g., available options, command line examples) by executing tgz-g5k -h. Some implementation details are also available on the man page (man tgz-g5k).

2. Describe the newly created environment for deployments

Kadeploy3 works using an environment description. The easiest way to create a description for your new environment is to change the description of the environment it is based on. We have based this tutorial on the debian10-x64-base environment of user deploy. We therefore print its description to a file that will be used as a good basis:

Terminal.png frontend:
kaenv3 -p debian10-x64-base -u deploy > mydebian10-x64-base.env

It should be edited to change the name, description, author lines, as well as the tarball line. Since the tarball is local, the path should be a simple absolute path (without a leading server://). The visibility line should be removed, or changed to shared or private. Once this is done, the newly created environment can be deployed using:

Terminal.png frontend:
kadeploy3 -f $OAR_NODEFILE -a mydebian10-x64-base.env

This kind of deployment is called anonymous deployment because the description is not recorded into the Kadeploy3 database. It is particularly useful when you perform the tuning of your environment if you have to update the environment tarball several times.

Once your customized environment is successfully tuned, you can save it to Kadeploy3 database so that you can directly deploy it with kadeploy3, by specifying its name:

Terminal.png frontend:
kaenv3 -a mydebian10-x64-base.env

and then (if your environment is named "mydebian10-base"):

Terminal.png frontend:
kadeploy3 -f $OAR_NODEFILE -e mydebian10-base

With kaenv3 command, you can manage your environments at your ease. Please refer to its documentation for an overview of its features.

Deployment options

Multisite deployment

In order to achieve a deployment on nodes from differents sites, you can use the multiserver option of kadeploy, using the -M

Terminal.png frontend:
kadeploy3 -M -f file_with_all_nodes -e debian10-x64-std

Deploy on other partition of disk(s)

Kadeploy default handling of partitions may be too limited for some usage. One may need to use disks differently (e.g. to deploy our environment in an optimal way). Kadeploy offers several options to simply deploy on another existing partition (sda2 or sda5), or if required to repartition disks entirely and/or use several disks (on nodes with many disks).

Deploy on sda2 or sda5

First, as this kind of deployment will break node standard operation, you must tell to OAR that it should be redeployed entirely after the reservation with the -t destructive option:

Terminal.png frontend:
oarsub -t deploy -t destructive -l nodes=1,walltime=1 -p "cluster='hercule'" -I

Then you can deploy on sda2 or sda5 with the -p 2 or -p 5 option:

Terminal.png frontend:
kadeploy3 -e debian10-x64-nfs -f $OAR_NODEFILE -p 2 -k

Deploy on additional disks

Warning.png Warning

Currently broken

First, as this kind of deployment will break node standard operation, you must tell to OAR that it should be redeployed entirely after the reservation with the -t destructive option:

Terminal.png frontend:
oarsub -t deploy -t destructive -l nodes=1,walltime=1 -p "cluster='hercule'" -I

Then you can deploy on an additional disk such as sdb with the -b sdb option:

Terminal.png frontend:
kadeploy3 -e debian10-x64-base -f $OAR_NODEFILE -b sdb -k

Disks can also be handled differently by modifying the deployment automata, see below.

Tuning the Kadeploy3 deployment workflow

kadeploy3 allows to fully modify the deployment workflow.

First of all you have to understand the different steps of a deployment. There are 3 macro-steps:

  1. SetDeploymentEnv: this step aims at setting up the deployment environment that contains all the required tools to perform a deployment ;
  2. BroadcastEnv: this step aims at broadcasting the new environment to the nodes and writing it to disk;
  3. BootNewEnv: this step aims at rebooting the nodes on their new environment.

kadeploy3 provides several implementations for each of those 3 macro-steps. You can consult that list in the kadeploy3 page. In Grid'5000, we use the following steps by default in all our clusters:

  • SetDeploymentEnv -> SetDeploymentEnvUntrusted: use an embedded deployment environment
  • BroadcastEnv -> BroadcastEnvKascade: use the Kascade tool to broadcast the environment
  • BootNewEnv -> BootNewEnvKexec: the nodes use kexec to reboot (if it fails, a BootNewEnvClassical, classical reboot, will be performed)

Each one of these implementations is divided in micro steps. You can can see the name of those micro-steps if you use the kadeploy3 option --verbose-level 4. And to see what is actually executed during those micro-steps you can add the debug option of kadeploy3 -d

Terminal.png frontend:
kadeploy3 -f $OAR_FILE_NODES -k -e debian10-x64-base --verbose-level 4 -d > ~/kadeploy3_steps

This command will store the kadeploy3 standard output in the file ~/kadeploy3_steps. Lets analyse its content:

Terminal.png frontend:
grep "Time in" ~/kadeploy3_steps

This command will print on the terminal all the micro-steps executed during the deployment process, and the time spent for each execution. Here are the micro-steps that you should see:

  1. SetDeploymentEnvUntrusted-switch_pxe: Configures the PXE server so that this node will boot on an environment that contains all the required tools to perform the deployment,
  2. SetDeploymentEnvUntrusted-reboot: Sends a reboot signal to the node
  3. SetDeploymentEnvUntrusted-wait_reboot: Waits for the node to restart.
  4. SetDeploymentEnvUntrusted-send_key_in_deploy_env: Sends kadeploy's user's ssh public key into the node's authorized_keys to ease the following ssh connections,
  5. SetDeploymentEnvUntrusted-create_partition_table: Creates the partition table
  6. SetDeploymentEnvUntrusted-format_deploy_part: Format the partition where your environment will be installed. This partition is by default /dev/sda3
  7. SetDeploymentEnvUntrusted-mount_deploy_part: Mounts the deployment partition in a local directory.
  8. SetDeploymentEnvUntrusted-format_tmp_part: Format the partition defined as tmp (by default, /dev/sda5)
  9. SetDeploymentEnvUntrusted-format_swap_part: Format the swap partition
  10. BroadcastEnvKascade-send_environment: Sends your environments into the node and untar it into the deployment partition.
  11. BroadcastEnvKascade-manage_admin_post_install: Execute post installation instructions defined by the site admins, in general to adapt to the specificities of the cluster: console baud rate, Infiniband,...
  12. BroadcastEnvKascade-manage_user_post_install: Execute user defined post installation instructions to automatically configure its node depending on its cluster, site, network capabilities, disk capabilities,...
  13. BroadcastEnvKascade-send_key: Sends the user public ssh key(s) to the node (if the user specified it with the option -k).
  14. BroadcastEnvKascade-install_bootloader: Properly configures the bootloader
  15. BootNewEnvKexec-switch_pxe: Configure the PXE server so that this node will boot on the partition where your environment has been installed
  16. BootNewEnvKexec-umount_deploy_part: Umount the deployment partition from the directory where it has been mounted during the step 7.
  17. BootNewEnvKexec-mount_deploy_part: ReMount the deployment partition
  18. BootNewEnvKexec-kexec: Perform a kexec reboot on the node
  19. BootNewEnvKexec-set_vlan: Properly configure the node's VLAN
  20. BootNewEnvKexec-wait_reboot: Wait for the node to be up.

That is it. You now know all the default micro-steps used to deploy your environments.

Adjusting timeout for some environments

Since kadeploy3 provides multiple macro-steps and micro-steps, its is important to detect when a step in failing its execution. This error detection is done by using timeout on each step. When a timeout is reached, the nodes that have not completed the given step are discarded from the deployment process.
The value of those timeouts varies from one cluster to another since they depend on the hardware configuration (network speed, hard disk speed, reboot speed, ...). All defaults timeouts are entered in the configurations files on the kadeploy3 server. But you can consult the default timeouts of each macro-steps by using the command kastat3

Terminal.png frontend:
kastat3 -I
 Kadeploy server configuration:
 Custom PXE boot method: PXElinux
 Automata configuration:
   hercule:
     SetDeploymentEnv: SetDeploymentEnvUntrusted,1,600
     BroadcastEnv: BroadcastEnvKascade,0,1000
     BootNewEnv: BootNewEnvKexec,0,180; BootNewEnvHardReboot,0,900
   nova:
     SetDeploymentEnv: SetDeploymentEnvUntrusted,1,600
     BroadcastEnv: BroadcastEnvKascade,0,1000
     BootNewEnv: BootNewEnvKexec,0,150; BootNewEnvHardReboot,0,600
 ...


kadeploy3 allow users to change timeouts in the command line. In some cases, when you try to deploy an environment with a large tarball or with a post-install that lasts too long, you may get discarded nodes. This false positive behavior can be avoided by manually modifying the timeouts for each step at the deployment time.

For instance, in our previous example, the timeout of each steps are:

  • SetDeploymentEnvUntrusted: 143
  • BroadcastEnvKascade: 111
  • BootNewEnvKexec: 33

You can increase the timeout of the second step to 1200 seconds with the following command:

Terminal.png frontend:
kadeploy3 -e my_big_env -f $OAR_FILE_NODES -k --force-steps "SetDeploymentEnv|SetDeploymentEnvUntrusted:1:450&BroadcastEnv|BroadcastEnvKascade:1:1200&BootNewEnv|BootNewEnvClassical:1:400"

Set Break-Point during deployment

As mentioned in the section above, a deployment is a succession of micro steps that can be consulted and modified.
Moreover, kadeploy3 allows user to set a break-point during deployment.

Terminal.png frontend:
kadeploy3 -f $OAR_FILE_NODES -k -e debian10-x64-base --verbose-level 4 -d --breakpoint BroadcastEnvKascade:manage_user_post_install

This command can be used for debugging purpose. It performs a deployment with the maximum verbose level and it asks to stop the deployment workflow just before executing the manage_user_post_install micro-step of the BroadcastEnvKascade macro-step. Thus you will be able to connect in the deployment environment and to manually run the user post install script to debug it.

Warning.png Warning

At the current state of kadeploy3, it is not possible to resume the deployment from the break-point step. Thus you will have to redeploy you environment from the first step. This feature will be implemented in future version of kadeploy3.

Modify the deployment workflow with custom operations

In Kadeploy3, we can easily customize the deployment's automata. It's possible to add custom pre, post or substitute operations to each steps. In a custom operation it's possible to: send a file, execute a command or run a script.

This feature in explained in Kadeploy3's documentation (available on Kadeploy3's website) in the section 4.2.2, Use Case 10 and 4.7.

This is illustrated in the following sub-sections.

Note.png Note

When running a custom script, Kadeploy will export different variables, you can get a list of them by running kadeploy3 -I.
A description of each of this variables is available in Kadeploy3's documentation (on Kadeploy3 website) in the section 4.4

Format additional disks

In this example, we will add some custom operations to the deployment workflow: our nodes have two additional hard disks and we want them to be formated during the deployment process.

We want to a new partition scheme such as:

  • classical grid5000 partitioning on sda
  • data1 ext4 on sdb1
  • data2 ext2 on sdc1

The three following sections describe how to perform such an operation.

1. Make the reservation in destructive mode

First of all, when you do your reservation, you must tell to OAR that it should redeploy the node entirely after the reservation with the -t destructive parameter:

Terminal.png frontend:
oarsub -t deploy -t destructive -l nodes=1,walltime=2 -p "cluster='hercule'" -I
2. Describe the custom operations

After that you have to create a file that describe the custom operations you want to be performed during the deployment. In our example we will first repartition the additional disks (using parted) and then format them (using the script format.sh).

  • The operation description file (let's say custom-partitioning.yml) should look like something like this:
---
# Our custom steps should be performed during the SetDeploymentEnv macro-step
SetDeploymentEnvUntrusted:
  # Custom partitioning step, done after the create_partition_table micro-step
  # In the sample this step is exploded in 4 steps but it can be done in 1 using a single parted command
  create_partition_table:
      post-ops:
        # We send a file on the node
        - action: send
          file: sdb.parted
          # The variable $KADEPLOY_TMP_DIR will be substitued by kadeploy
          destination: $KADEPLOY_TMP_DIR 
          name: send_partition_map_sdb
        # Then we execute the parted command using the previously sent file
        - action: exec
          name: partitioning_sdb
          # The variable $KADEPLOY_TMP_DIR will be substitued by kadeploy
          command: parted -a optimal /dev/sdb --script $(cat $KADEPLOY_TMP_DIR/sdb.parted)
        # Same operation for the second disk
        - action: send
          file: sdc.parted
          destination: $KADEPLOY_TMP_DIR 
          name: send_partition_map_sdc
        - action: exec
          name: partitioning_sdc
          command: parted -a optimal /dev/sdc --script $(cat $KADEPLOY_TMP_DIR/sdc.parted)
  # Custom format step, done after the format_deploy_part micro-step
  format_deploy_part:
      post-ops:
        # We run the script contained in the file 'format.sh'
        - action: run 
          name: format_disks
          file: format.sh
  • The file sdb.parted will look like something like this:
mklabel msdos
u GB mkpart primary ext4 0% 100%
align-check optimal 1
  • The file sdc.parted will look like something like this:
mklabel msdos
u GB mkpart primary ext2 0% 100%
align-check optimal 1
  • The file format.sh will look like something like this:
#!/bin/sh
set -e
# formating /dev/sdb
mkfs -t ext4 -b 4096 -O sparse_super,filetype,resize_inode,dir_index -q /dev/sdb1
# formating /dev/sdc
mkfs -t ext2 -b 4096 -O sparse_super,filetype,resize_inode,dir_index -q /dev/sdc1
3. Run the deployment

Now you can deploy you environment with this custom operation:

Terminal.png frontend:
kadeploy3 -e debian10-x64-min -f $OAR_NODE_FILE -k --custom-steps ./custom-partitioning.yml
Warning.png Warning

In some cases you should increase the step timeout (for some long formatting for example) see Advanced_Kadeploy#Adjusting timeout for some environments for details.

Note: Both partitions are not mounted on boot. To mount those partitions you should do:

Terminal.png NODE:
mkdir -p /media/data1
Terminal.png NODE:
mkdir /media/data2
Terminal.png NODE:
mount /dev/sdb1 /media/data1
Terminal.png NODE:
mount /dev/sdc1 /media/data2

Use a custom partitioning scheme

Example 1: Deploy on the whole disk

In this example, we will modify the deployment workflow to deploy the system on a unique disk partition ( '/' on sda1 )

1. Make the reservation in destructive mode

As you will change partitioning of the disk, you must tell to OAR that it should redeploy the node entirely after the reservation with the -t destructive parameter:

Terminal.png frontend:
oarsub -t deploy -t destructive -l nodes=1,walltime=2 -I
2. Describe the custom operations

After that you have to create a file that describe the custom operations you want to be performed during the deployment. In this example we will create our custom partitioning scheme and bypass some steps that are not necessary to deploy the system on a unique partition.

  • The operation description file (let's say custom-partitioning.yml) should look like something like this:
---
# Our custom steps should be performed during the SetDeploymentEnv macro-step
SetDeploymentEnvUntrusted:
  # Custom partitioning step that is substituted to the create_partition_table micro-step
  create_partition_table:
    substitute:
      # We send a file on the node
      - action: send
        file: map.parted
        # The variable $KADEPLOY_TMP_DIR will be substituted by Kadeploy
        destination: $KADEPLOY_TMP_DIR
        name: send_partition_map
      # Then we execute the parted command using the previously sent file
      - action: exec
        name: partitioning
        # The variable $KADEPLOY_TMP_DIR will be substituted by Kadeploy
        command: parted -a optimal /dev/sda --script $(cat $KADEPLOY_TMP_DIR/map.parted)
# Hack to disable useless steps
  format_tmp_part:
    substitute:
      - action: exec
        name: remove_format_tmp_part_step
        command: /bin/true
  format_swap_part:
    substitute:
      - action: exec
        name: remove_format_swap_part_step
        command: /bin/true
  • The file map.parted, which will be passed to parted, will look like this:
mklabel gpt
mkpart partition-system ext4 0% 100%
toggle 1 boot
align-check optimal 1
3. Customize the environment's postinstall

In order for our new partitions to be mounted at boot time we will modify the Grid'5000 postinstall files.

  • Create and go in your public directory:
Terminal.png frontend:
mkdir public/custom-postinstall && cd public/custom-postinstall
  • Then decompress the postinstall archive:
Terminal.png frontend:
tar xzf /grid5000/postinstalls/g5k-postinstall.tgz
  • Add your custom /etc/fstab file in this directory, named fstab:
/dev/sda1       /          ext4    defaults 1      2

When you will pass "--fstab custom" option to the postinstall, it will copy this file in /etc/fstab

  • Regenerate the postinstall archive:
Terminal.png frontend:
tar -czvf ~/public/g5k-postinstall-custom.tgz *
  • Make some cleanup:
  • Create the environment's description file (let's say custom-env.dsc) based on the reference one:
    • use kaenv3 -p debian10-x64-base to have an example of environment description.

Your custom-env.dsc should look like this:

--- 
name: custom-env
version: 1
description: Custom env based on Debian 10
author: me@domain.tld
visibility: shared
destructive: true
os: linux
image:
  file: server:///grid5000/images/debian10-x64-base-2020012812.tgz
  kind: tar
  compression: gzip
postinstalls:
- archive: http://public/~<login>/g5k-postinstall-custom.tgz
  compression: gzip
  script: g5k-postinstall --net debian --fstab custom
boot:
  kernel: "/vmlinuz"
  initrd: "/initrd.img"
filesystem: ext4
partition_type: 131
multipart: false
4. Run the deployment

Finally, we deploy our custom environment with your custom operations:

Terminal.png frontend:
kadeploy3 -a custom-env.dsc -f $OAR_NODE_FILE -p 1 -k --custom-steps custom-partitioning.yml
Note.png Note

In some case you should increase the step timeout (for some long formatting for example) see Advanced_Kadeploy#Adjusting timeout for some environments for details.

Example 2: Deploy on multiple partitions

In this example, we will modify the deployment workflow: a different partition will be used for each of the /, /home, /opt and /tmp directories. Imagine that you want to make your own partitioning scheme like that:

Mount point Partition Disk space File System
swap /dev/sda1 2G linux-swap
/ /dev/sda2 18G ext4
/var /dev/sda3 30G ext4
/opt /dev/sda4 20G ext4
/tmp /dev/sda5 everything else ext4

The four following sections describe how to perform such an operation.

1. Make the reservation in destructive mode

First of all, when you do your reservation, you must tell to OAR that it should redeploy the node entirely after the reservation with the -t destructive parameter:

Terminal.png frontend:
oarsub -t deploy -t destructive -l nodes=1,walltime=2 -I
2. Describe the custom operations

After that you have to create a file that describe the custom operations you want to be performed during the deployment. In our example we will first create apply our custom partitioning scheme, format the partition and the mount them.

  • The operation description file (let's say custom-partitioning.yml) should look like something like this:
---
# Our custom steps should be performed during the SetDeploymentEnv macro-step
SetDeploymentEnvUntrusted:
  # Custom partitioning step that is substituted to the create_partition_table micro-step
  create_partition_table:
    substitute:
      # We send a file on the node
      - action: send
        file: map.parted
        # The variable $KADEPLOY_TMP_DIR will be substituted by Kadeploy
        destination: $KADEPLOY_TMP_DIR 
        name: send_partition_map
      # Then we execute the parted command using the previously sent file
      - action: exec
        name: partitioning
        # The variable $KADEPLOY_TMP_DIR will be substituted by Kadeploy
        command: parted -a optimal /dev/sda --script $(cat $KADEPLOY_TMP_DIR/map.parted)
  # Custom format step, done after the format_deploy_part micro-step
  format_deploy_part:
    post-ops:
      # We run the script contained in the file 'format.sh'
      - action: run 
        name: format_partitions
        file: format.sh
  # Custom mount step, done after the mount_deploy_part micro-step
  mount_deploy_part:
    post-ops:
      # We run the script contained in the file 'format.sh'
      - action: run 
        name: mount_partitions
        file: mount.sh
# Hack to disable useless steps
  format_tmp_part:
    substitute:
      - action: exec
        name: remove_format_tmp_part_step
        command: /bin/true
  format_swap_part:
    substitute:
      - action: exec
        name: remove_format_swap_part_step
        command: /bin/true
Note.png Note

In order for Kadeploy to be able to perform the installation correctly, every partitions have to be mounted before the installation process which is done in the macro-step BroadcastEnv

  • The file map.parted will look like something like this:
mklabel gpt
u GB mkpart partition-swap linux-swap 0% 2
u GB mkpart partition-system ext4 2 20
u GB mkpart partition-var ext4 20 50
u GB mkpart partition-opt ext4 50 70
u GB mkpart partition-tmp ext4 70 100%
toggle 2 boot
align-check optimal 1
align-check optimal 2
align-check optimal 3
align-check optimal 4
align-check optimal 5
  • The file format.sh will look like something like this:
#!/bin/sh
set -e

mkfs_opts="sparse_super,filetype,resize_inode,dir_index"
ext4_blocksize="4096"

# create swap
mkswap ${KADEPLOY_BLOCK_DEVICE}1
# / will be formated by Kadeploy since we will precise the -p 2 option
# formating /var
mkfs -t ext4 -b ${ext4_blocksize} -O ${mkfs_opts} -q ${KADEPLOY_BLOCK_DEVICE}3
# formating /opt
mkfs -t ext4 -b ${ext4_blocksize} -O ${mkfs_opts} -q ${KADEPLOY_BLOCK_DEVICE}4
# formating /tmp
mkfs -t ext4 -b ${ext4_blocksize} -O ${mkfs_opts} -q ${KADEPLOY_BLOCK_DEVICE}5
Note.png Note

When running a custom script, Kadeploy will export different variables, you can get a list of them by running "kadeploy -i".

  • The file mount.sh will look like something like this:
#!/bin/sh
set -e

# / will be mounted in ${KADEPLOY_ENV_EXTRACTION_DIR} by Kadeploy
# mount /var
mkdir ${KADEPLOY_ENV_EXTRACTION_DIR}/var
mount ${KADEPLOY_BLOCK_DEVICE}3 ${KADEPLOY_ENV_EXTRACTION_DIR}/var/
# mount /opt
mkdir ${KADEPLOY_ENV_EXTRACTION_DIR}/opt
mount ${KADEPLOY_BLOCK_DEVICE}4 ${KADEPLOY_ENV_EXTRACTION_DIR}/opt/
# mount /tmp
mkdir ${KADEPLOY_ENV_EXTRACTION_DIR}/tmp
mount ${KADEPLOY_BLOCK_DEVICE}5 ${KADEPLOY_ENV_EXTRACTION_DIR}/tmp/
3. Customize the environment's postinstall

In order for our new partitions to be mounted at boot time we can modify the Grid'5000 postinstall files (this customization can also be done by adding another custom operation).

  • Create and go in a temporary directory:
Terminal.png frontend:
tmpdir=$(mktemp -d) && export tmpdir && pushd $tmpdir
  • Then decompress the postinstall archive:
Terminal.png frontend:
tar xzf /grid5000/postinstalls/g5k-postinstall.tgz
Note.png Note

We assume that the current shell is BASH, if not please replace the "export" instruction

  • Add your custom /etc/fstab file in this temporary directory, named fstab:
/dev/sda1       none          swap    sw       0      0
/dev/sda3       /var          ext4    defaults 1      2
/dev/sda4       /opt          ext4    defaults 1      2
/dev/sda5       /tmp          ext4    defaults 1      2

/ will be added by Kadeploy since we will precise the -p 2 option

  • Regenerate the postinstall archive:
Terminal.png frontend:
tar -czvf ~/g5k-postinstall-custom.tgz *
  • Make some cleanup:
Terminal.png frontend:
popd && rm -R $tmpdir
  • Create the environment's description file (let's say custom-env.yml) based on the reference one:
Terminal.png frontend:
kaenv3 -p debian10-x64-base -u deploy | sed -e "s/archive:.*$/archive: \/home\/${USER}\/g5k-postinstall-custom.tgz/" -e 's/public/shared/' > custom-env.yml

and customize the custom-env.yml file to suit your needs (especially your archive path):

--- 
name: custom-env
version: 1
description: Custom env based on Debian 10
author: me@domain.tld
visibility: shared
destructive: true
os: linux
image:
  file: server:///grid5000/images/debian10-x64-base-2019100414.tgz
  kind: tar
  compression: gzip
postinstalls:
- archive: /home/me/g5k-postinstall-custom.tgz
  compression: gzip
  script: g5k-postinstall --net debian --fstab custom
boot:
  kernel: "/vmlinuz"
  initrd: "/initrd.img"
filesystem: ext4
partition_type: 131
multipart: false
Warning.png Warning

Do not forget the --fstab custom option to g5k-postinstall.

4. Run the deployment

Finally, we deploy our custom environment with your custom operations:

Terminal.png frontend:
kadeploy3 -a custom-env.yml -f $OAR_NODE_FILE -p 2 -k --custom-steps custom-partitioning.yml
Note.png Note

In some case you should increase the step timeout (for some long formatting for example) see Advanced_Kadeploy#Adjusting timeout for some environments for details.

Customizing the postinstalls

In Kadeploy3, postinstalls are scripts that are executed after the copy of the image file in order to customize site-specific or cluster-specific aspects. Since the beginning on 2018, on Grid'5000 the same postinstall script (called g5k-postinstall) is used for all reference environments (and is thus compatible with all supported Debian versions and distributions). That script takes parameters in order to define its behaviour (for example, to choose the style of network configuration to use).

Using g5k-postinstall

The source code for g5k-postinstall is available on gitlab.inria.fr. Its parameters at the time of writing are:

Terminal.png frontend:
g5k-postinstall --help
Usage: g5k-postinstall [options]

Options:
    -d, --debug                      Run in debug mode, with output to terminal
    -n, --net n1,n2,n3               Network configuration specification
    -f, --fstab f1,f2,f3             Filesystems configuration specification
    -r, --restrict-user MODE         User restriction mode
        --inittab PATTERN            Configure console in inittab.
        --no-ref-api                 Do not use the Reference API
        --disable-hacks h1,h2,h3     Hacks to disable

Valid tags for network specification:
  debian               write config in /etc/network/interfaces
  debian-bridged       write config in /etc/network/interfaces, with a bridge
                       setup (for the std env)
  netplan              write config in /etc/netplan/01-netcfg.yaml
                       (https://wiki.ubuntu.com/Netplan)
  redhat               write config in /etc/sysconfig/network-scripts/*
  traditional-names    use traditional NIC naming (e.g. eth0) instead of
                       predictable
  force-ref-api-names  force the use of the name provided in the reference API
                       (by default, the predictable name determined by the
                       kernel is used)
  hpc                  add support for HPC (eg InfiniBand) interfaces
Example: --net debian-bridged,traditional-names,hpc

Valid tags for filesystems configuration in fstab:
  nfs            include generic NFS mounts (/home with autofs, /grid5000)
  no-autofs      do not use autofs, just mount the user's NFS directory
  site-specific  include site-specific NFS mounts (e.g. /softs)
  custom         include custom mounts for custom partitionning. Need fstab
                 file included in postinstall archive.
Example: --fstab nfs,site-specific


Valid modes for user restriction:
  std         if deployed on production partition, restrict to root,oar. else,
              restrict to the current user (see below)
  current     restrict to root and the user having currently reserved the node
  login:jdoe  restrict to a specific login (e.g. jdoe)
  none        no restriction (DEFAULT)

Inittab option:
  Needed for non-systemd systems.
  Example of pattern: s0:12345:respawn:/sbin/agetty -L SPEED TTYSX vt100
  Where SPEED and TTYSX are replaced by g5k-postinstall using information
  retieved from the parameters which are passed in /proc/cmdline.

No reference API option:
  Do not use the Reference API. This is useful during initial configuration of
  new clusters.

Disable hacks option:
  g5k-postinstall includes hacks that can optionally be disabled. Current
  hacks are:
  - oot-i40e          install the i40e driver on chifflot and chiclet (lille)
  - beegfs-gr520      configure beegfs shares on grcinq and grvingt (nancy)
Example: --disable-hacks oot-i40e

An example environment description using g5k-postinstall is:

---
name: debian10-x64-min
version: 2019100414
description: debian 10 (buster) - min
author: support-staff@list.grid5000.fr
visibility: public
destructive: false
os: linux
image:
  file: server:///grid5000/images/debian10-x64-min-2019100414.tgz
  kind: tar
  compression: gzip
postinstalls:
- archive: server:///grid5000/postinstalls/g5k-postinstall.tgz
  compression: gzip
  script: g5k-postinstall --net debian
boot:
  kernel: "/vmlinuz"
  initrd: "/initrd.img"
filesystem: ext4
partition_type: 131
multipart: false

Things that you can do from there:

  • Use different parameters to change the behaviour of the postinstall. Example parameters for various situations are:
    • Debian min environment with traditional NIC naming: g5k-postinstall --net debian --net traditional-names
    • Debian min environment with predictable NIC naming: g5k-postinstall --net debian
    • Debian NFS environment (mount /home, setup LDAP, restrict login to user who reserved the node): g5k-postinstall --net debian --fstab nfs --restrict-user current
    • Debian big environment (NFS + setup HPC networks and mount site-specific directories): g5k-postinstall --net debian --net traditional-names --net hpc --fstab nfs --fstab site-specific
    • RHEL/Centos style for network configuration: g5k-postinstall --net redhat --net traditional-names
    • Ubuntu 1710 or later: NetPlan for network configuration: g5k-postinstall --net netplan
    • Do not do any network configuration (useful for Gentoo), but force serial console settings: g5k-postinstall --inittab='s0:12345:respawn:/sbin/agetty -L SPEED TTYSX vt100'
  • Use a customized version of g5k-postinstall: after building a modified g5k-postinstall, just point the postinstalls/archive/ field to the new tar archive. See README.md and TechTeam:Postinstalls for details on g5k-postinstall internals.
  • Add additional postinstall to execute after g5k-postinstall. That way, the additionnal postinstall can be written in any language (e.g. just a shell script) and complement what is already done by g5k-postinstall, see below.

Adding an extra postinstall

Modifying g5k-postinstall may for some purpose not be relevant (or overkill), for instance if actions are independent and can be executed after g5k-postinstall is run. In such a case, it is very easy to provide an additional postinstall that for instance may just be a shell script:

Assuming additional-postinstall.sh is a script located at the root of the /home/jdoe/public/debiantesting-x64-additional-postinstall.tar.gz archive, we just have to declare the additional postinstall in the environment description as follows:

---
author: John Doe
boot:
  initrd: /initrd.img
  kernel: /vmlinuz
description: debian testing with some customizations
destructive: false
filesystem: ext4
image:
  compression: gzip
  file: local:///home/jdoe/public/debiantesting-x64-custom.tar.gz
  kind: tar
multipart: false
name: debiantesting-x64-custom
os: linux
partition_type: 131
postinstalls:
- archive: server:///grid5000/postinstalls/g5k-postinstall.tgz
  compression: gzip
  script: g5k-postinstall --net debian --fstab nfs --restrict-user current
- archive: local:///home/jdoe/public//debiantesting-x64-additional-postinstall.tar.gz
  compression: gzip
  script: additional-postinstall.sh
version: 2020071009
visibility: shared

Both postinstalls will execute during the deployment, the one after the other.