StarlingX build tools
Go to file
Jiping Ma 3994bd147d Enable OOT drivers i40e, iavf
In order to deal with a firmware incompatibility or if a problem is
found with the in-tree driver, we want to continue to support one
version of each out-of-tree driver. Since the versions have already
been validated. We will be preserving i40e 2.20.12, iavf 4.5.3.2,
and ice 1.9.11as OOT drivers, along with the NVME update utility
version 9.20 for the 700 series NICs and version 4.22 for the E810
series of NICs.

We only enable i40e and iavf here because ice is already enabled in
the previous commit "Use the in-tree drivers in initramfs".

Verification:
- installs from iso succeed on servers with ice(ntel E810-2C-QDA2
  Chapman beach) and i40e hw(Intel Ethernet Controller X710) for
  rt and std.
- interfaces are up and pass packets for rt and std.
- create vfs, ensure that they are picked up by the new iavf
  driver and that the interface can come up and pass packets
  on rt and std system.
- Check dmesg to see DDP package is loaded successfully and
  the version is 1.3.30.0 for rt and std.

Story: 2011056
Task: 49672

Depends-On: https://review.opendev.org/c/starlingx/kernel/+/911397
Change-Id: I1c4a76ca3e11199349e744e64cc052b50166444e
Signed-off-by: Jiping Ma <jiping.ma2@windriver.com>
2024-03-06 02:19:39 -05:00
centos-mirror-tools Fix https port 2023-12-01 15:25:40 -05:00
cve_support cve_policy_filter: Create new list to track the fixed LP CVE issue 2022-12-04 21:01:51 -05:00
debian-mirror-tools/config/debian Enable OOT drivers i40e, iavf 2024-03-06 02:19:39 -05:00
doc Fix tox-docs failing sphinx 2023-08-30 09:25:39 -03:00
release cengn reference removal - centos 2023-11-07 11:23:12 -05:00
releasenotes Switch to newer openstackdocstheme and reno versions 2020-06-04 14:39:04 +02:00
stx LAT: update to lat-sdk-20231206 2023-12-07 23:36:35 +08:00
toCOPY Lock requests to 2.27.1 for py 2.7 compatibility 2022-06-13 09:47:37 -04:00
.dockerignore update .dockerignore for debian build containers 2021-09-27 10:16:30 -04:00
.gitignore import-stx: Avoid divide by zero 2022-01-31 13:17:16 -05:00
.gitreview Update .gitreview for f/kernel-6.6 2024-01-25 10:52:53 -05:00
.yamllint stx tool: control: Add the support of control module 2021-09-15 21:35:47 -04:00
.zuul.yaml Fix github mirroring for this repo 2023-04-28 12:38:53 -04:00
buildrc Restore buildrc 2020-10-14 15:58:57 -04:00
DependenciesReviewer.py rename cgcs-centos-repo to centos-repo 2020-09-18 22:32:41 -04:00
Dockerfile cengn reference removal - centos 2023-11-07 11:23:12 -05:00
import-stx Override builder images registry path 2023-05-15 12:43:36 -04:00
import-stx.README Update Debian build system to support Kubernetes 2022-02-11 11:05:12 -08:00
localrc-compiler feat: Modify layer build process 2022-06-21 16:39:26 +00:00
localrc-distro feat: Modify layer build process 2022-06-21 16:39:26 +00:00
localrc-flock feat: Modify layer build process 2022-06-21 16:39:26 +00:00
pylint.rc stx-tool: config: Add the support of config module 2021-09-01 03:54:44 -04:00
README.rst rename cgcs-centos-repo to centos-repo 2020-09-18 22:32:41 -04:00
stx-init-env stx-init-env: new option --no-start 2023-12-06 11:25:46 -05:00
stx.conf.sample stx.conf.sample: fix stx_mirror_url 2023-11-09 10:52:04 -05:00
tb.sh feat: Modify layer build process 2022-06-21 16:39:26 +00:00
test-requirements.txt stx tool: control: Add the support of control module 2021-09-15 21:35:47 -04:00
tox.ini cengn reference removal - debian 2023-11-07 21:31:00 -05:00

tools

StarlingX Build Tools

