fix(session-manager): relocate vcluster ingress Contour/Envoy images for air-gap

The Contour ingress controller deployed inside a vcluster session used
hardcoded upstream Contour/Envoy image refs that bypassed image
relocation and were absent from the published image list, so vcluster
ingress could not work in air-gapped or mirrored-registry environments.

Make them first-class imageVersions entries (vcluster-internal-contour,
vcluster-internal-envoy) and rewrite the loaded Contour manifests to the
inventory refs at session creation, so they relocate via per-name
overrides like the loft-sh images and are captured in the air-gap image
list. Drop the dead contour-bundle inventory entry and its unused
constant. Repackage the vendored session-manager subchart tarball.

Also extend hack/generate-image-list.sh to render the session-manager
chart so the full imageVersions inventory (workshop environments plus
the vcluster application images) is included in the published list, and
add publish-workshop-images to the image-list job's needs so the
JDK/conda image digests resolve.

Author: jorgemoralespou

.github/workflows/build-and-publish-images.yaml

@@ -873,10 +873,13 @@ jobs:
       contents: read
       packages: read
 
-    # Digest resolution needs every listed image already pushed.
+    # Digest resolution needs every listed image already pushed. The
+    # list now includes the JDK/conda workshop environments, so the
+    # workshop-images job has to finish first too.
     needs:
       - publish-generic-images
       - publish-workshop-base-image
+      - publish-workshop-images
 
     steps:
       - name: Check out the repository
@@ -889,10 +892,12 @@ jobs:
           echo "REPOSITORY_OWNER=${REPOSITORY_OWNER,,}" >>${GITHUB_ENV}
           echo "REPOSITORY_TAG=${GITHUB_REF##*/}" >>${GITHUB_ENV}
 
-      # Digest-pinned list of every image an air-gapped install needs
-      # (platform images + base-environment + upstream cluster-service
-      # images from the vendored charts). Attached to the GitHub
-      # release for name-preserving mirroring with skopeo/crane.
+      # Digest-pinned list of every image an air-gapped install can need
+      # (platform images + the full session-manager image inventory:
+      # base-environment, JDK/conda environments, and the vcluster
+      # application images + upstream cluster-service images from the
+      # vendored charts). Attached to the GitHub release for
+      # name-preserving mirroring with skopeo/crane.
       - name: Generate image list
         shell: bash
         run: |

hack/generate-image-list.sh

@@ -4,23 +4,30 @@
 #   hack/generate-image-list.sh <version> <registry-host> <registry-namespace> [--no-digests]
 #
 # Writes one fully qualified image reference per line to stdout
-# (`<repo>:<tag>@sha256:<digest>`), covering everything an air-gapped
-# install of the platform needs (see decisions.md "Image relocation is
-# a published digest-pinned list"):
+# (`<repo>:<tag>@sha256:<digest>`), covering everything an install of the
+# platform can need (see decisions.md "Image relocation is a published
+# digest-pinned list"):
 #
 #   - the Educates platform images at the released version (operator,
-#     runtime components, pause-container, docker-registry, ...) plus
-#     the workshop base-environment image, composed from the given
-#     registry host/namespace;
+#     runtime components, pause-container, docker-registry, ...);
+#   - the full session-manager image inventory (the `imageVersions`
+#     helper): the workshop base, the JDK and conda workshop
+#     environments, and the optional runtime images for the vcluster
+#     workshop application — vcluster itself plus its loft-sh Kubernetes
+#     distro images, docker-in-docker, and the debian base. Extracted by
+#     rendering the session-manager chart, so version bumps in the chart
+#     flow through without editing this script;
 #   - the upstream cluster-service images (cert-manager, Contour,
-#     external-dns, Kyverno), extracted by rendering the vendored
-#     chart tarballs with default values. Defaults are a superset of
-#     what the operator enables, so this over-collects slightly rather
-#     than ever missing an image.
+#     external-dns, Kyverno), extracted by rendering the vendored chart
+#     tarballs with default values. Defaults are a superset of what the
+#     operator enables, so this over-collects slightly rather than ever
+#     missing an image.
 #
-# Workshop environment images beyond base-environment (jdk*, conda)
-# are deliberately excluded — they add many GB per release. Air-gap
-# users append them to the list as needed.
+# The list is intentionally COMPLETE — it includes the JDK/conda
+# environments and the vcluster application images even though most
+# installs use only a subset. When mirroring, delete the entries you do
+# not use rather than guessing which ones might be missing. The
+# JDK/conda environment images are multi-GB each.
 #
 # Digest resolution uses skopeo (preinstalled on GitHub runners) and
 # requires the images to already be published — the release workflow
@@ -47,24 +54,21 @@ fi
 cd "$(dirname "$0")/.."
 
 VENDORED_CHARTS_DIR=installer/operator/vendored-charts
+SESSION_MANAGER_CHART=installer/charts/educates-training-platform/charts/session-manager
+REGISTRY_PREFIX="$REGISTRY_HOST/$REGISTRY_NAMESPACE"
 
