path: root/ansible_collections/dellemc/openmanage/roles/idrac_os_deployment/README.md

idrac_os_deployment
=========

Role to deploy operating system and version on the servers.</br>

The role perform the following operations:
1. Downloads or copies the source ISO as a local copy in the ansible controller machine tmp folder.
1. Create a kickstart file using jinja template based on the os name and version .
1. Extract the ISO using the `xorriso` library.
1. Enable the extracted ISO to use kickstart file by modifying the boot configurations for bios and uefi.
1. Compile the iso to generate a custom iso by embedding the kickstart file in an iso using the `mkisofs`, `isohybrid` and `implantisomd5` commands.
1. Copy the custom ISO generated to destination share location as specfied to the role input. Based on the input a following method is used to copy the destination to a shared repository.
    - CIFS/NFS  uses the local file mount to copy the ISO to a location.
    - HTTP/HTTPS uses the SSH to copy/transfer the ISO to a location where the web server content is served.
1. Using an iDRAC `idrac_virtual_media` module mount the custom ISO as virtual media (virtual CD) in an iDRAC.
1. Using an iDRAC `idrac_boot` module set the boot target to CD and enable a reboot to CD once.
1. Track for the OS deployment for the specified amount of user input time.
1. Eject the virtual media after the specfied time is finished.

Requirements
------------

### Prerequisite
* To Support the HTTP/HTTPS repository as a destination an ssh to a target machine should be enabled to copy the custom iso into a http/https share location.
* To Support the CIFS/NFS repository as a destination the repository needs to be manually mounted to local (ansible controller) copy the custom iso into locally mounted CIFS/NFS share location.
### Development
Requirements to develop and contribute to the role.
```
ansible
python
xorriso
syslinux
isomd5sum
wget
```
### Production
Requirements to use the role.
```
ansible
python
xorriso
syslinux
isomd5sum
wget
```