The StarlingX build process is tightly tied to CentOS in a number of ways, doing the build inside a Docker container makes this much easier on other flavors of Linux. Basically, the StarlingX ISO image creation flow involves the following general steps.

  1. Build the StarlingX docker image.
  2. Package mirror creation.
  3. Build packages/ISO creation.

Build the Starlingx docker image

StarlingX docker image handles all steps related to StarlingX ISO creation. This section describes how to customize the docker image building process.

Container build image customization

You can start by customizing values for the StarlingX docker image build process. There are a pair of useful files that help to do this.

  • buildrc
  • localrc

The buildrc file is a shell script that is used to set the default configuration values. It is contained in the tbuilder repo and should not need to be modified by users as it reads a localrc file that will not be overwritten by tbuilder updates. This is where users should alter the default settings. This is a sample of a localrc file:

# tbuilder localrc
MYUNAME=<your user name>
PROJECT=starlingx
HOST_PREFIX=$HOME/starlingx/workspace
HOST_MIRROR_DIR=$HOME/starlingx/mirror

This project contains a Makefile that can be used to automate the build lifecycle of a container. The Makefile will read the contents of the buildrc file.

StarlingX Builder container image are tied to your UID so image names should include your username.

Build image

Once the configuration files have been customized, it is possible to build the docker image. This process is automated by the tb.sh script.

./tb.sh create

NOTE:

  • Do NOT change the UID to be different from the one you have on your host or things will go poorly. i.e. do not change --build-arg MYUID=$(id -u)
  • The Dockerfile needs MYUID and MYUNAME defined, the rest of the configuration is copied in via buildrc/localrc.

Package mirror creation

Once the StarlingX docker image has been built, you must create a mirror before creating the ISO image. Basically, a mirror is a directory that contains a series of packages. The packages are organized to be consumed by the ISO creation scripts.

The HOST_MIRROR_DIR variable provides the path to the mirror. The buildrc file sets the value of this variable unless the localrc file has modified it.

The mirror creation involves a set of scripts and configuration files required to download a group of RPMs, SRPMs, source code packages and so forth. These tools live inside centos-mirror-tools directory.

$ cd centos-mirror-tools

All items included in this directory must be visble inside the container environment. Then the container shall be run from the same directory where these tools are stored. Basically, we run a container with the previously created StarlingX docker image, using the following configuration:

$ docker run -it -v $(pwd):/localdisk <your_docker_image_name>:<your_image_version> bash

As /localdisk is defined as the workdir of the container, the same folder name should be used to define the volume. The container will start to run and populate logs and output folders in this directory.

Download packages

Inside the Docker container, enter the following commands to download the required packages to populate the CentOS mirror repository:

$ cd localdisk && bash download_mirror.sh

Monitor the download of packages until it is complete. When the download is complete, the following message appears:

totally 17 files are downloaded! step #3: done successfully IMPORTANT: The following 3 files are just bootstrap versions. Based on them, the workable images for StarlingX could be generated by running "update-pxe-network-installer" command after "build-iso" - out/stx/CentOS/Binary/LiveOS/squashfs.img - out/stx/CentOS/Binary/images/pxeboot/initrd.img - out/stx/CentOS/Binary/images/pxeboot/vmlinuz

Verify packages

Verify no missing or failed packages exist:

$ cat logs/_missing_.log $ cat logs/_failmove_.log

In case missing or failed packages do exist, which is usually caused by network instability (or timeout), you need to download the packages manually. Doing so assures you get all RPMs listed in rpms_3rdparties.lst/rpms_centos.lst/rpms_centos3rdparties.lst.

Copy the files to the mirror

After all downloads are complete, copy the downloaded files to mirror.

$ find ./output -name "*.i686.rpm" | xargs rm -f $ chown 751:751 -R ./output $ cp -rf output/stx/ <your_mirror_folder>/

In this case, <your_mirror_folder> can be whatever folder you want to use as mirror.

Tweaks in the StarlingX build system.

NOTE: You do not need to do the following step if you've synced the latest codebase.

Go into the StarlingX build system (i.e. another container that hosts the build system) and perform the following steps:

Build packages/ISO creation

StarlingX ISO image creation required some customized packages. In this step, a set of patches and customizations are applied to the source code to create the RPM packages. We have an script called tb.sh that helps with the process.

