Adding overlays capability to the installer

jorgemoralespou · jorgemoralespou · commit b23d5a17eee6 · 2026-02-13T19:30:32.000+01:00
diff --git a/Makefile b/Makefile
@@ -48,6 +48,18 @@
 #   Default: latest
 #   Examples: v1.0.0, dev, latest
 #
+# IMGPKG_IMAGE_REPOSITORY
+#   Description: Registry/repository used for image refs inside the installer bundle (kbld-images).
+#   Default: same as IMAGE_REPOSITORY
+#   Override when developing installer carvel-packages to use released images in the bundle
+#   instead of local images (e.g. IMGPKG_IMAGE_REPOSITORY=ghcr.io/educates).
+#
+# IMGPKG_PACKAGE_VERSION
+#   Description: Version tag used for image refs inside the installer bundle (kbld-images).
+#   Default: same as PACKAGE_VERSION
+#   Override when developing installer to pin bundle to a released version's images
+#   (e.g. IMGPKG_PACKAGE_VERSION=3.5.1).
+#
 # =============================================================================
 # BUILD TARGETS
 # =============================================================================
@@ -130,6 +142,10 @@ IMAGE_REPOSITORY = localhost:5001
 PACKAGE_VERSION = latest
 RELEASE_VERSION = 0.0.1
 
+# Installer bundle image refs: default to same as build repo/version; override to use released images when developing installer
+IMGPKG_IMAGE_REPOSITORY ?= $(IMAGE_REPOSITORY)
+IMGPKG_PACKAGE_VERSION ?= $(PACKAGE_VERSION)
+
 UNAME_SYSTEM := $(shell uname -s | tr '[:upper:]' '[:lower:]')
 UNAME_MACHINE := $(shell uname -m)
 
@@ -291,7 +307,7 @@ else
 endif
 
 push-installer-bundle:
-	ytt -f carvel-packages/installer/config/images.yaml -f carvel-packages/installer/config/schema.yaml -v imageRegistry.host=$(IMAGE_REPOSITORY) -v version=$(PACKAGE_VERSION) > carvel-packages/installer/bundle/kbld/kbld-images.yaml
+	ytt -f carvel-packages/installer/config/images.yaml -f carvel-packages/installer/config/schema.yaml -v imageRegistry.host=$(IMGPKG_IMAGE_REPOSITORY) -v version=$(IMGPKG_PACKAGE_VERSION) > carvel-packages/installer/bundle/kbld/kbld-images.yaml
    # For local development, we just need to lock educates images. Everything else can be referenced by tag from real origin.
 	cat carvel-packages/installer/bundle/kbld/kbld-images.yaml | kbld -f - --imgpkg-lock-output carvel-packages/installer/bundle/.imgpkg/images.yml
 	imgpkg push -b $(IMAGE_REPOSITORY)/educates-installer:$(RELEASE_VERSION) -f carvel-packages/installer/bundle
diff --git a/carvel-packages/installer/bundle/config/ytt/_ytt_lib/infrastructure/custom/00-remove-toplevel-values.yaml b/carvel-packages/installer/bundle/config/ytt/_ytt_lib/infrastructure/custom/00-remove-toplevel-values.yaml
@@ -48,3 +48,5 @@ websiteStyling:
 imagePuller:
 #@overlay/remove
 lookupService:
+#@overlay/remove
+installerImages:
diff --git a/carvel-packages/installer/bundle/config/ytt/_ytt_lib/infrastructure/eks/00-remove-toplevel-values.yaml b/carvel-packages/installer/bundle/config/ytt/_ytt_lib/infrastructure/eks/00-remove-toplevel-values.yaml
@@ -48,3 +48,5 @@ websiteStyling:
 imagePuller:
 #@overlay/remove
 lookupService:
