Add OLM upgrade support to Makefile and document workflow

Add REPLACES variable to inject `replaces` field into the CSV for OLM
upgrade paths. Add PREV_BUNDLE_IMG and CATALOG_BUNDLE_IMGS variables to
support incremental and from-scratch catalog builds with full upgrade
chains. Fix kustomization.yaml patch accumulation by clearing old patches
before regenerating. Add documentation covering single-version, multi-
version, and complete catalog rebuild workflows.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: stuggi

Makefile

@@ -48,6 +48,10 @@ ifeq ($(USE_IMAGE_DIGESTS), true)
 	BUNDLE_GEN_FLAGS += --use-image-digests
 endif
 
+# REPLACES is the previous version that this version replaces (for OLM upgrades)
+# Example: make bundle REPLACES=openstack-operator.v0.6.0 VERSION=0.6.1
+REPLACES ?=
+
 # Set the Operator SDK version to use. By default, what is installed on the system is used.
 # This is useful for CI or a project to utilize a specific version of the operator-sdk toolkit.
 OPERATOR_SDK_VERSION ?= v1.41.1
@@ -398,10 +402,16 @@ endif
 .PHONY: bundle
 bundle: manifests kustomize operator-sdk ## Generate bundle manifests and metadata, then validate generated files.
 	$(OPERATOR_SDK) generate kustomize manifests -q
-	cd config/operator/deployment/ && $(KUSTOMIZE) edit set image controller=$(IMG) && \
+	cd config/operator/deployment/ && \
+	sed -i '/^patches:/,$$d' kustomization.yaml && \
+	$(KUSTOMIZE) edit set image controller=$(IMG) && \
 	$(KUSTOMIZE) edit add patch --kind Deployment --name openstack-operator-controller-init --namespace system --patch "[{\"op\": \"replace\", \"path\": \"/spec/template/spec/containers/0/env/0\", \"value\": {\"name\": \"OPENSTACK_RELEASE_VERSION\", \"value\": \"$(OPENSTACK_RELEASE_VERSION)\"}}]" && \
 	$(KUSTOMIZE) edit add patch --kind Deployment --name openstack-operator-controller-init --namespace system --patch "[{\"op\": \"replace\", \"path\": \"/spec/template/spec/containers/0/env/1\", \"value\": {\"name\": \"OPERATOR_IMAGE_URL\", \"value\": \"$(IMG)\"}}]"
 	$(KUSTOMIZE) build config/operator --load-restrictor='LoadRestrictionsNone' | $(OPERATOR_SDK) generate bundle $(BUNDLE_GEN_FLAGS)
+ifneq ($(REPLACES),)
+	@echo "Adding replaces: $(REPLACES) to CSV"
+	sed -i "/^  name: openstack-operator.v$(VERSION)/a\  replaces: $(REPLACES)" bundle/manifests/openstack-operator.clusterserviceversion.yaml
+endif
 	$(OPERATOR_SDK) bundle validate ./bundle
 
 .PHONY: bundle-build
@@ -448,12 +458,30 @@ SHELL_EXPORT = $(foreach v,$(MAKE_ENV),$(v)='$($(v))')
 # These images MUST exist in a registry and be pull-able.
 BUNDLE_IMGS = "$(BUNDLE_IMG)$(shell $(SHELL_EXPORT) /bin/bash hack/pin-bundle-images.sh || echo bundle-fail-tag)"
 
+# When REPLACES is set, include the previous version's bundle in the catalog for upgrade support
+# PREV_BUNDLE_IMG can be set to override the default (defaults to upstream :latest)
+# Example: make catalog-build REPLACES=openstack-operator.v0.6.0 PREV_BUNDLE_IMG=quay.io/openstack-k8s-operators/openstack-operator-bundle:latest
+ifneq ($(REPLACES),)
+PREV_BUNDLE_IMG ?= quay.io/openstack-k8s-operators/openstack-operator-bundle:latest
+endif
+
 # The image tag given to the resulting catalog image (e.g. make catalog-build CATALOG_IMG=example.com/operator-catalog:v0.2.0).
 CATALOG_IMG ?= $(IMAGE_TAG_BASE)-index:v$(VERSION)
 
 # Set CATALOG_BASE_IMG to an existing catalog image tag to add $BUNDLE_IMGS to that image.
+# When using a base catalog, only add the NEW bundle (base already has everything else)
+# Alternatively, set CATALOG_BUNDLE_IMGS directly to specify all bundles (for building from scratch without a base)
 ifneq ($(origin CATALOG_BASE_IMG), undefined)
 FROM_INDEX_OPT := --from-index $(CATALOG_BASE_IMG)