### Ansible collections
Collections required to use the role
```
dellemc.openmanage
ansible.utils
ansible.windows
```
Role Variables
--------------

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Required</th>
    <th>Default Value</th>
    <th>Choices</th>
    <th>Type</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>hostname</td>
    <td>true</td>
    <td></td>
    <td></td>
    <td>str</td>
    <td>iDRAC IP Address or hostname</td>
  </tr>
  <tr>
    <td>username</td>
    <td>true</td>
    <td></td>
    <td></td>
    <td>str</td>
    <td>iDRAC username with admin privilages</td>
  </tr>
  <tr>
    <td>password</td>
    <td>true</td>
    <td></td>
    <td></td>
    <td>str</td>
    <td>iDRAC user password.</td>
  </tr>
  <tr>
    <td>https_port</td>
    <td>false</td>
    <td>443</td>
    <td></td>
    <td>int</td>
    <td>iDRAC port.</td>
  </tr>
  <tr>
    <td>validate_certs</td>
    <td>false</td>
    <td>true</td>
    <td></td>
    <td>bool</td>
    <td>If C(false), the SSL certificates will not be validated.<br>Configure C(false) only on personally controlled sites where self-signed certificates are used.</td>
  </tr>
  <tr>
    <td>ca_path</td>
    <td>false</td>
    <td></td>
    <td></td>
    <td>path</td>
    <td>The Privacy Enhanced Mail (PEM) file that contains a CA certificate to be used for the validation.</td>
  </tr>
  <tr>
    <td>https_timeout</td>
    <td>false</td>
    <td>30</td>
    <td></td>
    <td>int</td>
    <td> The HTTPS socket level timeout in seconds.</td>
  </tr>
  <tr>
    <td>os_name</td>
    <td>false</td>
    <td></td>
    <td></td>
    <td>str</td>
    <td>- The operating system name to match the jinja template of the kickstart file.</br>- Supported os name is versions for RHEL and ESXI.</br>- Jinja template file should exists in the format `os_name_upper_os_version_major.j2`</td>
  </tr>
  <tr>
    <td>os_version</td>
    <td>false</td>
    <td></td>
    <td></td>
    <td>str</td>
    <td>- The operating system version to match the jinja template of the kickstart file.</br>- Supported versions for RHEL are 9.x and 8.x and for ESXi is 8.x.</br> - Jinja template file should exists in the format `os_name_upper_os_version_major.j2`</td>
  </tr>  
  <tr>
    <td>source</td>
    <td>true</td>
    <td></td>
    <td></td>
    <td>dict</td>
    <td>HTTP/HTTPS share or local path of the ISO.</td>
  </tr>
    <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;protocol</td>
      <td>true</td>
      <td></td>
      <td>["https", "http", "local", "cifs", "nfs"]</td>
      <td>str</td>
      <td>- Type of the the transfer protocol used to download the iso.<br/>- C(https) uses the https protocol to download the iso.<br/>- C(http) uses the http protocol to download the iso.<br/>- C(nfs) uses the locally mounted nfs folder path to download the iso.<br/>- C(cifs) uses the locally mounted cifs folder path to download the iso.<br/>- C(local) uses the local folder path to download the iso.<br/>- If I(custom_iso_true) is C(true) this will be used to mount the custom iso to virtual media.</td>
    </tr>
    <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;hostname</td>
      <td>true</td>
      <td></td>
      <td></td>
      <td>str</td>
      <td>- HTTP/HTTPS address to download the ISO.<br/>- Hostname of the http/https/cifs and nfs to mount the custom iso to virtual media.<br/>- I(hostname) is applicable to download iso only when I(protocol) is C(http) or C(https) and I(is_custom_iso) is C(false).<br/>- I(hostname) is ignored to download the iso when I(protocol) is C(local), C(nfs) or C(cifs) and I(is_custom_iso) is C(false).<br/>- I(hostname) will be used to attach the virtual media when I(is_custom_iso) is C(true).</td>
    </tr>
    <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;iso_path</td>
      <td>true</td>
      <td></td>
      <td></td>
      <td>path</td>
      <td>- Absolute local path or http/https share path of the iso.<br/>- when I(custom_iso) true I(iso_path) should be http, https, nfs or cifs path.</td>
    </tr>
    <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;iso_name</td>
      <td>true</td>
      <td></td>
      <td></td>
      <td>str</td>
      <td>Name of the iso file.</td>
    </tr>
    <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ks_path</td>
      <td>false</td>
      <td></td>
      <td></td>
      <td>path</td>
      <td>- Absolute local path or http/https share path kickstart file.<br/>- When I(ks_path) is provided role skips the generation of kickstart file and uses the one provided in the input.</td>
    </tr>
    <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;is_custom_iso</td>
      <td>false</td>
      <td>false</td>
      <td></td>
      <td>bool</td>
      <td>- Specifies the source iso is a custom iso.<br/>- C(true) uses the custom iso and skips the kickstart file generation and custom iso compilation.<br/>- when C(true), I(destination) is ignored and uses the I(iso_path) to mount the virtual media on idrac.<br/>- C(false) runs the the kickstart file generation and custom iso compilation</td>
    </tr>
    <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;username</td>
      <td>false</td>
      <td></td>
      <td></td>
      <td>str</td>
      <td>- Username of the http, https and cifs share.<br/>- I(username) is applicable only when I(protocol) is C(http) , C(https) to download the iso file.<br/>- I(username) is used to mount the virtual media on idrac and applicable when I(protocol) is C(http), C(https) or C(cifs) and I(is_custom_iso) is C(true).<br/>- I(username) is ignored when I(protocol) is C(local).</td>
    </tr>
    <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;password</td>
      <td>false</td>
      <td></td>
      <td></td>
      <td>str</td>
      <td>- Password of the http, https and cifs share.<br/>- I(password) is applicable only when I(protocol) is C(http) , C(https) to download the iso file.<br/>- I(password) is applicable to mount the custom iso as a virtual media in idrac when I(protocol) is C(http) , C(https), c(cifs) and I(is_custom_iso) is C(true).<br/>- I(password) is ignored when I(protocol) is C(local).</td>
    </tr>
  <tr>
    <td>destination</td>
    <td>true</td>
    <td></td>
    <td></td>
    <td>dict</td>
    <td>- Share path to mount the ISO to iDRAC.<br/>- Share needs to have a write permission to copy the generated ISO.<br/>- CIFS, NFS, HTTP and HTTPS shares are supported.<br/>- I(destination) is ignored when I(is_custom_iso) is C(true)<br>- When the protocol is of C(http), C(https) custom iso is copied into a destination location/folder where the web server content is served.<br/>- When the protocol is of C(cifs), c(nfs) custom iso is copied into the locally mounted nfs or cifs location location.</td>
  </tr>
    <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;protocol</td>
      <td>true</td>
      <td></td>
      <td>["https", "http", "nfs", "cifs"]</td>
      <td>str</td>
      <td>- Type of the the transfer protocol used to mount the virtual media on to idrac.- C(https) uses the ssh protocol to copy the custom iso to the I(mountpoint) and uses https protocol to the mount the virtual media.- C(http) uses the ssh protocol to copy the custom iso to the I(mountpoint) and uses https protocol to the mount the virtual media.- C(nfs) copies the the custom iso to the I(mountpoint) mounted localy and uses nfs protocol to the mount the virtual media.- C(cifs) copies the the custom iso to the I(mountpoint) mounted localy and uses cifs protocol to the mount the virtual media.</td>
    </tr>
    <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;hostname</td>
      <td>true</td>
      <td></td>
      <td></td>
      <td>str</td>
      <td>- Target machine address/hostname where the custom iso will be copied.<br/>- Address/hostname used to mount the iso as a virtual media.<br/>- I(hostname) is applicable to copy iso using ssh when I(protocol) is C(http) or C(https).<br/>- I(hostname) will be defaulted to localhost to copy iso when I(protocol) is C(nfs), C(cifs).<br/> - I(hostname) will be used to mount the virtual media in idrac when I(protocol) is C(http), C(https), C(nfs) or C(cifs).</td>
    </tr>
    <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;iso_path</td>
      <td>true</td>
      <td></td>
      <td></td>
      <td>path</td>
      <td>Custom iso absolute path to be used to mount as a virtual media in idrac.</td>
    </tr>
    <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;iso_name</td>
      <td>false</td>
      <td></td>
      <td></td>
      <td>str</td>
      <td>Custom iso file name. If not specified defaulted to C(hostname-source.iso_name).</td>
    </tr>
    <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;mountpoint</td>
      <td>true</td>
      <td></td>
      <td></td>
      <td>path</td>
      <td>- Target machine absolute path where the custom iso will be copied.<br/>- I(mountpoint) will be path where http/https is served from when I(protocol) is C(http), C(https).<br/>- I(mountpoint) will be local folder mounted with nfs/cifs share when I(protocol) is C(nfs) C(cifs).</td>
    </tr>
     <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;os_type</td>
      <td>false</td>
      <td>linux</td>
      <td>["linux", "windows"]</td>
      <td>str</td>
      <td>HTTP/HTTPS share based on linux/Windows.</td>
    </tr>
    <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;username</td>
      <td>false</td>
      <td></td>
      <td></td>
      <td>str</td>
      <td>Username of the http/https/cifs share where customized ISO is used to mount as a virtual media.</td>
    </tr>
    <tr>
      <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;password</td>
      <td>false</td>
      <td></td>
      <td></td>
      <td>str</td>
      <td>Password of the http/https/cifs share where customized ISO is used to mount as a virtual media.</td>
    </tr>
  <tr>
    <td>wait_for_os_deployment</td>
    <td>false</td>
    <td>true</td>
    <td></td>
    <td>bool</td>
    <td>Wait for the OS deployment to finish.</td>
  </tr>  
  <tr>
    <td>os_deployment_timeout</td>
    <td>false</td>
    <td>30</td>
    <td></td>
    <td>int</td>
    <td>Time in minutes to wait for the OS deployment to finish.</td>
  </tr>
  <tr>
    <td>eject_iso</td>
    <td>false</td>
    <td>true</td>
    <td></td>
    <td>bool</td>
    <td>- Eject the virtual media (ISO) after the tracking of OS deployment is finished.<br/>- ISO will be ejected if I(eject_iso) is C(true) and I(wait_for_os_deployment) is C(true).</td>
  </tr>
  <tr>
    <td>delete_custom_iso</td>
    <td>false</td>
    <td></td>
    <td>true</td>
    <td>bool</td>
    <td>- Deletes the Custom iso after the OS deployment is finshed.<br/>- ISO will be delete if I(delete_custom_iso) is C(true) and I(wait_for_os_deployment) is C(true).</td>
  </tr>