+#@overlay/remove
+installerImages:
diff --git a/carvel-packages/installer/bundle/config/ytt/_ytt_lib/infrastructure/generic/00-remove-toplevel-values.yaml b/carvel-packages/installer/bundle/config/ytt/_ytt_lib/infrastructure/generic/00-remove-toplevel-values.yaml
@@ -48,3 +48,5 @@ websiteStyling:
 imagePuller:
 #@overlay/remove
 lookupService:
+#@overlay/remove
+installerImages:
diff --git a/carvel-packages/installer/bundle/config/ytt/_ytt_lib/infrastructure/kind/00-remove-toplevel-values.yaml b/carvel-packages/installer/bundle/config/ytt/_ytt_lib/infrastructure/kind/00-remove-toplevel-values.yaml
@@ -48,3 +48,5 @@ websiteStyling:
 imagePuller:
 #@overlay/remove
 lookupService:
+#@overlay/remove
+installerImages:
diff --git a/carvel-packages/installer/bundle/config/ytt/_ytt_lib/infrastructure/minikube/00-remove-toplevel-values.yaml b/carvel-packages/installer/bundle/config/ytt/_ytt_lib/infrastructure/minikube/00-remove-toplevel-values.yaml
@@ -48,3 +48,5 @@ websiteStyling:
 imagePuller:
 #@overlay/remove
 lookupService:
+#@overlay/remove
+installerImages:
diff --git a/carvel-packages/installer/bundle/config/ytt/_ytt_lib/infrastructure/openshift/00-remove-toplevel-values.yaml b/carvel-packages/installer/bundle/config/ytt/_ytt_lib/infrastructure/openshift/00-remove-toplevel-values.yaml
@@ -48,3 +48,5 @@ websiteStyling:
 imagePuller:
 #@overlay/remove
 lookupService:
+#@overlay/remove
+installerImages:
diff --git a/carvel-packages/installer/bundle/config/ytt/_ytt_lib/infrastructure/vcluster/00-remove-toplevel-values.yaml b/carvel-packages/installer/bundle/config/ytt/_ytt_lib/infrastructure/vcluster/00-remove-toplevel-values.yaml
@@ -48,3 +48,5 @@ websiteStyling:
 imagePuller:
 #@overlay/remove
 lookupService:
+#@overlay/remove
+installerImages:
diff --git a/carvel-packages/installer/bundle/config/ytt/values-schema.yaml b/carvel-packages/installer/bundle/config/ytt/values-schema.yaml
@@ -75,7 +75,7 @@ clusterInfrastructure:
     #@schema/title "AWS IAM IRSA Roles"
     #@schema/desc "AWS IAM IRSA Roles for external-dns and cert-manager"
     irsaRoles:
-      #@schema/example "arn:aws:iam::MY_IAM:role/external-dns" 
+      #@schema/example "arn:aws:iam::MY_IAM:role/external-dns"
       #@schema/validation ("irsaRole for external-dns is required for aws based providers",lambda v: len(v) >= 1)
       external-dns: ""
       #@schema/example "arn:aws:iam::MY_IAM:role/cert-manager"
@@ -122,6 +122,9 @@ localKindCluster: {}
 #@schema/nullable
 #@schema/type any=True
 localDNSResolver: {}
+#@schema/nullable
+#@schema/type any=True
+installerImages: {}
 #!--------- educates training platform schema
 #! NOTE: https://github.com/jorgemoralespou/educates-training-platform/blob/develop/carvel-packages/training-platform/bundle/config/00-schema.yaml#L21C1-L33
 #! This is only so that the images generates are loaded from this registry. There's a pre-proccesing step that will generate a images file
diff --git a/client-programs/pkg/cmd/cluster_portal_open_cmd.go b/client-programs/pkg/cmd/cluster_portal_open_cmd.go
@@ -67,6 +67,7 @@ func (o *ClusterPortalOpenOptions) Run() error {
 		return err
 	}
 
+	// TODO: Most of this logic is similar to workshops.OpenBrowser, so we should refactor it to a common function.
 	fmt.Printf("Training portal %q.\n", o.Portal)
 
 	fmt.Print("Checking training portal is ready.\n")
