Skip to content

Testing saltboot deployment

Jump to bottom
Ondřej Holeček edited this page Jul 22, 2022 · 1 revision

To test Saltboot (aka Retail) end-to-end workflow, following these steps and/or checks:

  1. Set up private network
  2. Preparing image building host
  3. Preparing for image building
  4. Transferring image to the Branch server
  5. Preparing branch server for deployment
  6. Preparing Uyuni for deployment - System groups
  7. Configuring System group with Saltboot formula
  8. Individual Terminal installation (no pre-populated details)
  9. Troubleshooting

1. Set up private network

The actual steps how to create private network are not subject of this document, but for the purpose of describing the retail process please make sure you have the private network that will be used by the Branch Server and all the terminals.

Important: Please use similar convention when creating private network as when creating automated test environment, by adding your initials as prefix for the network name.

2. Preparing image building host

  • to prepare for bootstrapping, create an activation key for which you select "OS Image Build Host" as Add-On System Types
  • bootstrap a minion, which will be used as image building host
  • When building SLE12 based images, install package kiwi-desc-saltboot, SLE15 based images do not require any extra steps
  • Important: make sure you apply highstate to complete the configuration of the image build host.

3. Preparing for image building

(Make sure you have applied highstate to complete the configuration of the image build host.)

Image building is done from to SUMA > Images

There are two workarounds in case of problems with suma server machine host resolution during the build of the image:

  • Include package nss-mdns to the kiwi image
  • Adding server FQDN to /etc/hosts on image build machine

Image build host automatically stores the image on the SUMA serevr in this location: /srv/www/os-images/<organization_id>

4. Transferring image to the Branch server

(Important: Do this after the branch server has been configured, as described in Chapter 5)

Transfer the image from SUMA server to the branch server using the command:

salt branch-server state.apply image-sync

On the branch server the image details will be stored in /srv/saltboot.

5. Preparing branch server for deployment

  1. Bootstrap the minion, then install Salt proxy on it.
  2. Configure Salt proxy on the minion. - run configure-proxy.sh
  3. Connect the branch server / proxy to the private network.
  4. Configure the proxy with the following formulas: Dhcpd, Tftpd and Bind. (At this stage the image can be transferred from the SUMA server to the branch server, as described in Chapter 4.)
  5. Add PXE and Branch network formulas too.
  • zypper in bind-formula
  • zypper in dhcpd-formula
  • zypper in tftpd-formula
  • zypper in pxe-formula
  • zypper in branch-network-formula

(Instead of installing all formulas individually, you can also run zypper in -t pattern suma_retail or zypper in -t pattern uyuni_retail)

IMPORTANT: Some values to pay attemtion to:

  • dhcpd -- boot/pxelinux.0
  • bind -- check Forwarders box (this is needed for resolving outside of branch network)
  • bind -- add a global option to set empty-zones-enable to no (this is needed for reverse resolution on the terminals)
  • bind -- use a different domain for branch network as for real network
  • pxe -- /srv/saltboot
  • tftpd -- /srv/saltboot (TFTP base directory) and saltboot (run TFTP under user)
  • saltboot (see Chapter 7 for installation) -- e.g. POS_Image_JeOS7 (NOT the name of the image you created)

6. Preparing system groups

There are 2 mandatory system groups:

  • one system group for terminal type. In case of VMs on x86_64 test server, this group is called: HWTYPE:Intel-Genuine
  • one system group for the branch (use the same name as defined in formula Pxe > Branch Id) and move branch server to this group

7. Configuring System group with Saltboot formula

  • System group corresponding to terminal type must have Saltboot formula configured.
    • zypper in saltboot-formula

8. Individual Terminal installation (no pre-populated details)

Create the new VM which uses PXE booting and runs on the private network. For the purpose of testing this VM's XML file will be manually manipulated to ensure that libvirt picks up the right information regarding the system group of this terminal.

(IMPORTANT: The final solution must allow this assigning to happen automatically and therefore part of these instructions will be removed once they become irrelevant.)

Before making any changes to the VM's (future terminal's) XML, make sure to destroy and undefine it.

8.1 Terminal XML modification

The following snippets must be present in the dumped XML file:

<sysinfo type='smbios'>
  <system>
    <entry name='manufacturer'>Intel</entry>
    <entry name='product'>Genuine</entry>
  </system>
</sysinfo>
<os>
  (...)
  <bootmenu enable='yes'/>
  <smbios mode='sysinfo'/>
</os>
<disk type='file' device='disk'>
  (...)
  <boot order='2'/>
</disk>
<interface type='network'>
  (...)
  <boot order='1'/>
</interface>

Explanations:

  • <sysinfo type='smbios'> section refers to the system group created before, HWTYPE:Intel-Genuine
  • <smbios mode='sysinfo'> refers to the <sysinfo> section above
  • <boot order='...'> statements ensure that PXE has priority over hard disk
8.2 PXE boot

Restart terminal bootstrapping with this amended XML. Some distinctive stages that can be monitored are:

  • the terminal receives a fingerprint
  • the Salt key appears on SUMA server
  • make sure you accept the key for this terminal in the SUMA, so the image downloading can start
  • SUMA will show this terminal in the list of systems (the name of the terminal will start with the branch name)
  • the terminal is assigned to the relevant system groups
  • the image downloads
  • the terminal is installed from the downloaded image
  • the new system is booted

Once the terminal is installed and booted, it will prompt for username and password.

9. Troubleshooting

Here is a list of known issues when deploying images and bootstrapping terminals:

  1. DHCP can be dangerous! Before you configure the dhcpd formula, make sure that the network card for private (branch) network is configured, and that you use that card in the formula.

  2. By default, the JeOS6 image has no virtio disk driver.

    • If you use the Kiwi profile provided by the test suite (*), this driver is added.
    • If you use the standard profiles, declare a SATA disk and access it via /dev/sda

  3. By default, no images have root user.

    • If you use the Kiwi profile provided by the test suite (*), the root user is created for you.
    • If you use the standard profiles, use Salt to create the users:
      $ salt $terminal_name user.add $username
      $ salt $terminal_name shadow.gen_password $password
      $ salt $terminal_name shadow.set_password $username $encrypted_password

(*) at https://github.com/uyuni-project/uyuni/tree/master/testsuite/features/profiles/Kiwi/POS_Image-JeOS6.

  1. For issues with fstab, check that there is no Saltboot formula configured for both TERMINALS and HWType Group (this happened when I used yaml file to set up the branch server).

  2. Have you made any changes on the branch server? If yes, then Apply Highstate.

Clone this wiki locally