</tbody>
</table>

##  SSH ansible Variables
<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Sample</th>
    <th>Description</th>
  </tr>
</thead>
  <tbody>
    <tr>
      <td>ansible_ssh_user</td>
      <td>user</td>
      <td>Username of the target ssh machine where the custom iso is copied</br>This is used copy/ssh the custom ISO to the destination folder where http/https web server serves the content.</td>
    </tr>
     <tr>
      <td>ansible_ssh_password</td>
      <td>password</td>
      <td>Password of the target ssh machine where the custom iso is copied</br>This is used copy/ssh the custom ISO to the destination folder where http/https web server serves the content.</td>
    </tr>
    <tr>
      <td>ansible_remote_tmp</td>
      <td>C://User//tmp</td>
      <td>Temp directory of the target ssh machine where the custom iso is copied</br>This is used copy/ssh the custom ISO to the destination folder where http/https web server serves the content.</td>
    </tr>
    <tr>
      <td>become_method</td>
      <td>runas</td>
      <td>Overrides the default method of shh</br>This is used copy/ssh the custom ISO to the destination folder where http/https web server serves the content.</td>
    </tr>
    <tr>
      <td>shell_type</td>
      <td>cmd</td>
      <td>Defines the shell type to be used on the target ssh machine where the custom iso is copied</br>This is used copy/ssh the custom ISO to the destination folder where http/https web server serves the content.</td>
    </tr>
  </tbody>
</table>

## Fact variables

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Sample</th>
    <th>Description</th>
  </tr>
