8 Image Building and Management

The containers feature is available for Salt minions running SUSE Linux Enterprise Server 12 or later. Before you begin, ensure your environment meets these requirements:

To build images with Uyuni, you will need to create and configure a build host. Build hosts are Salt minions running SUSE Linux Enterprise 12 or later. This section guides you though the initial configuration for a build host.

From the Uyuni Web UI perform these steps to configure a build host.

8.2.2.1 Define Container Build Channels with an Activation Key #

Create an activation key associated with the channel that your images will use.

Note: Relationship Between Activation Keys and Image Profiles

To build containers, you will need an activation key that is associated with a channel other than "SUSE Manager Default".

1. Select Main Menu › Systems › Activation Keys.

2. Click Create Key.

3. Enter a Description and a Key name. Use the drop-down menu to select the Base Channel to associate with this key.

4. Confirm with Create Activation Key.

For more information, see Chapter 7, Activation Key Management.

Define a location to store all of your images by creating an Image Store.

Manage Image Profiles from the Image Profile page.

https://github.com/USER/project.git#branchname:folder

https://github.com/ORG/project.git#branchname:folder

If your git repository is private and not publicly accessible, you need to modify the profile’s git URL to include authentication. Use this URL format to authenticate with a Github token:

https://USER:<AUTHENTICATION_TOKEN>@github.com/USER/project.git#master:/container/

https://gitlab.example.com/USER/project.git#master:/container/

https://gitlab.example.com/GROUP/project.git#master:/container/

https://gitlab-ci-token:<AUTHENTICATION_TOKEN>@gitlab.example.com/USER/project.git#master:/container/

Important: Specifying a Github or Gitlab Branch

If a branch is not specified, the master branch will be used by default. If a folder is not specified the image sources (Dockerfile sources) are expected to be in the root directory of the Github or Gitlab checkout.

This section contains an example Dockerfile. You specify a Dockerfile that will be used during image building when creating an image profile. A Dockerfile and any associated scripts should be stored within an internal or external Github or Gitlab repository:

Important: Required Dockerfile Lines

The Dockerfile provides access to a specific repository version served by Uyuni. This example Dockerfile is used by Uyuni to trigger a build job on a build host minion. The ARG parameters ensure that the image that is built is associated with the desired repository version served by Uyuni. The ARG parameters also allow you to build image versions of SUSE Linux Enterprise Server which may differ from the version of SUSE Linux Enterprise Server used by the build host itself.

For example: The ARG repo parameter and the echo command pointing to the repository file, creates and then injects the correct path into the repository file for the desired channel version.

The repository version is determined by the activation key that you assigned to your image profile.

FROM registry.example.com/sles12sp2
MAINTAINER Tux Administrator "tux@example.com"

### Begin: These lines Required for use with {productname}

ARG repo
ARG cert

# Add the correct certificate
RUN echo "$cert" > /etc/pki/trust/anchors/RHN-ORG-TRUSTED-SSL-CERT.pem

# Update certificate trust store
RUN update-ca-certificates

# Add the repository path to the image
RUN echo "$repo" > /etc/zypp/repos.d/susemanager:dockerbuild.repo

### End: These lines required for use with {productname}

# Add the package script
ADD add_packages.sh /root/add_packages.sh

# Run the package script
RUN /root/add_packages.sh

# After building remove the repository path from image
RUN rm -f /etc/zypp/repos.d/susemanager:dockerbuild.repo

This is an example add_packages.sh script for use with your Dockerfile:

#!/bin/bash
set -e

zypper --non-interactive --gpg-auto-import-keys ref

zypper --non-interactive in python python-xml aaa_base aaa_base-extras net-tools timezone vim less sudo tar

Note: Packages Required for Inspecting Your Images

To inspect images and provide the package and product list of a container to the Uyuni Web UI you will need to install python and python-xml within the container. If these packages remain uninstalled, your images will still build, but the package and product list will be unavailable from the Web UI.

There are two ways to build an image. You can select Images › Build from the left navigation bar, or click the build icon in the Images › Profiles list.

You can import and inspect arbitrary images. Select Images › Images from the left navigation bar. Complete the text boxes of the Import dialog. Once it has processed, the imported image will be listed on the Images page.

The entry for the image is created in the database, and an Inspect Image action on Uyuni is scheduled.

Once it has been processed, you can find the imported image in the Images list. It has a different icon in the Build column, to indicate that the image is imported (see screenshot). The status icon for the imported image can also be seen on the Overview tab for the image.

These are some known problems that you might encounter when working with images:

OS image building is disabled by default. You can enable it in /etc/rhn/rhn.conf by setting:

java.kiwi_os_image_building_enabled = true

Restart the Spacewalk service to pick up the changes:

spacewalk-service restart

The Kiwi image building feature is available for Salt minions running SUSE Linux Enterprise Server 12 or later.

Kiwi image configuration files and configuration scripts must be accessible in one of these locations:

Example scripts are provided in the following sections.

To build all kinds of images with Uyuni, create and configure a build host. Build hosts are Salt minions running SUSE Linux Enterprise Server 12 or later. This procedure will guide you though the initial configuration for a build host.

From the Uyuni Web UI perform these steps to configure a build host:

