Skip to content

Eikon Image Deploy

The Eikon plugin deploys images to systems. These images can be tarballs that get untarred onto defined partition-based filesystems or raw storage images that get copied onto defined storage devices. In either case, additional files can be injected into the images for post-install operations.

The eikon-image-deploy pipeline injects and attempts to start the drpcli agent during deployment. This allows introspection during deployment under most circumstances. When not possible, the pipeline injects scripts to allow cloud-init or another process to run on first boot. For Windows, the script will be C:\eikon-win-agent.ps1. This has all the necessary information to configure and start the agent once run.

The eikon system is purpose built to deploy images and continue to run further pipelines. Like image-deploy, Eikon can interpret curtin configurations. Curtin is driven by a configuration YAML file that is built dynamically based upon the value of parameters. These parameters drive the actual imaging process. Eikon also provides a similar configuration schema using parameters that can derive from existing image-deploy parameter values.

Getting Started

Eikon Image Construction

Eikon requires an image. This image can be in many different formats. The format type defines what additional operational parameters that need to be set. These images can be built using RackN's image-builder content pack, using Hashicorp's Packer tool, or other tools that generate images.

  • All drivers should be added to the system in the base image or additional tarball packages. It is possible to add drivers and other packages during deployment, but is left to the customer to manage.

  • It is recommended that the image should be built for the the boot-style of the target hardware. If the system is going to boot in UEFI mode, then the disk image should be formatted with EFI partitions that hold EFI bootloaders. The same applies for legacy systems. There are disk layouts that can work for both.

  • The version of sledgehammer or ubuntuhammer used for deployment should be compatible with the target OS. Newer OS versions may require newer kernel versions and tools to properly deploy. Eikon supports both sledgehammer and ubuntuhammer as deployment OSes.

Another consideration during image construction is how the next phase of operation starts. For Windows, this could be an unattend.xml that is part of the image or is injected by additional parameters. It could also mean that cloud-init or cloudbase-init is installed and set to automatically start. Eikon can also inject scripts to install a runner for the OS type in question. These could also be called to install the agent as well. Depending upon the choice of startup method, different packages and configurations may need to be added to the image.

Eikon Operations

Once an image is built, the system needs to know where it is, what type of image it is, where the image is to be deployed, and optionally what startup process to use. These are all defined as parameters that can be added to a machine. Because all of this information is consistent across all machines using this image, it is best practice to create a profile that contains all these parameters.

To define the location of the image file:

  • eikon/image-url - This is a URL that references the image. You can use template functions such as {{ .ProvisionerURL }}/path/to/file.tar.zst

To define the type and content of the image:

  • eikon/image-type - This is the curtin image type value. These types are define in the parameter and validated by the systems. Available values are available in the parameter definition.

Additional parameters can be used to override and expand the deployement scenario.

You can build more complex storage configurations and deploy layers of images using the eikon/plan parameter.

Eikon Customizations

With the basic parameters set in a profile, additional parameters can be added to drive further customization and enhancements.

Partitioning

When using a raw disk image, the target hard disk can be selected using the image-deploy/install-disk parameter. If this parameter is not specified, /dev/sda is used by default. Custom partitioning when defined this way.

When using a rootfs image, the target hard disk can be selected using the image-deploy/install-disk parameter. If not specified, the system defaults to /dev/sda. A simple GPT-based filesystem layout is then applied, as chosen by Curtin.

A more complex storage and image deployment can be provided for rootfs images by providing an eikon/plan parameter.

Additional Content

The agent binary will be installed as part of the image deployment. For linux, the binary is installed to /usr/local/bin. If selinux is available, a relabel on the file is done to make sure the binary is correctly labeled.

For Windows, the binary is installed to C:\Windows. For compatiblity with curtin and most of our existing Windows tasks, the C:\curtin directory and a link to the binary are created. Due to limitations on ACL access from linux, the permissions are permissive. It is recommended that the directory should be created in the image and appropriately hardened. The jq.exe binary is linked back to drpcli.exe (the client can run standard jq queries using gojq).

Debug and Troubleshooting

To debug issues, use the standard debug parameter rs-debug-enable by setting it to true. There are also two tasks that pause the deployment as an opportunity to login and troubleshoot using ssh or console login.

Sledgehammer Override

Overriding the default sledgehammer may be necessary depending on the target OS. You can use bootenv override profiles such as the sledgehammer-alma9-v4.12.0 profile by adding the profile to the machine, the global profile, or another profile assigned to the machine.

Using Ubuntuhammer

To use Ubuntuhammer as the Eikon deployment OS, first upload the ubuntuhammer iso to the endpoint.

shell drpcli bootenvs uploadiso ubuntuhammer

Next add the param eikon/deployment-os to a profile or machine and set its value to "ubuntuhammer". Then attach that profile to the machine. When you run Eikon it should use ubuntuhammer instead of sledgehammer to deploy the image. This works like other params and can be in a profile directly attached to a machine, or at a global level by placing the param in the global profile. Another helpful global param is the kexec-ok param. Adding it to your global profile and setting the value to true will speed up the process by reducing unnecessary reboots.

Using kexec

Since deployment is almost always contained within linux, it may be possible to use kexec to save a system reset. Set the kexec-ok param to true on the machine. If secure boot is enabled, there is a possibility that kexec will not work on non-rhelish images. If this is the case, the machine will reboot as a fallback.