The tb.sh script is used to manage the run/stop lifecycle of working containers. Copy it to somewhere on your PATH, say $HOME/bin if you have one, or maybe /usr/local/bin.

The basic workflow is to create a working directory for a particular build, say a specific branch or whatever. Copy the buildrc file from the tbuilder repo to your work directory and create a localrc if you need one. The current working directory is assumed to be this work directory for all tb.sh commands. You switch projects by switching directories.

By default LOCALDISK will be placed under the directory pointed to by HOST_PREFIX, which defaults to $HOME/starlingx.

The tb.sh script uses sub-commands to select the operation: * run - Runs the container in a shell. It will also create LOCALDISK if it does not exist. * stop - Kills the running shell. * exec - Starts a shell inside the container.

You should name your running container with your username. tbuilder does this automatically using the USER environment variable.

tb.sh run will create LOCALDISK if it does not already exist before starting the container.

Set the mirror directory to the shared mirror pointed to by HOST_MIRROR_DIR. The mirror is LARGE, if you are on a shared machine use the shared mirror. For example you could set the default value for HOST_MIRROR_DIR to $HOME/starlingx/mirror and share it.

Running the Container

Start the builder container:

tb.sh run

or by hand:

docker run -it --rm \
    --name ${TC_CONTAINER_NAME} \
    --detach \
    -v ${LOCALDISK}:${GUEST_LOCALDISK} \
    -v ${HOST_MIRROR_DIR}:/import/mirrors:ro \
    -v /sys/fs/cgroup:/sys/fs/cgroup:ro \
    -v ~/.ssh:/mySSH:ro \
    -e "container=docker" \
    --security-opt seccomp=unconfined \
    ${TC_CONTAINER_TAG}

Running a Shell Inside the Container

Since running the container does not return to a shell prompt the exec into the container must be done from a different shell:

tb.sh exec

or by hand:

docker exec -it --user=${MYUNAME} ${USER}-centos-builder bash

Notes:

  • The above will reusult in a running container in systemd mode. It will have NO login.
  • I tend to use tmux to keep a group of shells related to the build container
  • --user=${USER} is the default username, set MYUNAME in buildrc to change it.

Stop the Container

tb.sh stop

or by hand:

docker kill ${USER}-centos-builder

What to do to build from WITHIN the container

To make git cloning less painful

$ eval $(ssh-agent)
$ ssh-add

To start a fresh source tree

Instructions

Initialize the source tree.

cd $MY_REPO_ROOT_DIR
repo init -u https://opendev.org/starlingx/manifest.git -m default.xml
repo sync

To generate centos-repo

The centos-repo is a set of symbolic links to the packages in the mirror and the mock configuration file. It is needed to create these links if this is the first build or the mirror has been updated.

generate-centos-repo.sh /import/mirrors/CentOS

Where the argument to the script is the path of the mirror.

To build all packages:

$ cd $MY_REPO
$ build-pkgs or build-pkgs --clean <pkglist>; build-pkgs <pkglist>

To generate local-repo:

The local-repo has the dependency information that sequences the build order; To generate or update the information the following command needs to be executed after building modified or new packages.

$ generate-local-repo.sh

To make an iso:

$ build-iso

First time build

The entire project builds as a bootable image which means that the resulting ISO needs the boot files (initrd, vmlinuz, etc) that are also built by this build system. The symptom of this issue is that even if the build is successful, the ISO will be unable to boot.

For more specific instructions on how to solve this issue, please the README on installer folder in metal repository.

WARNING HACK WARNING

  • Due to a lack of full udev support in the current build container, you need to do the following:

    $ cd $MY_REPO
    $ rm build-tools/update-efiboot-image
    $ ln -s /usr/local/bin/update-efiboot-image $MY_REPO/build-tools/update-efiboot-image
  • if you see complaints about udisksctl not being able to setup the loop device or not being able to mount it, you need to make sure the build-tools/update-efiboot-image is linked to the one in /usr/local/bin

Troubleshooting

  • if you see:

    Unit tmp.mount is bound to inactive unit dev-sdi2.device. Stopping, too.
  • it's a docker bug. just kill the container and restart the it using a different name.

    • I usually switch between -centos-builder and -centos-builder2. It's some kind of timeout (bind?) issue.