Generate Rancher image list

The hangar generate-list command allows to generate a Rancher image list and K8s cluster version list according to the Rancher Version.

The generate K8s cluster version list function was supported from Hangar v1.7.1.

Quick Start

Generate a Rancher image list and K8s cluster (K3s, RKE, RKE2) version list by specifying the Rancher version:

hangar generate-list --rancher="v2.8.0"

The output file image list file is v2.8.0-images.txt, and cluster version list is v2.8.0-versions.txt.

warning

The image list file generated by hangar only includes images from KDM (Kontainer Driver Metadata) and Chart repositories used by Rancher, and the generated image list file is only used to sync container images when Rancher KDM and Chart repo upgrades.

You need to download the official rancher-images.txt image list file from Rancher GitHub Release page if you need the complete image list file instead of the upgrade images of KDM and Helm Chart images.

Usage

hangar generate-list --help

'generate-list' generates an image list and k8s version list from KDM data and Chart repos of Rancher.

Generate the image list by simply specifying the Rancher version:

    hangar generate-list --rancher="v2.8.0"

You can also download the KDM JSON file and clone chart repos manually:

    hangar generate-list \
        --rancher="v2.8.0" \
        --chart="./chart-repo-dir" \
        --system-chart="./system-chart-repo-dir" \
        --kdm="./kdm-data.json"

Usage:
  hangar generate-list [flags]

Flags:
  -y, --auto-yes                     answer yes automatically (used in shell script)
      --chart strings                cloned chart repo path (URL not supported)
      --dev                          switch to dev branch/URL of charts & KDM data
  -h, --help                         help for generate-list
      --k3s-images string            output KDM K3s linux image list if specified
      --kdm string                   KDM file path or URL
      --kdm-remove-deprecated        remove deprecated k3s/rke2 k8s versions from KDM (default true)
  -o, --output string                output linux image list file (default "[RANCHER_VERSION]-images.txt")
      --output-source string         output the image list with image source if specified
      --output-versions string       output Rancher supported k8s versions (default "[RANCHER_VERSION]-k8s-versions.txt")
      --output-windows string        output the windows image list if specified
      --rancher string               rancher version (semver with 'v' prefix) (use '-ent' suffix to distinguish with Rancher Prime Manager GC) (required)
      --registry string              customize the registry URL of the generated image list
      --rke-images string            output KDM RKE linux image list if specified
      --rke2-images string           output KDM RKE2 linux image list if specified
      --rke2-windows-images string   output KDM RKE2 Windows image list if specified
      --system-chart strings         cloned system chart repo path (URL not supported)
      --tls-verify                   require HTTPS and verify certificates

Global Flags:
      --debug             enable debug output
      --insecure-policy   run Hangar without policy check

Customize KDM data file and Chart repositories

If you only specify the --rancher option, hangar will fetch KDM data and clone chart repos used by Rancher to generate image list automatically.

In addition, you can also customize the KDM data.json file and Chart repository directories when generating the image-list by using --chart, --system-chart, --kdm options.

You can use multiple --chart and --system-chart options to specify multiple directories.

Example:

# Download KDM data.json and clone chart repository into local directory before generate list.

hangar generate-list \
    --rancher="v2.8.0" \
    --kdm="./data.json" \
    --chart="./charts-1" \
    --chart="./charts-2" \
    --system-chart="./system-charts-1" \
    --system-chart="./system-charts-2"

Options for KDM image list files

Available from v1.7.3.

You can use following options to output RKE/RKE2/K3s image list separately from KDM data.json.

• --rke-images
• --rke2-images
• --k3s-images
• --rke2-windows-images

Example:

hangar generate-list \
    --rancher="v2.8.0" \
    --rke-images="rke-images.txt" \
    --k3s-images="k3s-images.txt" \
    --rke2-images="rke2-images.txt" \
    --rke2-windows-images="rke2-windows-images.txt"

Hangar removes the deprecated k8s versions when generating RKE2/K3s images by default, you can use the --kdm-remove-deprecated=false option to generate image list contains the deprecated k8s versions.

Example:

hangar generate-list \
    --rancher="v2.8.0" \
    --kdm-remove-deprecated=false

# Now generated `v2.8.0-versions.txt` and `v2.8.0-images.txt`
# will contain deprecated older k8s patch releases:

cat v2.8.0-versions.txt
# K3s Versions:
# v1.25.13+k3s1
# v1.25.15+k3s2
# v1.25.16+k3s4
# ...