diff --git a/client-programs/pkg/config/installationconfig.go b/client-programs/pkg/config/installationconfig.go
@@ -324,6 +324,11 @@ type TrainingPlatformConfig struct {
 	LookupService     LookupServiceConfig     `yaml:"lookupService,omitempty"`
 }
 
+type InstallerImagesConfig struct {
+	Bundle string `yaml:"bundle,omitempty"`
+	Overlays []string `yaml:"overlays,omitempty"`
+}
+
 type InstallationConfig struct {
 	Debug                 *bool                       `yaml:"debug,omitempty"`
 	LocalKindCluster      LocalKindClusterConfig      `yaml:"localKindCluster,omitempty"`
@@ -348,6 +353,7 @@ type InstallationConfig struct {
 	WebsiteStyling        WebsiteStylingConfig        `yaml:"websiteStyling,omitempty"`
 	ImagePuller           ImagePullerConfig           `yaml:"imagePuller,omitempty"`
 	LookupService         LookupServiceConfig         `yaml:"lookupService,omitempty"`
+	InstallerImages       InstallerImagesConfig       `yaml:"installerImages,omitempty"`
 }
 
 type EducatesDomainStruct struct {
diff --git a/client-programs/pkg/installer/installer.go b/client-programs/pkg/installer/installer.go
@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strconv"
 	"time"
 
 	"github.com/educates/educates-training-platform/client-programs/pkg/cluster"
@@ -68,7 +69,7 @@ func (inst *Installer) DryRun(version string, packageRepository string, fullConf
 	}
 
 	// Fetch
-	prevDir, err := inst.fetch(tempDir, version, packageRepository, verbose)
+	prevDir, err := inst.fetch(tempDir, version, packageRepository, fullConfig, verbose)
 	if err != nil {
 		return err
 	}
@@ -120,7 +121,7 @@ func (inst *Installer) Run(version string, packageRepository string, fullConfig
 	}
 
 	// Fetch
-	prevDir, err := inst.fetch(tempDir, version, packageRepository, verbose)
+	prevDir, err := inst.fetch(tempDir, version, packageRepository, fullConfig, verbose)
 	if err != nil {
 		return err
 	}
@@ -210,25 +211,59 @@ func (inst *Installer) GetConfigFromCluster(kubeconfig string, kubeContext strin
 	return string(valuesData), nil
 }
 
-func (inst *Installer) fetch(tempDir string, version string, packageRepository string, verbose bool) (string, error) {
+func (inst *Installer) fetch(tempDir string, version string, packageRepository string, fullConfig *config.InstallationConfig, verbose bool) (string, error) {
 	if verbose {
 		fmt.Println("Running fetch ...")
 	}
 
-	pullOpts := imgpkgv1.PullOpts{
+	pullOptsAsImage := imgpkgv1.PullOpts{
+		Logger:   logger.NewNullLogger(),
+		AsImage:  true,
+		IsBundle: false,
+	}
+	pullOptsAsBundle := imgpkgv1.PullOpts{
 		Logger:   logger.NewNullLogger(),
 		AsImage:  false,
 		IsBundle: true,
 	}
 	// TODO: Remove some logging from here
 	fetchOutputDir := filepath.Join(tempDir, "fetch")
-	installerImageRef := inst.getBundleImageRef(version, packageRepository)
+	installerImageRef := fullConfig.InstallerImages.Bundle
+	if installerImageRef == "" {
+		installerImageRef = inst.getBundleImageRef(version, packageRepository)
+	}
 	fmt.Println("Using installer image: ", installerImageRef)
-	_, err := imgpkgv1.Pull(installerImageRef, fetchOutputDir, pullOpts, registry.Opts{})
+	_, err := imgpkgv1.Pull(installerImageRef, fetchOutputDir, pullOptsAsBundle, registry.Opts{})
 	if err != nil {
 		// TODO: There might be more potential issues here
 		return "", errors.Wrapf(err, "Installer image not found")
 	}
+
+	// Fetch installer overlay bundles when configured
+	if fullConfig != nil && len(fullConfig.InstallerImages.Overlays) > 0 {
+		overlaysDir := filepath.Join(tempDir, "overlays")
+		for i, ref := range fullConfig.InstallerImages.Overlays {
+			overlayDir := filepath.Join(overlaysDir, strconv.Itoa(i))
+			if err := os.MkdirAll(overlayDir, 0755); err != nil {
+				return "", errors.Wrapf(err, "create overlay directory for %s", ref)
+			}
+			if verbose {
+				fmt.Println("Using installer overlay image: ", ref)
+			}
+			status, err := imgpkgv1.Pull(ref, overlayDir, pullOptsAsBundle, registry.Opts{})
+			if err != nil {
+				if !status.IsBundle {
+					_, err := imgpkgv1.Pull(ref, overlayDir, pullOptsAsImage, registry.Opts{})
+					if err != nil {
+						return "", errors.Wrapf(err, "installer overlay image %d (%s) not found", i, ref)
+					}
+				} else {
+					return "", errors.Wrapf(err, "installer overlay image %d (%s) not found", i, ref)
+				}
+			}
+		}
+	}
+
 	return fetchOutputDir, nil
 }
 
@@ -241,6 +276,15 @@ func (inst *Installer) template(tempDir string, inputDir string, fullConfig *con
 	if !showPackagesValues && !skipImageResolution {
 		paths = append(paths, filepath.Join(inputDir, "kbld/kbld-bundle.yaml"))
 	}
+	// Add installer overlay bundle roots as ytt paths (any structure in each bundle works)
+	if fullConfig != nil && len(fullConfig.InstallerImages.Overlays) > 0 {
+		for i := 0; i < len(fullConfig.InstallerImages.Overlays); i++ {
+			overlayPath := filepath.Join(tempDir, "overlays", strconv.Itoa(i))
+			if _, err := os.Stat(overlayPath); err == nil {
+				paths = append(paths, overlayPath)
+			}
+		}
+	}
 	filesToProcess, err := files.NewSortedFilesFromPaths(paths, files.SymlinkAllowOpts{})
 	if err != nil {
 		return "", err
diff --git a/go.work.sum b/go.work.sum
@@ -351,6 +351,7 @@ github.com/containernetworking/plugins v1.9.0/go.mod h1:JG3BxoJifxxHBhG3hFyxyhid
 github.com/containers/ocicrypt v1.2.1/go.mod h1:aD0AAqfMp0MtwqWgHM1bUwe1anx0VazI108CRrSKINQ=
 github.com/coredns/caddy v1.1.1/go.mod h1:A6ntJQlAWuQfFlsd9hvigKbo2WS0VUs2l1e2F+BawD4=
 github.com/coredns/corefile-migration v1.0.21/go.mod h1:XnhgULOEouimnzgn0t4WPuFDN2/PJQcTxdWKC5eXNGE=
+github.com/coredns/corefile-migration v1.0.23/go.mod h1:8HyMhuyzx9RLZp8cRc9Uf3ECpEAafHOFxQWUPqktMQI=
 github.com/coredns/corefile-migration v1.0.24/go.mod h1:56DPqONc3njpVPsdilEnfijCwNGC3/kTJLl7i7SPavY=
 github.com/coredns/corefile-migration v1.0.26/go.mod h1:56DPqONc3njpVPsdilEnfijCwNGC3/kTJLl7i7SPavY=
 github.com/coreos/go-oidc v2.2.1+incompatible/go.mod h1:CgnwVTmzoESiwO9qyAFEMiHoZ1nMCKZlZ9V6mm3/LKc=
@@ -708,6 +709,7 @@ github.com/onsi/gomega v1.34.2/go.mod h1:v1xfxRgk0KIsG+QOdm7p8UosrOzPYRo60fd3B/1
 github.com/opencontainers/cgroups v0.0.1/go.mod h1:s8lktyhlGUqM7OSRL5P7eAW6Wb+kWPNvt4qvVfzA5vs=
 github.com/opencontainers/image-spec v1.1.0-rc3/go.mod h1:X4pATf0uXsnn3g5aiGIsVnJBR4mxhKzfwmvK/B2NTm8=
 github.com/opencontainers/runc v1.1.12/go.mod h1:S+lQwSfncpBha7XTy/5lBwWgm5+y5Ma/O44Ekby9FK8=
+github.com/opencontainers/runc v1.1.13/go.mod h1:R016aXacfp/gwQBYw2FDGa9m+n6atbLWrYY8hNMT/sA=
 github.com/opencontainers/runc v1.2.1/go.mod h1:/PXzF0h531HTMsYQnmxXkBD7YaGShm/2zcRB79dksUc=
 github.com/opencontainers/runtime-spec v1.0.3-0.20220909204839-494a5a6aca78/go.mod h1:jwyrGlmzljRJv/Fgzds9SsS/C5hL+LL3ko9hs6T5lQ0=
 github.com/opencontainers/runtime-spec v1.2.0/go.mod h1:jwyrGlmzljRJv/Fgzds9SsS/C5hL+LL3ko9hs6T5lQ0=
@@ -843,6 +845,7 @@ go.etcd.io/etcd/client/pkg/v3 v3.6.4 h1:9HBYrjppeOfFjBjaMTRxT3R7xT0GLK8EJMVC4xg6
 go.etcd.io/etcd/client/pkg/v3 v3.6.4/go.mod h1:sbdzr2cl3HzVmxNw//PH7aLGVtY4QySjQFuaCgcRFAI=
 go.etcd.io/etcd/client/v2 v2.305.0/go.mod h1:h9puh54ZTgAKtEbut2oe9P4L/oqKCVB6xsXlzd7alYQ=
 go.etcd.io/etcd/client/v2 v2.305.10/go.mod h1:m3CKZi69HzilhVqtPDcjhSGp+kA1OmbNn0qamH80xjA=
+go.etcd.io/etcd/client/v2 v2.305.13/go.mod h1:iQnL7fepbiomdXMb3om1rHq96htNNGv2sJkEcZGDRRg=
 go.etcd.io/etcd/client/v2 v2.305.16/go.mod h1:h9YxWCzcdvZENbfzBTFCnoNumr2ax3F19sKMqHFmXHE=
 go.etcd.io/etcd/client/v3 v3.5.8/go.mod h1:idZYIPVkttBJBiRigkB5EM0MmEyx8jcl18zCV3F5noc=
 go.etcd.io/etcd/client/v3 v3.5.9/go.mod h1:i/Eo5LrZ5IKqpbtpPDuaUnDOUv471oDg8cjQaUr2MbA=
@@ -853,6 +856,7 @@ go.etcd.io/etcd/pkg/v3 v3.5.10/go.mod h1:TKTuCKKcF1zxmfKWDkfz5qqYaE3JncKKZPFf8c1
 go.etcd.io/etcd/pkg/v3 v3.5.16/go.mod h1:+lutCZHG5MBBFI/U4eYT5yL7sJfnexsoM20Y0t2uNuY=
 go.etcd.io/etcd/pkg/v3 v3.6.4/go.mod h1:kKcYWP8gHuBRcteyv6MXWSN0+bVMnfgqiHueIZnKMtE=
 go.etcd.io/etcd/raft/v3 v3.5.10/go.mod h1:odD6kr8XQXTy9oQnyMPBOr0TVe+gT0neQhElQ6jbGRc=
+go.etcd.io/etcd/raft/v3 v3.5.13/go.mod h1:uUFibGLn2Ksm2URMxN1fICGhk8Wu96EfDQyuLhAcAmw=
 go.etcd.io/etcd/raft/v3 v3.5.16/go.mod h1:P4UP14AxofMJ/54boWilabqqWoW9eLodl6I5GdGzazI=
 go.etcd.io/etcd/server/v3 v3.5.10/go.mod h1:gBplPHfs6YI0L+RpGkTQO7buDbHv5HJGG/Bst0/zIPo=
 go.etcd.io/etcd/server/v3 v3.5.16/go.mod h1:ynhyZZpdDp1Gq49jkUg5mfkDWZwXnn3eIqCqtJnrD/s=
@@ -1264,6 +1268,7 @@ google.golang.org/genproto v0.0.0-20230711160842-782d3b101e98 h1:Z0hjGZePRE0ZBWo
 google.golang.org/genproto v0.0.0-20230711160842-782d3b101e98/go.mod h1:S7mY02OqCJTD0E1OiQy1F72PWFB4bZJ87cAtLPYgDR0=
 google.golang.org/genproto v0.0.0-20230803162519-f966b187b2e5/go.mod h1:oH/ZOT02u4kWEp7oYBGYFFkCdKS/uYR9Z7+0/xuuFp8=
 google.golang.org/genproto v0.0.0-20230822172742-b8732ec3820d h1:VBu5YqKPv6XiJ199exd8Br+Aetz+o08F+PLMnwJQHAY=
+google.golang.org/genproto v0.0.0-20230822172742-b8732ec3820d/go.mod h1:yZTlhN0tQnXo3h00fuXNCxJdLdIdnVFVBaRJ5LWBbw4=
 google.golang.org/genproto v0.0.0-20231016165738-49dd2c1f3d0b/go.mod h1:CgAqfJo+Xmu0GwA0411Ht3OU3OntXwsGmrmjI8ioGXI=
 google.golang.org/genproto v0.0.0-20240123012728-ef4313101c80/go.mod h1:cc8bqMqtv9gMOr0zHg2Vzff5ULhhL2IXP4sbcn32Dro=
 google.golang.org/genproto v0.0.0-20240722135656-d784300faade/go.mod h1:FfBgJBJg9GcpPvKIuHSZ/aE1g2ecGL74upMzGZjiGEY=
diff --git a/project-docs/installation-guides/configuration-settings.md b/project-docs/installation-guides/configuration-settings.md
@@ -4,6 +4,39 @@ Configuration Settings
 
 At the time of installing Educates, various configuration settings can be supplied. Some of these are essential to ensuring Educates will work correctly while others are optional. In a few cases the settings can be overridden on a case by case basis when deploying a training portal, but key settings must be provided when installing Educates.
 
+(installer-images)=
+Installer images
+---------------
+
+When using the Educates CLI to install (or dry-run), you can customize the installer bundle and add overlay bundles using the ``installerImages`` configuration. This setting provides two options:
+
+* **bundle**: A single OCI image reference to an imgpkg bundle that replaces the default installer bundle. This allows you to use a completely customized installation bundle instead of the standard Educates installer bundle.
+
+* **overlays**: A list of OCI image references to imgpkg bundles that will be used as additional ytt overlay inputs. Each overlay bundle is pulled and its root directory is passed to the template phase, so you can add or patch the default installer manifests without forking the installer. No fixed layout is required inside the bundle—any structure (e.g. ytt files, an ``overlays/`` folder, or flat YAML) is used as-is from the bundle root. Overlays are applied in order after the base installer templates, so later entries can override or extend earlier ones.
+
+Both options are optional and can be used independently or together. This setting is only used by the CLI installer; it does not apply when installing via Carvel or kapp-controller.
+
+```yaml
+installerImages:
+  bundle: "registry.example.com/my-org/custom-installer-bundle:v1"
+  overlays:
+    - "registry.example.com/my-org/educates-overlays:v1"
+    - "registry.example.com/my-org/extra-patches:latest"
+```
+
+You can also use just one of the options:
+
+```yaml
+# Use only a custom bundle
+installerImages:
+  bundle: "registry.example.com/my-org/custom-installer-bundle:v1"
+
+# Use only overlays (keep default bundle)
+installerImages:
+  overlays:
+    - "registry.example.com/my-org/educates-overlays:v1"
+```
+
 (defining-configuration-for-ingress)=
 Defining configuration for ingress
 ----------------------------------
@@ -504,7 +537,7 @@ The ``user`` field will be the same portal user identity that is returned by the
 
 Note that the event stream only produces events for things as they happen. If you need a snapshot of all current workshop sessions, you should use the REST API to request the catalog of available workshop environments, enabling the inclusion of current workshop sessions.
 
-Instead of enabling tracking of workshop globally, it can also be configured when creating a training portal. 
+Instead of enabling tracking of workshop globally, it can also be configured when creating a training portal.
 
 (tracking-using-google-analytics)=
 Tracking using Google Analytics
@@ -545,7 +578,7 @@ In addition to custom dimensions against page accesses, events are also generate
 
 Note that Google Analytics is not a reliable way to collect data. This is because individuals or corporate firewalls can block the reporting of Google Analytics data. For more precise statistics, you should use the webhook URL for collecting analytics with a custom data collection platform.
 
-Instead of enabling Google analytics globally, it can also be configured when creating a training portal. 
+Instead of enabling Google analytics globally, it can also be configured when creating a training portal.
 
 (tracking-using-microsoft-clarity)=
 Tracking using Microsoft Clarity
@@ -561,7 +594,7 @@ workshopAnalytics:
 
 As Microsoft Clarity doesn't support custom user events, events generated by Educates are not able to be sent to it.
 
-Instead of enabling Microsoft Clarity analytics globally, it can also be configured when creating a training portal. 
+Instead of enabling Microsoft Clarity analytics globally, it can also be configured when creating a training portal.
 
 (tracking-using-amplitude)=
 Tracking using Amplitude
@@ -575,7 +608,7 @@ workshopAnalytics:
     trackingId: "XXXXXXXXXX"
 ```
 
-Instead of enabling Amplitude analytics globally, it can also be configured when creating a training portal. 
+Instead of enabling Amplitude analytics globally, it can also be configured when creating a training portal.
 
 (overriding-styling-of-the-workshop)=
 Overriding styling of the workshop
diff --git a/project-docs/installation-guides/installation-instructions.md b/project-docs/installation-guides/installation-instructions.md
@@ -88,6 +88,17 @@ See the general documentation on [Configuration Settings](configuration-settings
 
 For more details on configuration requirements for specific infrastructure providers see the documentation on [Infrastructure Providers](infrastructure-providers).
 
+Customizing the installation via installer images
+------------------------------------------------
+
+When installing with the Educates CLI, you can customize the installation in two ways using the ``installerImages`` configuration:
+
+* **Custom bundle**: Replace the default installer bundle with your own customized imgpkg bundle by setting ``installerImages.bundle`` to an OCI image reference. This allows you to use a completely customized installation bundle.
+
+* **Overlays**: Add one or more *installer overlay* bundles by setting ``installerImages.overlays`` to a list of OCI image references. Each overlay is an imgpkg bundle that contains ytt templates or YAML; the CLI fetches these images and runs their content together with the default installer templates. Use this to add resources, patch existing ones, or adjust configuration without forking the installer. Overlay bundles can use any directory layout, as the entire bundle root is passed to ytt.
+
+Both options can be used independently or together. Configure these in your package configuration file under the top-level key ``installerImages``. See [Configuration Settings](configuration-settings) for the ``installerImages`` setting. This option is only available when using the [CLI Based Installation](cli-based-installation); it is not used when installing via Carvel or kapp-controller.
+
 Performing the installation
 ---------------------------
 

Original file line number	Diff line number	Diff line change
`@@ -67,6 +67,7 @@ func (o *ClusterPortalOpenOptions) Run() error {`
`67`	`67`	`return err`
`68`	`68`	`}`
`69`	`69`
	`70`	`+ // TODO: Most of this logic is similar to workshops.OpenBrowser, so we should refactor it to a common function.`
`70`	`71`	`fmt.Printf("Training portal %q.\n", o.Portal)`
`71`	`72`
`72`	`73`	`fmt.Print("Checking training portal is ready.\n")`