-# Educates-built platform images: the publish-generic-images matrix
-# (with the operator's published name) plus the workshop
-# base-environment. educates-cli and the docker extension are client
-# tools, not platform images, and stay out.
+# Educates-built platform images that are NOT part of the session-manager
+# imageVersions inventory (the operator, the other components, and the
+# pause image). The inventory-resident Educates images — training-portal,
+# docker-registry, base-environment, jdk*, conda, ... — come from the
+# chart render below and are deduplicated against this list.
 PLATFORM_IMAGES="
-docker-registry
 pause-container
 session-manager
-training-portal
 secrets-manager
-tunnel-manager
-image-cache
-assets-server
 lookup-service
 node-ca-injector
 operator
-base-environment
 "
 
 # Upstream cluster-service charts the operator installs in Managed
@@ -94,10 +98,6 @@ emit() {
     fi
 }
 
-for name in $PLATFORM_IMAGES; do
-    emit "$REGISTRY_HOST/$REGISTRY_NAMESPACE/educates-$name:$VERSION"
-done
-
 # Image references appear in rendered manifests as `image:` fields and,
 # for cert-manager's acmesolver, as a `--*-image=` controller argument.
 extract_chart_images() {
@@ -107,18 +107,50 @@ extract_chart_images() {
         sed -E 's/^image: *"?//; s/"$//; s/^--[a-z0-9-]*image=//'
 }
 
-upstream_refs=""
+# Render the session-manager chart and pull every image reference out of
+# the imageVersions inventory (and the chart's own pod images). The
+# registry prefix is forced to the release's host/namespace so the
+# Educates-built entries resolve to the published location; clusterIngress
+# .domain is a required value that does not affect image refs.
+render_session_manager_images() {
+    helm template image-list-probe "$SESSION_MANAGER_CHART" \
+        --set clusterIngress.domain=image-list-probe.invalid \
+        --set development.imageRegistry.host="$REGISTRY_HOST" \
+        --set development.imageRegistry.namespace="$REGISTRY_NAMESPACE" \
+        2>/dev/null |
+        grep -ohE 'image: *"?[^"[:space:]]+"?' |
+        sed -E 's/^image: *"?//; s/"$//'
+}
+
+all_refs=""
+
+for name in $PLATFORM_IMAGES; do
+    all_refs+="$REGISTRY_PREFIX/educates-$name:$VERSION"$'\n'
+done
+
+# Educates-built inventory entries render at the chart's appVersion; pin
+# them to the release VERSION instead. External entries (vcluster,
+# loft-sh Kubernetes, the vcluster Contour/Envoy, docker-in-docker,
+# debian) pass through verbatim.
+while read -r ref; do
+    [ -n "$ref" ] || continue
+    case "$ref" in
+        "$REGISTRY_PREFIX"/*) all_refs+="${ref%:*}:$VERSION"$'\n' ;;
+        *) all_refs+="$ref"$'\n' ;;
+    esac
+done < <(render_session_manager_images)
+
 for glob in $UPSTREAM_CHART_GLOBS; do
     # shellcheck disable=SC2086 -- glob expansion is the point
     set -- $VENDORED_CHARTS_DIR/$glob
     [ -f "$1" ] || {
         echo "no vendored chart matching $glob in $VENDORED_CHARTS_DIR" >&2
         exit 1
     }
-    upstream_refs+="$(extract_chart_images "$1")"$'\n'
+    all_refs+="$(extract_chart_images "$1")"$'\n'
 done
 
 while read -r ref; do
     [ -n "$ref" ] || continue
     emit "$ref"
-done < <(echo "$upstream_refs" | sort -u)
+done < <(echo "$all_refs" | sort -u)

installer/charts/educates-training-platform/charts/session-manager/templates/_helpers.tpl

@@ -283,7 +283,6 @@ Returns the merged list as a YAML array string (consume via fromYamlArray).
     (dict "name" "tunnel-manager"          "image" (printf "%s/educates-tunnel-manager:%s" $repo $v))
     (dict "name" "image-cache"             "image" (printf "%s/educates-image-cache:%s" $repo $v))
     (dict "name" "assets-server"           "image" (printf "%s/educates-assets-server:%s" $repo $v))
-    (dict "name" "contour-bundle"          "image" (printf "%s/educates-contour-bundle:%s" $repo $v))
     (dict "name" "base-environment"        "image" (printf "%s/educates-base-environment:%s" $repo $v))
     (dict "name" "jdk8-environment"        "image" (printf "%s/educates-jdk8-environment:%s" $repo $v))
     (dict "name" "jdk11-environment"       "image" (printf "%s/educates-jdk11-environment:%s" $repo $v))
@@ -297,6 +296,8 @@ Returns the merged list as a YAML array string (consume via fromYamlArray).
     (dict "name" "loftsh-kubernetes-v1.33" "image" "ghcr.io/loft-sh/kubernetes:v1.33.4")
     (dict "name" "loftsh-kubernetes-v1.34" "image" "ghcr.io/loft-sh/kubernetes:v1.34.0")
     (dict "name" "loftsh-vcluster"         "image" "ghcr.io/loft-sh/vcluster-oss:0.30.2")
+    (dict "name" "vcluster-internal-contour" "image" "ghcr.io/projectcontour/contour:v1.30.2")
+    (dict "name" "vcluster-internal-envoy"   "image" "docker.io/envoyproxy/envoy:v1.31.5")
 -}}
 {{- $overrides := dict -}}
 {{- range default list .Values.imageVersions -}}

installer/operator/vendored-charts/session-manager-4.0.0-alpha.1.tgz

@@ -88,7 +88,14 @@ New Features
 * The Helm charts are published as OCI artifacts to
   ``ghcr.io/educates/charts`` with each release, and a digest-pinned list of
   all images used by a release is attached to the GitHub release to support
-  mirroring images into air-gapped registries.
+  mirroring images into air-gapped registries. The list is intentionally
+  complete: in addition to the platform and bundled cluster-service images it
+  includes every image in the session-manager image inventory — the
+  workshop base, the JDK and conda workshop environments, and the images the
+  vcluster workshop application uses (``vcluster`` itself, its loft-sh
+  Kubernetes distribution images, the Contour and Envoy images for vcluster
+  ingress, ``docker-in-docker`` and the debian base). When mirroring, delete
+  the entries you do not use rather than guessing which ones might be missing.
 
 * ``imageVersions`` entries in the CLI configuration now reach every
   platform image: entries named ``secrets-manager`` and ``lookup-service``
@@ -244,6 +251,15 @@ Deprecations
 Bugs Fixed
 ----------
 
+* The Contour ingress controller deployed inside a vcluster workshop session
+  (when the ``vcluster`` application enables ingress) used hardcoded upstream
+  Contour and Envoy image references that were not subject to image relocation
+  and were absent from the published image list, so vcluster ingress could not
+  work in air-gapped or registry-mirrored environments. These images are now
+  first-class entries in the ``imageVersions`` inventory, so they are
+  relocatable through the same per-name override mechanism as the other
+  platform images and are included in the air-gap image list.
+
 * In Inline mode the ``EducatesClusterConfig`` status could remain ``Ready``
   after a referenced ``ClusterIssuer`` was deleted, if the deletion event from
   the cert-manager watch was missed or observed against a momentarily stale

project-docs/release-notes/version-4.0.0.md

@@ -10,9 +10,33 @@
     LOFTSH_KUBERNETES_V1_32_IMAGE,
     LOFTSH_KUBERNETES_V1_33_IMAGE,
     LOFTSH_KUBERNETES_V1_34_IMAGE,
+    VCLUSTER_INTERNAL_CONTOUR_IMAGE,
+    VCLUSTER_INTERNAL_ENVOY_IMAGE,
     CLUSTER_STORAGE_GROUP,
 )
 
+# The Contour manifests in packages/contour/upstream pin specific upstream
+# image refs. Rewrite them to the refs from the imageVersions inventory so
+# the inventory entry — and any air-gap relocation override of it — is what
+# actually gets deployed into the vcluster, mirroring how the loft-sh
+# images are sourced.
+CONTOUR_IMAGE_REPOSITORIES = {
+    "ghcr.io/projectcontour/contour": VCLUSTER_INTERNAL_CONTOUR_IMAGE,
+    "docker.io/envoyproxy/envoy": VCLUSTER_INTERNAL_ENVOY_IMAGE,
+}
+
+
+def relocate_contour_images(objects):
+    for obj in objects:
+        pod_spec = xget(obj, "spec.template.spec", {})
+        for key in ("initContainers", "containers"):
+            for container in pod_spec.get(key, []):
+                image = container.get("image")
+                if image is None:
+                    continue
+                repository = image.rsplit(":", 1)[0]
+                container["image"] = CONTOUR_IMAGE_REPOSITORIES.get(repository, image)
+
 K8S_DEFAULT_VERSION = "1.33"
 
 K8S_VERSIONS = {
@@ -172,6 +196,8 @@ def relpath(*paths):
 
                 contour_objects.append(obj)
 
+        relocate_contour_images(contour_objects)
+
         vcluster_objects.extend(contour_objects)
 
         # Add the Contour service with a ClusterIP instead of a LoadBalancer

session-manager/handlers/application_vcluster.py

@@ -165,7 +165,12 @@ def image_reference(name):
 
 LOFTSH_VCLUSTER_IMAGE = image_reference("loftsh-vcluster")
 
-CONTOUR_BUNDLE_IMAGE = image_reference("contour-bundle")
+# Contour ingress controller deployed inside a vcluster session when the
+# vcluster application enables ingress. Sourced from the imageVersions
+# inventory so the refs are relocatable and captured in the air-gap image
+# list, the same way the loft-sh images are.
+VCLUSTER_INTERNAL_CONTOUR_IMAGE = image_reference("vcluster-internal-contour")
+VCLUSTER_INTERNAL_ENVOY_IMAGE = image_reference("vcluster-internal-envoy")
 
 
 def resolve_workshop_image(name):