Uyuni Web Server Public Certificate RPM. Build host provisioning copies the Uyuni certificate RPM to the build host. This certificate is used for accessing repositories provided by Uyuni.

The certificate is packaged in RPM by the mgr-package-rpm-certificate-osimage package script. The package script is called automatically during a new Uyuni installation.

When you upgrade the spacewalk-certs-tools package, the upgrade scenario will call the package script using the default values. However if the certificate path was changed or unavailable, you will need to call the package script manually using --ca-cert-full-path <path_to_certificate> after the upgrade procedure has finished.

Package script call example. 

/usr/sbin/mgr-package-rpm-certificate-osimage --ca-cert-full-path /root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT

The RPM package with the certificate is stored in a salt-accessible directory such as /usr/share/susemanager/salt/images/rhn-org-trusted-ssl-cert-osimage-1.0-1.noarch.rpm.

The RPM package with the certificate is provided in the local build host repository /var/lib/Kiwi/repo.

Important: The RPM Package with the Uyuni Certificate Must Be Specified in the Build Source

Make sure your build source Kiwi configuration contains rhn-org-trusted-ssl-cert-osimage as a required package in the bootstrap section.

config.xml. 

...
  <packages type="bootstrap">
    ...
    <package name="rhn-org-trusted-ssl-cert-osimage" bootinclude="true"/>
  </packages>
...

8.3.3.1 Define Kiwi Build Channels with an Activation Key #

Create an activation key associated with the channel that your images will use. Activation keys are mandatory for OS Image building.

Note: Relationship Between Activation Keys and Image Profiles

To build OS Images, you will need an activation key that is associated with a channel other than "SUSE Manager Default".

1. In the Web UI, select Main Menu › Systems › Activation Keys.

2. Click Create Key.

3. Enter a Description, a Key name, and use the drop-down box to select a Base Channel to associate with the key.

4. Confirm with Create Activation Key.

For more information, see Chapter 7, Activation Key Management.

OS images can require a significant amount of storage space. Therefore, we recommended that the OS image store is located on a partition of its own or on a btrfs subvolume, separate from the root partition. By default, the image store will be located at /srv/www/os-images.

Note: Image stores for Kiwi build type

Image stores for Kiwi build type, used to build system, virtual and other images, are not supported yet.

Images are always stored in /srv/www/os-images/<organization id> and are accessible via HTTP/HTTPS https://<susemanager_host>/os-images/<organization id>

Manage Image Profiles using the Web UI.

Kiwi sources consist at least of config.xml. Usually config.sh and images.sh are present as well. Sources can also contain files to be installed in the final image under the root subdirectory.

For information about the Kiwi build system, see the Kiwi documentation.

SUSE provides examples of fully functional image sources at the SUSE/manager-build-profiles public GitHub repository.

Example of JeOS config.xml. 

<?xml version="1.0" encoding="utf-8"?>

<image schemaversion="6.1" name="POS_Image_JeOS6">
    <description type="system">
        <author>Admin User</author>
        <contact>noemail@example.com</contact>
        <specification>SUSE Linux Enterprise 12 SP3 JeOS</specification>
    </description>
    <preferences>
        <version>6.0.0</version>
        <packagemanager>zypper</packagemanager>
        <bootsplash-theme>SLE</bootsplash-theme>
        <bootloader-theme>SLE</bootloader-theme>

        <locale>en_US</locale>
        <keytable>us.map.gz</keytable>
        <timezone>Europe/Berlin</timezone>
        <hwclock>utc</hwclock>

        <rpm-excludedocs>true</rpm-excludedocs>
        <type boot="saltboot/suse-SLES12" bootloader="grub2" checkprebuilt="true" compressed="false" filesystem="ext3" fsmountoptions="acl" fsnocheck="true" image="pxe" kernelcmdline="quiet"></type>
    </preferences>
    <!--    CUSTOM REPOSITORY
    <repository type="rpm-dir">
      <source path="this://repo"/>
    </repository>
    -->
    <packages type="image">
        <package name="patterns-sles-Minimal"/>
        <package name="aaa_base-extras"/> <!-- wouldn't be SUSE without that ;-) -->
        <package name="kernel-default"/>
        <package name="salt-minion"/>
        ...
    </packages>
    <packages type="bootstrap">
        ...
        <package name="sles-release"/>
        <!-- this certificate package is required to access {productname} repositories
             and is provided by {productname} automatically -->
        <package name="rhn-org-trusted-ssl-cert-osimage" bootinclude="true"/>

    </packages>
    <packages type="delete">
        <package name="mtools"/>
        <package name="initviocons"/>
        ...
    </packages>
</image>

There are two ways to build an image using the Web UI. Either select Main Menu › Images › Build, or click the build icon in the Main Menu › Images › Profiles list.

After the image is successfully built, the inspection phase begins. During the inspection phase SUSE Manager collects information about the image:

Note

If the built image type is PXE, a Salt pillar will also be generated. Image pillars are stored in the /srv/susemanager/pillar_data/images/ directory and the Salt subsystem can access details about the generated image. Details include where the pillar is located and provided, image checksums, information needed for network boot, and more.

The generated pillar is available to all connected minions.

Building an image requires of several dependent steps. When the build fails, investigation of salt states results can help you to identify the source of the failure. Usual checks when the build fails:

The section contains some known issues when working with images.