Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update image-builder docs #8552

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

update image-builder docs #8552

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
76c11a3
update image-builder docs
tatlat Jul 29, 2024
e31e1bf
remove python path
tatlat Jul 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 37 additions & 15 deletions docs/content/en/docs/osmgmt/artifacts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -358,6 +358,7 @@ These steps use `image-builder` to create an Ubuntu-based or RHEL-based image fo
sudo adduser image-builder
```
Follow the prompt to provide a password for the image-builder user.
If it does not prompt you for a password, then run `sudo passwd image-builder`
1. Add image-builder user to the sudo group and change user as image-builder providing in the password from previous step when prompted.
```bash
sudo usermod -aG sudo image-builder
Expand Down Expand Up @@ -402,7 +403,7 @@ These steps use `image-builder` to create an Ubuntu-based or RHEL-based image fo
* Starting with `image-builder` version `v0.3.0`, the minimum required Python version is Python 3.9. However, many Linux distros ship only up to Python 3.8, so you will need to install Python 3.9 from external sources. Refer to the `pyenv` [installation](https://github.com/pyenv/pyenv#installation) and [usage](https://github.com/pyenv/pyenv#usage) documentation to install Python 3.9 and make it the default Python version.
* Once you have Python 3.9, you can install Ansible using `pip`.
```bash
python3 -m pip install --user ansible
python3 -m pip install --user ansible==8.7.0 ansible-core==2.15.10
```
1. Get the latest version of `govc`:
```bash
Expand Down Expand Up @@ -496,6 +497,7 @@ These steps use `image-builder` to create an Ubuntu-based or RHEL-based image fo
* `--vsphere-config`: vSphere configuration file (`vsphere.json` in this example)

```bash
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os ubuntu --hypervisor vsphere --release-channel 1-29 --vsphere-config vsphere.json
```

Expand All @@ -510,6 +512,7 @@ These steps use `image-builder` to create an Ubuntu-based or RHEL-based image fo
* `--vsphere-config`: vSphere configuration file (`vsphere.json` in this example)

```bash
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os redhat --hypervisor vsphere --release-channel 1-29 --vsphere-config vsphere.json
```

Expand All @@ -521,6 +524,7 @@ These steps use `image-builder` to create an Ubuntu-based or RHEL-based image fo
sudo adduser image-builder
```
Follow the prompt to provide a password for the image-builder user.
If it does not prompt you for a password, then run `sudo passwd image-builder`
2. Add image-builder user to the sudo group and change user as image-builder providing in the password from previous step when prompted.
```bash
sudo usermod -aG sudo image-builder
Expand Down Expand Up @@ -574,7 +578,7 @@ These steps use `image-builder` to create an Ubuntu-based or RHEL-based image fo
* Starting with `image-builder` version `v0.3.0`, the minimum required Python version is Python 3.9. However, many Linux distros ship only up to Python 3.8, so you will need to install Python 3.9 from external sources. Refer to the `pyenv` [installation](https://github.com/pyenv/pyenv#installation) and [usage](https://github.com/pyenv/pyenv#usage) documentation to install Python 3.9 and make it the default Python version.
* Once you have Python 3.9, you can install Ansible using `pip`.
```bash
python3 -m pip install --user ansible
python3 -m pip install --user ansible==8.7.0 ansible-core==2.15.10
```
1. Create an Ubuntu or Red Hat image:

Expand All @@ -589,6 +593,7 @@ These steps use `image-builder` to create an Ubuntu-based or RHEL-based image fo
* `--baremetal-config`: baremetal config file if using proxy

```bash
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os ubuntu --hypervisor baremetal --release-channel 1-29
```

Expand Down Expand Up @@ -621,6 +626,7 @@ These steps use `image-builder` to create an Ubuntu-based or RHEL-based image fo
Image builder only supports building RHEL 9 raw images with EFI firmware. Refer to [UEFI Support]({{< relref "#uefi-support">}}) to enable image builds with EFI firmware.

```bash
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os redhat --hypervisor baremetal --release-channel 1-29 --baremetal-config baremetal.json
```
1. To consume the image, serve it from an accessible web server, then create the [bare metal cluster spec]({{< relref "../getting-started/baremetal/bare-spec/" >}})
Expand All @@ -641,6 +647,7 @@ These steps use `image-builder` to create a RHEL-based image for CloudStack. Bef
sudo adduser image-builder
```
Follow the prompt to provide a password for the image-builder user.
If it does not prompt you for a password, then run `sudo passwd image-builder`
1. Add image-builder user to the sudo group and change user as image-builder providing in the password from previous step when prompted.
```bash
sudo usermod -aG sudo image-builder
Expand Down Expand Up @@ -694,7 +701,7 @@ These steps use `image-builder` to create a RHEL-based image for CloudStack. Bef
* Starting with `image-builder` version `v0.3.0`, the minimum required Python version is Python 3.9. However, many Linux distros ship only up to Python 3.8, so you will need to install Python 3.9 from external sources. Refer to the `pyenv` [installation](https://github.com/pyenv/pyenv#installation) and [usage](https://github.com/pyenv/pyenv#usage) documentation to install Python 3.9 and make it the default Python version.
* Once you have Python 3.9, you can install Ansible using `pip`.
```bash
python3 -m pip install --user ansible
python3 -m pip install --user ansible==8.7.0 ansible-core==2.15.10
```
1. Create a CloudStack configuration file (for example, `cloudstack.json`) to provide the location of a Red Hat Enterprise Linux 8 ISO image and related checksum and Red Hat subscription information:
```json
Expand All @@ -716,6 +723,7 @@ These steps use `image-builder` to create a RHEL-based image for CloudStack. Bef
* `--cloudstack-config`: CloudStack configuration file (`cloudstack.json` in this example)

```bash
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os redhat --hypervisor cloudstack --release-channel 1-29 --cloudstack-config cloudstack.json
```
1. To consume the resulting RHEL-based image, add it as a template to your CloudStack setup as described in [Preparing CloudStack]({{< relref "../getting-started/cloudstack/cloudstack-preparation" >}}).
Expand All @@ -729,6 +737,7 @@ These steps use `image-builder` to create an Ubuntu-based Amazon Machine Image (
sudo adduser image-builder
```
Follow the prompt to provide a password for the image-builder user.
If it does not prompt you for a password, then run `sudo passwd image-builder`
1. Add the `image-builder` user to the `sudo` group and switch user to `image-builder`, providing in the password from previous step when prompted.
```bash
sudo usermod -aG sudo image-builder
Expand Down Expand Up @@ -773,7 +782,7 @@ These steps use `image-builder` to create an Ubuntu-based Amazon Machine Image (
* Starting with `image-builder` version `v0.3.0`, the minimum required Python version is Python 3.9. However, many Linux distros ship only up to Python 3.8, so you will need to install Python 3.9 from external sources. Refer to the `pyenv` [installation](https://github.com/pyenv/pyenv#installation) and [usage](https://github.com/pyenv/pyenv#usage) documentation to install Python 3.9 and make it the default Python version.
* Once you have Python 3.9, you can install Ansible using `pip`.
```bash
python3 -m pip install --user ansible
python3 -m pip install --user ansible==8.7.0 ansible-core==2.15.10
```
1. Create an AMI configuration file (for example, `ami.json`) that contains various AMI parameters. For example:

Expand Down Expand Up @@ -839,7 +848,8 @@ These steps use `image-builder` to create an Ubuntu-based Amazon Machine Image (
* `--ami-config`: AMI configuration file (`ami.json` in this example)

```bash
image-builder build --os ubuntu --hypervisor ami --release-channel 1-29 --ami-config ami.json
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os ubuntu --hypervisor ami --release-channel 1-29 --ami-config ami.json
```
1. After the build, the Ubuntu AMI will be available in your AWS account in the AWS region specified in your AMI configuration file. If you wish to export it as a raw image, you can achieve this using the AWS CLI.
```
Expand All @@ -863,6 +873,7 @@ These steps use `image-builder` to create a Ubuntu-based image for Nutanix AHV a
sudo adduser image-builder
```
Follow the prompt to provide a password for the image-builder user.
If it does not prompt you for a password, then run `sudo passwd image-builder`
1. Add image-builder user to the sudo group and change user as image-builder providing in the password from previous step when prompted.
```bash
sudo usermod -aG sudo image-builder
Expand Down Expand Up @@ -907,7 +918,7 @@ These steps use `image-builder` to create a Ubuntu-based image for Nutanix AHV a
* Starting with `image-builder` version `v0.3.0`, the minimum required Python version is Python 3.9. However, many Linux distros ship only up to Python 3.8, so you will need to install Python 3.9 from external sources. Refer to the `pyenv` [installation](https://github.com/pyenv/pyenv#installation) and [usage](https://github.com/pyenv/pyenv#usage) documentation to install Python 3.9 and make it the default Python version.
* Once you have Python 3.9, you can install Ansible using `pip`.
```bash
python3 -m pip install --user ansible
python3 -m pip install --user ansible==8.7.0 ansible-core==2.15.10
```
1. Create a `nutanix.json` config file. More details on values can be found in the [image-builder documentation](https://image-builder.sigs.k8s.io/capi/providers/nutanix.html). See example below:
```json
Expand Down Expand Up @@ -946,6 +957,7 @@ These steps use `image-builder` to create a Ubuntu-based image for Nutanix AHV a
* `--nutanix-config`: Nutanix configuration file (`nutanix.json` in this example)

```bash
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os ubuntu --hypervisor nutanix --release-channel 1-29 --nutanix-config nutanix.json
```

Expand All @@ -960,6 +972,7 @@ These steps use `image-builder` to create a Ubuntu-based image for Nutanix AHV a
* `--nutanix-config`: Nutanix configuration file (`nutanix.json` in this example)

```bash
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os redhat --hypervisor nutanix --release-channel 1-29 --nutanix-config nutanix.json
```

Expand Down Expand Up @@ -1014,12 +1027,14 @@ This was improved in `image-builder` released with EKS-A `v0.16.3` to `v0.16.5`.
For example, if you want to build an image for EKS-A version `v0.16.5`, you can run the following command.
```bash
export EKSA_RELEASE_VERSION=v0.16.5
image-builder build --os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json
```

With `image-builder` versions `v0.2.1` and above (released with EKS-A version `v0.17.0`), the `image-builder` CLI has the EKS-A version baked into it, so it will build images pertaining to that release of EKS Anywhere by default. You can override the default version using the `eksa-release` option.
```bash
image-builder build --os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json --eksa-release v0.16.5
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json --eksa-release v0.16.5
```

#### Building images corresponding to dev versions of EKS-A
Expand All @@ -1034,12 +1049,14 @@ This can be achieved using an `image-builder` CLI that has the dev version of EK
**`image-builder` obtained from a production EKS-A release:**
```bash
export EKSA_USE_DEV_RELEASE=true
image-builder build --os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json --eksa-release v0.0.0-dev
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json --eksa-release v0.0.0-dev
```
**`image-builder` obtained from a dev EKS-A release:**
```bash
export EKSA_USE_DEV_RELEASE=true
image-builder build --os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json
```

In both these above approaches, the artifacts embedded into the images will be obtained from the dev release bundle manifest instead of production. This manifest contains the latest artifacts built from the `main` branch, and is generally more up-to-date than production release artifact versions.
Expand All @@ -1050,7 +1067,8 @@ In both these above approaches, the artifacts embedded into the images will be o

For example, to build a Kubernetes v1.27 Ubuntu 22.04 OVA with UEFI enabled, you can run the following command.
```bash
image-builder build --os ubuntu --hypervisor vsphere --os-version 22.04 --release-channel 1.27 --vsphere-config config.json --firmware efi
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os ubuntu --hypervisor vsphere --os-version 22.04 --release-channel 1.27 --vsphere-config config.json --firmware efi
```

The table below shows the possible firmware options for the hypervisor and OS combinations that `image-builder` supports.
Expand Down Expand Up @@ -1082,7 +1100,8 @@ To do this, create a configuration file (say, `files.json`) containing the list

You can now run the `image-builder` CLI with the `files-config` option, with this configuration file as input.
```bash
image-builder build --os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json --files-config files.json
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json --files-config files.json
```

### Using Proxy Server
Expand All @@ -1106,7 +1125,8 @@ In a proxy-enabled environment, `image-builder` uses `wget` to download artifact

Run `image-builder` CLI with the hypervisor configuration file
```bash
image-builder build --os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json
```

### Red Hat Satellite Support
Expand Down Expand Up @@ -1138,7 +1158,8 @@ In order to use Red Hat Satellite in the image build process follow the steps be
`rhsm_server_release_version` should always point to the latest 8.x or 9.x minor Red Hat release synced and available on Red Hat Satellite
2. Run `image-builder` CLI with the hypervisor configuration file
```bash
image-builder build --os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build --os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json
```

### Air Gapped Image Building
Expand Down Expand Up @@ -1287,7 +1308,8 @@ In order to use Red Hat Satellite in the image build process follow the steps be
```
12. Run `image-builder` CLI with the hypervisor configuration file and the downloaded manifest tarball
```bash
image-builder build -os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json --airgapped --manifest-tarball <path to eks-a-manifests.tar>
export PATH="$PATH:/home/image-builder/.local/bin"
image-builder build -os <OS> --hypervisor <hypervisor> --release-channel <release channel> --<hypervisor>-config config.json --airgapped --manifest-tarball <path to eks-a-manifests.tar>
```


Expand Down