f5devcentral/f5-bigip-image-generator repository overview

⁠Welcome to the F5 BIG-IP Image Generator Tool for Docker Hub

⁠Introduction

Use this tool to create custom images from the .ISO file for F5 BIG-IP VE releases or for hot-fixes that are not available on the various public cloud marketplaces.

F5 has verified:

• Image Generator Tool v1.0-1.17 on Alpine 3.11.5 operating system
• Image Generator Tool v1.18+ on Alpine 3.15.4 operating system

For complete tool descriptions and uses, see https://github.com/f5devcentral/f5-bigip-image-generator⁠.

⁠Benefits

• Provide pre-deployment file customization of BIG-IP (for example, SSH keys, trusted certificates, custom packages, and so forth).
• Automatically publish BYOL images to public cloud providers.
• Simplify deployment workflows, such as encrypting custom images in AWS (prevents launching an instance in the marketplace first).
• Run multiple containers that take in the same input files and output to the same folder for better organization.
• Build multiple images, concurrently.
• Simplify reproducibility of images on different systems.
• Prevents the need for installing additional programs to your environment.
• Leverages Alpine 3.11.5 images to reduce container image size.

⁠References

The F5 BIG-IP Image Generator is continuously evolving. To provide feedback about using this tool, consult GitHub Issue⁠.

• Documentation: https://clouddocs.f5.com/cloud/public/v1/ve-image-gen_index.html⁠
• GitHub: https://github.com/f5devcentral/f5-bigip-image-generator⁠
• Where to file issues: https://github.com/f5devcentral/f5-bigip-image-generator/issues⁠
• Maintained by: F5 Networks⁠

⁠Usage

The container provides a convenient pre-built runtime with many of the tool’s package dependencies pre-installed (with the exception of VMware’s ovftool). You can enter the container interactively and run the tool from the container’s shell or more typically run it externally from the Docker host (for example, your Desktop, build server, and other similar locations). However, in either case, as the container image itself is small and only providing the tool’s runtime, you will need mount volumes in order to read/write the large input/output files the tool creates.

⁠Mount mappings

Inputs

The tool is located at /f5/build-image and the default location whereby the tool reads input files is the present working directory.

Outputs

The default location whereby the tool writes output files is the tool's /images and /artifacts folders:

• /f5/images
• /f5/artifacts

To simplify/shorten the docker run command you can customize sub-directories in which to store your outputs; for example, images, logs, and artifacts. Then you can point to these sub-directories in your config file and environment variables. For example your Docker directory can look like this:

docker/ 
             config.yml
             BIGIP.iso
             output_images/ .ova or .qcow2
             output_artifacts/ 
             logs/ .log

NOTE: The Docker name is used for example purposes only. You do NOT need to name the folder, "Docker".

Your config file can look like this:

IMAGE_DIR: "/<path>/docker/output_images/"
ARTIFACTS_DIR: "/<path>/docker/output_artifacts/"
LOG_FILE: "/<path>/docker/logs/

⁠Environmental variables

Similar to running the tool outside the container, it is recommended that you use environment variables (versus using the tool’s config file) to pass any credentials. You can use Docker’s -e flag to pass from the Docker host to the container.

For example:

> export AWS_ACCESS_KEY_ID=XXXXXXXXXX
> export AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXXXXXXX
> docker run -e "AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}” -e "AWS_SECRET_ACCESS_KEY= ${AWS_SECRET_ACCESS_KEY}”

> docker run -e "GOOGLE_APPLICATION_CREDENTIALS=application_default_credentials.json"

⁠IMPORTANT

If specifying a file for credentials; for example, application_default_credentials.json, any input or output files (whether specified in the docker run command or the tool’s own config file) instead reference the file from the context of the container’s filesystem and point to a mount.

⁠Example: Run the F5 Image Generator interactively

This example demonstrates running the Image Generator interactively from inside the Docker container.

qcow2

To enter the container's shell:

docker run -it --device="/dev/kvm" -v "/<path>/docker:/mnt" f5devcentral/f5-bigip-image-generator:latest

To run the tool interactively:

bash-5.0# build-image --help
bash-5.0# build-image -c config.yml -i BIGIP-15.0.1-0.0.11.iso -p qcow2 -m ltm -b 1

The previous example demonstrates:

1. Mounting an input directory, containing the input files (for example, ISOs, tool’s config file, custom files to add, and other similar files), from the Docker host’s present working directory to the container’s /mnt directory.

   -v "/<path>/docker/:/mnt" 

2. Mounting the /dev/kvm device which will enable the container to use hardware acceleration, if available.  

   --device="/dev/kvm"
   

   Copy

This is highly recommended, but you must remove that argument, if the host does NOT have KVM acceleration enabled (consult the KVM Virtualization documentation⁠).

1. Running the build-image tool as normal from within the container.

⁠Example: Run the F5 Image Generator container from the Docker host

This example demonstrates running the Image Generator container from the Desktop or build server.

qcow2

docker run -it --rm --device="/dev/kvm" -v "/<path>/docker:/mnt" 
f5devcentral/f5-bigip-image-generator:latest build-image -c config.yml -i BIGIP-15.0.1-0.0.11.iso -p qcow2 -m ltm -b 1

