diff --git a/modules/retail/pages/containerized-saltboot.adoc b/modules/retail/pages/containerized-saltboot.adoc index 9c7b2b7db0d..afde64494fa 100644 --- a/modules/retail/pages/containerized-saltboot.adoc +++ b/modules/retail/pages/containerized-saltboot.adoc @@ -4,72 +4,74 @@ To set up the {productname} {smr} environment, you will need to have already installed and configured: * {productname} {smr} Server 4.3 or newer +* {productname} {smr} Server * one or more {productname} {smr} containerized proxies * one or more {productname} build host This section covers how to configure your environment using containerized {productname} Proxy for [systemitem]``Saltboot`` deployment. - [IMPORTANT] ==== -Containerized workflow requires POS images build using {productname} Server 4.3 or newer. -Older images will not work. +Containerized workflow not longer implicitly configures DHCP for PXE booting. +Without the formula, make sure your DHCP server has correct PXE booting setting pointing to containerized proxy. +For more information how to use DHCP formula to configure DHCP server, see xref:specialized-guides:salt/salt-formula-dhcpd.adoc[]. ==== -[IMPORTANT] -==== -Containerized workflow not longer implicitly configure DHCP for PXE booting. -See xref:specialized-guides:salt/salt-formula-dhcpd.adoc[] how to use DHCP formula to configure DHCP server. -Without using DHCP formula, make sure your DHCP server has correct PXE booting setting pointing to containerized proxy. -See below for example. -==== +== Requirements and assumptions -== Assumptions +* Containerized workflow requires POS images build using {productname} Server 4.3 or newer. + Older images will not work. -In this example we are going to use branch id [systemitem]``B0001``. +* In this example we are going to use branch id [systemitem]``B0001``. -As a terminal we assume to have one terminal with hardware manufacturer [systemitem]``TerminalOEM`` and model [systemitem]``T1000``. +* As a terminal we assume to have one terminal with hardware manufacturer [systemitem]``TerminalOEM`` and model [systemitem]``T1000``. -For POS image we assume to have one with name [systemitem]``POS_Image_JeOS7``. +* For POS image we assume to have one with name [systemitem]``POS_Image_JeOS7``. == Create required system groups -Follow guide xref:reference:systems/system-groups.adoc[] to create the system groups: - -- [systemitem]``TERMINALS`` -- [systemitem]``HWType:TerminalOEM-T1000`` -- [systemitem]``B0001`` - -First group is generic optional group for collecting all POS terminals. Second group is hardware type group for our POS terminal. Third group is mandatory branch group. - +.Procedure +. Create the following three system groups. + For guidelines on how to create the groups, see xref:reference:systems/system-groups.adoc[]. + + - [systemitem]``TERMINALS`` + - [systemitem]``HWType:TerminalOEM-T1000`` + - [systemitem]``B0001`` ++ +The first group is generic optional group for collecting all POS terminals. +The second group is hardware type group for our POS terminal. +The third group is mandatory branch group. ++ For more information about {saltboot} groups, see xref:retail:retail-install-setup.adoc[]. - -We assign [systemitem]``Saltboot Group`` formula to group [systemitem]``B0001`` we just created. With this, our branch group is converted to [systemitem]``Saltboot Group``. ++ +. Assign [systemitem]``Saltboot Group`` formula to group [systemitem]``B0001`` we just created. + This converts the branch group to [systemitem]``Saltboot Group``. == {saltboot} group Containerized {productname} {smr} is configured in [systemitem]``Saltboot Group``. -{saltboot} Groups are branch groups, system group with branch id as its name, with [systemitem]``Saltboot Group`` formula enabled. - -image::saltboot_group.png[scaledwidth=80%] +{saltboot} groups are branch groups, system group with [systemitem]``branch id`` as its name and [systemitem]``Saltboot Group`` formula enabled. [systemitem]``Saltboot Group`` formula is a successor of [systemitem]``Branch Network formula``, [systemitem]``PXE formula`` and [systemitem]``TFTP formula`` used in regular {productname} {smr} setups. -Name of the [systemitem]``Saltboot group`` is automatically used as a [systemitem]``branch id``, an identifier for group of machines booted through particular containerized {productname} Proxy. +Name of the [systemitem]``Saltboot Group`` is automatically used as a [systemitem]``branch id``, an identifier for group of machines booted through particular containerized {productname} Proxy. All [systemitem]``Saltboot`` deployed machines though containerized proxy will automatically became members of its [systemitem]``Saltboot group``. -To connect [systemitem]``Saltboot group`` with containerized proxy fill [systemitem]``Image Download Server`` entry with Fully Qualified Domain Name ([literal]``FQDN``) of the containerized proxy. +To connect [systemitem]``Saltboot group`` with containerized proxy, fill [systemitem]``Image Download Server`` entry with Fully Qualified Domain Name ([literal]``FQDN``) of the containerized proxy. + +With this, mandatory configuration is finished. +The rest of configuration is optional. -With this, mandatory configuration is finished. The rest of configuration is optional. === Default boot image Configure [systemitem]``Default boot image for new registrations`` to specify what boot image should be booted by not yet registered POS terminal. + This is useful when stable boot image is wanted for initial deployments. Without this setting, newest built boot image is used as default boot image. @@ -80,11 +82,13 @@ If [systemitem]``Default boot image for new registrations`` is set, option to se Option [systemitem]``Kernel parameters for the group`` can be used to pass extra kernel options to all POS terminals registered withing this {saltboot} group. + === Naming scheme for new registrations Last three options are related to how will be newly registered machine visible in {productname} Server. -See xref:retail:retail-terminal-names.adoc[] for explanation of possible configurations. +For explanation of possible configurations, see xref:retail:retail-terminal-names.adoc[]. + == Comparing containerized and non-containerized workflows @@ -92,15 +96,15 @@ External DHCP service must be used with containerized {saltboot}. For more information about how to enable PXE booting in DHCP service, see xref:retail:retail-install-setup.adoc[]. -Containerized workflow relies on updated image building in {productname} Server 4.3 where PXE images are no longer collected as bundle, but kernel, initrd and filesystem image are collected individually. +Containerized workflow relies on updated image building in {productname} Server 4.3, where PXE images are no longer collected as bundle, but kernel, initrd and filesystem image are collected individually. Containerized workflow uses new TFTP container which instead of providing files present on the proxy, routes TFTP requests as HTTP requests through local proxy to {productname} Server. -Containerized proxy is not a Salt client, it is not possible to call [systemitem]``image-sync`` state. +Containerized proxy is not a {salt} client, it is not possible to call [systemitem]``image-sync`` state. [IMPORTANT] ==== -Once POS image is build and made available on {productname} Server, it is immediately available to the {saltboot} clients as well. +Once POS image is built and made available on {productname} Server, it is immediately available to the {saltboot} clients as well. Image synchronization is not needed, nor available. This may have implications on how images are deployed to production. ==== @@ -108,16 +112,15 @@ This may have implications on how images are deployed to production. The following sections differentiate between containerized and regular workflow. Both are assuming proxy (containerized or in form of {productname} {smr} Branch Server) are available. -Containerized workflow: +.Procedure: Deploying with containerized workflow . Build POS image . Configure DHCP server for PXE booting for given network . Create [systemitem]``Saltboot group`` and configure it for existing containerized proxy . Boot system to be deployed -Non-Containerized workflow: - +.Procedure: Deploying with non-ontainerized workflow . Build POS image . Configure and apply Retail formulas on {productname} {smr} Branch server . Apply [systemitem]``highstate`` state on the Branch server @@ -125,14 +128,14 @@ Non-Containerized workflow: . Apply [systemitem]``image-sync`` state on configured {productname} {smr} Branch server . Boot system to be deployed + == Validating {saltboot} group configuration [systemitem]``Containerized Saltboot`` utilizes [systemitem]``Cobbler`` system underneath for managing PXE and UEFI configuration. - When new PXE image is built (such as {productname} {smr} POS_Image_JeOS images) [systemitem]``cobbler distro`` and [systemitem]``cobbler profile`` are automatically generated for this image. -For example when first image [literal]``POS_Image_JeOS`` version [literal]``7.0.0`` is build under organization with number 1 [command]``cobbler list`` will show: +For example, when first image [literal]``POS_Image_JeOS`` version [literal]``7.0.0`` is build under organization with number 1 [command]``cobbler list`` will show: ---- # cobbler list @@ -178,4 +181,4 @@ Kernel options in example are always present and are internal for {saltboot} fun With this information [systemitem]``Cobbler`` is able to generate required PXE and UEFI Grub configurations which can be checked in [path]``/srv/tftpboot/pxelinux.cfg/default`` and [path]``/srv/tftpboot/grub/x86_64_menu_items.cfg``. -These files contain the end result which will be used by PXE client when determining what to boot and with what parameters. +These files contain the end result which will be used by PXE client when determining what to boot and with which parameters.