</thead>
  <tbody>
    <tr>
      <td>idrac_os_deployment_out</td>
      <td>Successfully deployed the Operating System</td>
      <td>Output of the OS deployment role.</td>
    </tr>
    <tr>
      <td>idrac_os_deployment_failure</td>
      <td>The combination of OS name %s and version %s is not supported.</td>
      <td>Error result of the task</td>
    </tr>
    <tr>
      <td>idrac_os_deployment_kickstart_file</td>
      <td>/tmp/omam_osd_kufwni/kickstart.cfg</td>
      <td>Path of the kickstart file generated or downloaded</td>
    </tr>
    <tr>
      <td>idrac_os_deployment_iso_file</td>
      <td>/tmp/omam_osd_kufwni/rhel.iso</td>
      <td>Path of the iso file downloaded</td>
    </tr>
    <tr>
      <td>idrac_os_deployment_iso_extract_dir</td>
      <td>/tmp/omam_osd_kufwni/extract</td>
      <td>Path of the extract folder created within the tmp directory</td>
    </tr>
    <tr>
      <td>idrac_os_deployment_custom_iso_filename</td>
      <td>198.192.0.1_rhel.iso</td>
      <td>Filename of the custom iso file genereated</td>
    </tr>
    <tr>
      <td>idrac_os_deployment_custom_iso_file</td>
      <td>/tmp/omam_osd_kufwni/198.192.0.1_rhel.iso</td>
      <td>Path of the custom iso file genereated</td>
    </tr>
    <tr>
      <td>idrac_os_deployment_hybrid_cmd</td>
      <td>isohybrid --uefi /tmp/omam_osd_kufwni/198.192.0.1_rhel.iso</td>
      <td>Command isohybrid applied the custom iso file</td>
    </tr>
    <tr>
      <td>idrac_os_deployment_checksum_cmd</td>
      <td>implantisomd5 --uefi /tmp/omam_osd_kufwni/198.192.0.1_rhel.iso</td>
      <td>Command to implant md5 checksum on the custom iso file</td>
    </tr>
     <tr>
      <td>idrac_os_deployment_xorriso_cmd</td>
      <td>xorriso -osirrox -indev /tmp/omam_osd_kufwni/rhel.iso -extract / /tmp/omam_osd_kufwni/extract</td>
      <td>Command xorisso to extract the downloaded iso</td>
    </tr>
      <tr>
      <td>idrac_os_deployment_delegate</td>
      <td>localhost</td>
      <td>Enables the delgate task to run on localhost or container in case of molecules</td>
    </tr>
    <tr>
      <td>idrac_os_deployment_supported_os</td>
      <td>{ RHEL: ["8", "9"], ESXI: ["8"] }</td>
      <td>Hold the map data of supported os name and version</td>
    </tr>
  </tbody>
</table>

## Env Varaibles

When we have to SSH into a machine a fingerprint has to be added into the ansible controller machine for it to connect succesfully, if you trust the machine you are copying you use the below environment variable disable the fingerprint check.

```export ANSIBLE_HOST_KEY_CHECKING=False```

Example Playbook
----------------

```
- name: Generate Kickstart file, custom iso and install RHEL OS
  ansible.builtin.import_role:
    name: idrac_os_deployment
  vars:
    hostname: 192.168.0.1
    username: root
    password: password
    os_name: RHEL
    os_version: 9
    source:
      protocol: https
      hostname: 198.192.0.1
      iso_path: /to/iso
      iso_name: rhel9.iso
    destination:
      protocol: https
      hostname: 198.192.0.1
      mountpath: /user/www/myrepo
      os_type: linux
      iso_path: /to/iso
```
```
- name: Generate custom iso using a kickstart file and install RHEL OS
  ansible.builtin.import_role:
    name: idrac_os_deployment
  vars:
    hostname: 192.168.0.1
    username: root
    password: password
    ca_path: path/to/ca
    os_name: RHEL
    os_version: 9
    source:    
      protocol: https
      hostname: 198.192.0.1
      ks_path: /to/iso/rhel-9.cfg
      path: /to/iso
      iso_name: rhel9.iso    
    destination:      
      protocol: https
      hostname: 198.192.0.1
      mountpath: /user/www/myrepo
      os_type: linux
      iso_path: /to/iso
```
``` 
- name: Install RHEL OS using a custom iso
  ansible.builtin.import_role:
    name: idrac_os_deployment
  vars:
    hostname: 192.168.0.1
    username: root
    password: password
    os_name: RHEL
    os_version: 9
    source:    
      protocol: https
      hostname: 198.192.0.1
      iso_path: /to/iso
      iso_name: custom-rhel.iso
      is_custom_iso: true
```
Author Information
------------------
Dell Technologies <br>
Sachin Apagundi (Sachin_Apagundi@Dell.com) 2023 <br>
Abhishek Sinha (Abhishek.Sinha10@Dell.com) 2023 <br>
Jagadeesh N V (Jagadeesh.N.V@Dell.com) 2023