+CATALOG_BUNDLE_IMGS ?= $(BUNDLE_IMG)
+else
+# Building from scratch: include previous bundle if REPLACES is set, plus all dependency bundles
+# Can be overridden by setting CATALOG_BUNDLE_IMGS on command line
+ifneq ($(REPLACES),)
+CATALOG_BUNDLE_IMGS ?= $(PREV_BUNDLE_IMG),$(BUNDLE_IMGS)
+else
+CATALOG_BUNDLE_IMGS ?= $(BUNDLE_IMGS)
+endif
 endif
 
 # Build a catalog image by adding bundle images to an empty catalog using the operator package manager tool, 'opm'.
@@ -462,7 +490,7 @@ endif
 .PHONY: catalog-build
 catalog-build: opm ## Build a catalog image.
 	# FIXME: hardcoded bundle below should use go.mod pinned version for manila bundle
-	$(OPM) index add --container-tool podman --mode semver --tag $(CATALOG_IMG) --bundles $(BUNDLE_IMGS) $(FROM_INDEX_OPT)
+	$(OPM) index add --container-tool podman --mode semver --tag $(CATALOG_IMG) --bundles $(CATALOG_BUNDLE_IMGS) $(FROM_INDEX_OPT)
 
 # Push the catalog image.
 .PHONY: catalog-push

docs/building-operator-updates-for-olm.md