The previous example demonstrates:

1. Removing the stopped container (the one docker run creates), NOT the image on which it is based (what you downloaded) for a one-time CLI-like usage: --rm.

2. Mounting an input directory, containing the input files (for example, ISOs, tool’s config file, custom files to add, and other similar files), from the Docker host’s present working directory to the container’s /mnt directory: -v "$(pwd):/mnt".

3. Mounting the /dev/kvm device which will enable the container to use hardware acceleration, if available: --device="/dev/kvm".

4. Running the build-image image tool as an argument at the end of the docker run command:

   build-image -c config.yml -i BIGIP-15.0.1-0.0.11.iso -p qcow2 -m ltm -b 1
   

   Copy

⁠VERSION NOTIFICATION

Image Generator Tool 1.8 and later, supports config variables that move the /artifacts/ and /images/ directories.

When using Image Generator Tool 1.7 and earlier, you must include these directories in your Docker command by adding volumes like:

-v "$(pwd)/images:/f5/images" -v "$(pwd)/artifacts:/f5/artifacts"

For a qcow2 command example, use:

docker run -it --rm --device="/dev/kvm" -v "$(pwd):/mnt" -v "$(pwd)/images:/f5/images" -v "$(pwd)/artifacts:/f5/artifacts"
f5devcentral/f5-bigip-image-generator:latest build-image -c config.yml -i BIGIP-15.0.1-0.0.11.iso -p qcow2 -m ltm -b 1

This method works, but is no longer recommended with the latest version of F5 BIG-IP Image Generator Tool.

⁠Example: OVA or AWS

If building an ova or aws image, then you will also need the ovftool. Download and add the ovftool.bundle, which is renamed ovftool.bundle, file into the host’s input folder.

⁠NOTE

This example was tested and validated with the VMware-ovftool-4.3.0-7948156-lin.x86_64.bundle file.

1. To make the file executable, type:

   chmod +x ovftool.bundle
   

   Copy

2. Read and accept the EULA. To do this, run the following ovftool.bundle script or find it online⁠.

3. To extract the files, type:

   ./ovftool.bundle --extract ./ovftoolfiles/
   

   Copy

4. Put these files into the host's input folder, and then run:

   docker run -it --rm --device="/dev/kvm" -e "AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}" -e "AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}" -v "/<path>/docker:/mnt"  f5devcentral/f5-bigip-image-generator:latest /bin/bash -c "sudo cp -r /mnt/ovftoolfiles/vmware-ovftool /usr/lib/vmware-ovftool/; sudo chmod +x /usr/lib/vmware-ovftool/ovftool /usr/lib/vmware-ovftool/ovftool.bin; PATH='$PATH:/usr/lib/vmware-ovftool/:/f5'; export LANG=en_US.UTF-8; build-image -c config.yml -i BIGIP-15.0.1-0.0.11.iso -p aws -m ltm -b 1;"
   

   Copy

⁠Tip for AWS:

To prevent installing VMware ovftools repeatedly with every run, save changes to the container:

1. Exit the container: /mnt # exit.

2. From the host, obtain Container_ID from the container you just ran: sudo docker ps -a.

3. Commit⁠ the changes: sudo docker commit --change "ENV PATH=$PATH:/usr/lib/vmware-ovftool/:/f5" [CONTAINER_ID] f5-bigip-image-generator:with-ovftool.

   For example:

   sudo docker commit --change "ENV PATH=$PATH:/usr/lib/vmware-ovftool/:/f5" e7b5b895d793 f5-bigip-image-generator:with-ovftool
   

   Copy

4. The next time, you can run the container with ovftool pre-installed: sudo docker run -it --device="/dev/kvm" -v "/home/ubuntu:/mnt" f5-bigip-image-generator:with-ovftool.

⁠Build F5 Image Generator Docker container locally

To build the Docker image, change directories to the docker directory and type: ./build-docker-image. This will install all tools required for all supported platforms.

⁠Tip

To reduce the footprint required for development tools that you install based on the platform for which you are building, use the following supported PLATFORM variable options; for example:

• ./build-docker-image --qcow2
• ./build-docker-image --aws
• ./build-docker-image --vhd

and other supported platforms. Consult the User Guide⁠ for the complete PLATFORM parameter description.

To specify a tag for your image, use:

./build-docker-image --tag [insert tag name]

⁠Troubleshoot

Docker error message:

Temporary location for injected files: '/workdir/artifacts/BIGIP-15.1.0-0.0.31/aws/ltm_1slot/tmp.CgrVUToDbf/stage.initrd/etc/injected_files'
Collecting information about installed software on the build machine
copy 'authorized_keys' to a temporary location for '/home/admin/.ssh/authorized_keys'
Invalid URL 'authorized_keys': No schema supplied.

Remedy:

You see this message when your asset files reside in a local directory, or a relative directory from where you are running the docker command. Relocate your asset files to a docker file directory or mount a different volume and include those files in the volume BEFORE building your image.

⁠Copyright

Copyright (C) 2019-2022 F5 Networks, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0⁠

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.