@@ -0,0 +1,240 @@
+# Building Operator Updates for OLM
+
+This guide explains how to build operator versions that support OLM (Operator Lifecycle Manager) upgrades.
+
+## Prerequisites
+
+- An existing operator version is deployed via OLM
+- The previous version's bundle exists in a container registry
+- You have push access to your container registry
+
+## Simple Update (Single Version Upgrade)
+
+When creating your first update from an upstream version to your custom version:
+
+**Example: Upgrading from upstream v0.6.0 to custom v0.6.1**
+
+```bash
+IMAGENAMESPACE=userx \
+IMAGE_TAG_BASE=quay.io/userx/openstack-operator \
+REPLACES=openstack-operator.v0.6.0 \
+VERSION=0.6.1 \
+IMG=quay.io/userx/openstack-operator:v0.6.1 \
+make manifests generate bindata build docker-build docker-push bundle bundle-build bundle-push catalog-build catalog-push
+```
+
+**What this does:**
+- Creates v0.6.1 bundle with `replaces: openstack-operator.v0.6.0` in the CSV
+- `PREV_BUNDLE_IMG` defaults to `quay.io/openstack-k8s-operators/openstack-operator-bundle:latest` (upstream)
+- Builds catalog containing both v0.6.0 (upstream) and v0.6.1 (yours)
+- OLM will detect the upgrade path: v0.6.0 → v0.6.1
+
+## Multi-Version Updates (Incremental Upgrades)
+
+When creating subsequent versions on top of your own versions:
+
+**Example: Upgrading from custom v0.6.1 to custom v0.6.2**
+
+```bash
+IMAGENAMESPACE=userx \
+IMAGE_TAG_BASE=quay.io/userx/openstack-operator \
+REPLACES=openstack-operator.v0.6.1 \
+VERSION=0.6.2 \
+IMG=quay.io/userx/openstack-operator:v0.6.2 \
+PREV_BUNDLE_IMG=quay.io/userx/openstack-operator-bundle:v0.6.1 \
+CATALOG_BASE_IMG=quay.io/userx/openstack-operator-index:v0.6.1 \
+make manifests generate bindata build docker-build docker-push bundle bundle-build bundle-push catalog-build catalog-push
+```
+
+**What this does:**
+- Creates v0.6.2 bundle with `replaces: openstack-operator.v0.6.1` in the CSV
+- `PREV_BUNDLE_IMG` points to your v0.6.1 bundle (not upstream)
+- `CATALOG_BASE_IMG` uses your existing v0.6.1 catalog as a base
+- Builds catalog containing v0.6.0 → v0.6.1 → v0.6.2
+- OLM will detect the upgrade path from v0.6.1 to v0.6.2
+
+## Key Variables Explained
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `REPLACES` | Previous CSV name that this version replaces | `openstack-operator.v0.6.1` |
+| `VERSION` | New version being built | `0.6.2` |
+| `IMG` | New operator image | `quay.io/userx/openstack-operator:v0.6.2` |
+| `PREV_BUNDLE_IMG` | Bundle image of the version being replaced (used with `REPLACES`) | `quay.io/userx/openstack-operator-bundle:v0.6.1` |
+| `CATALOG_BASE_IMG` | Existing catalog to build upon (for incremental builds) | `quay.io/userx/openstack-operator-index:v0.6.1` |
+| `CATALOG_BUNDLE_IMGS` | Comma-separated list of all bundles to include (for building complete upgrade path from scratch) | `"bundle1:latest,bundle2:v0.6.1,bundle3:v0.6.2"` |
+
+## Variable Defaults
+
+If not specified:
+- `PREV_BUNDLE_IMG` defaults to `quay.io/openstack-k8s-operators/openstack-operator-bundle:latest` (upstream)
+- `CATALOG_BASE_IMG` - if not set, builds a fresh catalog from scratch
+- `CATALOG_BUNDLE_IMGS` - auto-computed based on other variables (see strategies below)
+
+## Catalog Building Strategies
+
+There are three approaches to building catalogs:
+
+### 1. Incremental Build (Recommended for iterative development)
+
+Use `CATALOG_BASE_IMG` to add the new bundle to an existing catalog:
+
+```bash
+IMAGENAMESPACE=userx \
+IMAGE_TAG_BASE=quay.io/userx/openstack-operator \
+REPLACES=openstack-operator.v0.6.2 \
+VERSION=0.6.3 \
+IMG=quay.io/userx/openstack-operator:v0.6.3 \
+PREV_BUNDLE_IMG=quay.io/userx/openstack-operator-bundle:v0.6.2 \
+CATALOG_BASE_IMG=quay.io/userx/openstack-operator-index:v0.6.2 \
+make catalog-build catalog-push
+```
+
+**Pros:** Fast, builds on existing catalog
+**Cons:** Requires previous catalog to be available
+
+### 2. Auto From Scratch (Single Previous Version)
+
+Use `REPLACES` without `CATALOG_BASE_IMG` to include one previous version:
+
+```bash
+IMAGENAMESPACE=userx \
+IMAGE_TAG_BASE=quay.io/userx/openstack-operator \
+REPLACES=openstack-operator.v0.6.2 \
+VERSION=0.6.3 \
+IMG=quay.io/userx/openstack-operator:v0.6.3 \
+PREV_BUNDLE_IMG=quay.io/userx/openstack-operator-bundle:v0.6.2 \
+make catalog-build catalog-push
+```
+
+**Pros:** Builds from scratch, no base image needed
+**Cons:** Only includes one upgrade step (v0.6.2 → v0.6.3), not the full upgrade path
+
+### 3. Full From Scratch (Complete Upgrade Path)
+
+Specify all bundles explicitly with `CATALOG_BUNDLE_IMGS`:
+
+```bash
+IMAGENAMESPACE=userx \
+IMAGE_TAG_BASE=quay.io/userx/openstack-operator \
+VERSION=0.6.3 \
+IMG=quay.io/userx/openstack-operator:v0.6.3 \
+CATALOG_BUNDLE_IMGS="quay.io/openstack-k8s-operators/openstack-operator-bundle:latest,quay.io/userx/openstack-operator-bundle:v0.6.1,quay.io/userx/openstack-operator-bundle:v0.6.2,quay.io/userx/openstack-operator-bundle:v0.6.3" \
+make catalog-build catalog-push
+```
+
+**Pros:** Complete control, builds full upgrade path from scratch, reproducible
+**Cons:** Must list all bundles manually
+
+**Recommendation:** Use strategy #3 for production releases and strategy #1 for iterative development.
+
+## Deploying the Update
+
+After building and pushing:
+
+1. Update the CatalogSource to use the new catalog image:
+   ```bash
+   oc patch catalogsource openstack-operator-index \
+     -n openstack-operators \
+     --type merge \
+     -p '{"spec":{"image":"quay.io/userx/openstack-operator-index:v0.6.2"}}'
+   ```
+
+2. Delete the catalog pod to force refresh:
+   ```bash
+   oc delete pod -n openstack-operators -l olm.catalogSource=openstack-operator-index
+   ```
+
+3. Check for upgrade:
+   ```bash
+   oc get subscription openstack -n openstack-operators
+   ```
+
+4. Approve the InstallPlan (if using Manual approval):
+   ```bash
+   oc patch installplan <installplan-name> \
+     -n openstack-operators \
+     --type merge \
+     -p '{"spec":{"approved":true}}'
+   ```
+
+## Troubleshooting
+
+### Upgrade not detected
+
+Check that both versions are in the catalog:
+```bash
+oc get packagemanifest openstack-operator -n openstack-operators -o json | \
+  jq -r '.status.channels[] | select(.name=="alpha") | .entries[] | .name'
+```
+
+Both the current and new version should appear.
+
+### Bundle image not found
+
+Ensure the previous bundle was pushed:
+```bash
+skopeo inspect docker://quay.io/userx/openstack-operator-bundle:v0.6.1
+```
+
+## Complete Example Workflows
+
+### Approach A: Incremental Builds (Using CATALOG_BASE_IMG)
+
+Building v0.6.1, v0.6.2, and v0.6.3 incrementally:
+
+```bash
+# First custom version (from upstream v0.6.0)
+IMAGENAMESPACE=userx IMAGE_TAG_BASE=quay.io/userx/openstack-operator \
+REPLACES=openstack-operator.v0.6.0 VERSION=0.6.1 \
+IMG=quay.io/userx/openstack-operator:v0.6.1 \
+make manifests generate bindata build docker-build docker-push bundle bundle-build bundle-push catalog-build catalog-push
+
+# Second version (builds on v0.6.1 catalog)
+IMAGENAMESPACE=userx IMAGE_TAG_BASE=quay.io/userx/openstack-operator \
+REPLACES=openstack-operator.v0.6.1 VERSION=0.6.2 \
+IMG=quay.io/userx/openstack-operator:v0.6.2 \
+PREV_BUNDLE_IMG=quay.io/userx/openstack-operator-bundle:v0.6.1 \
+CATALOG_BASE_IMG=quay.io/userx/openstack-operator-index:v0.6.1 \
+make manifests generate bindata build docker-build docker-push bundle bundle-build bundle-push catalog-build catalog-push
+
+# Third version (builds on v0.6.2 catalog)
+IMAGENAMESPACE=userx IMAGE_TAG_BASE=quay.io/userx/openstack-operator \
+REPLACES=openstack-operator.v0.6.2 VERSION=0.6.3 \
+IMG=quay.io/userx/openstack-operator:v0.6.3 \
+PREV_BUNDLE_IMG=quay.io/userx/openstack-operator-bundle:v0.6.2 \
+CATALOG_BASE_IMG=quay.io/userx/openstack-operator-index:v0.6.2 \
+make manifests generate bindata build docker-build docker-push bundle bundle-build bundle-push catalog-build catalog-push
+```
+
+Each catalog contains the full upgrade path from v0.6.0.
+
+### Approach B: Full From Scratch (Using CATALOG_BUNDLE_IMGS)
+
+Building v0.6.3 with complete upgrade path in one step:
+
+```bash
+# Build all versions
+IMAGENAMESPACE=userx IMAGE_TAG_BASE=quay.io/userx/openstack-operator \
+REPLACES=openstack-operator.v0.6.0 VERSION=0.6.1 \
+IMG=quay.io/userx/openstack-operator:v0.6.1 \
+make manifests generate bindata build docker-build docker-push bundle bundle-build bundle-push
+
+IMAGENAMESPACE=userx IMAGE_TAG_BASE=quay.io/userx/openstack-operator \
+REPLACES=openstack-operator.v0.6.1 VERSION=0.6.2 \
+IMG=quay.io/userx/openstack-operator:v0.6.2 \
+make manifests generate bindata build docker-build docker-push bundle bundle-build bundle-push
+
+IMAGENAMESPACE=userx IMAGE_TAG_BASE=quay.io/userx/openstack-operator \
+REPLACES=openstack-operator.v0.6.2 VERSION=0.6.3 \
+IMG=quay.io/userx/openstack-operator:v0.6.3 \
+make manifests generate bindata build docker-build docker-push bundle bundle-build bundle-push
+
+# Build complete catalog with all bundles
+IMAGENAMESPACE=userx IMAGE_TAG_BASE=quay.io/userx/openstack-operator \
+VERSION=0.6.3 IMG=quay.io/userx/openstack-operator:v0.6.3 \
+CATALOG_BUNDLE_IMGS="quay.io/openstack-k8s-operators/openstack-operator-bundle:latest,quay.io/userx/openstack-operator-bundle:v0.6.1,quay.io/userx/openstack-operator-bundle:v0.6.2,quay.io/userx/openstack-operator-bundle:v0.6.3" \
+make catalog-build catalog-push
+```
+
+This approach is reproducible and doesn't depend on previous catalog images.