(manifests/v2) add catalog targets to Makefile (#4406)

internal/plugins/manifests/v2: add 'catalog-build', 'catalog-push',
and 'opm' targets to Makefile; improve variable usage

Signed-off-by: Eric Stroczynski <[email protected]>

Author: Eric Stroczynski

changelog/fragments/make-catalog-build.yaml

@@ -0,0 +1,72 @@
+entries:
+  - description: >
+      (go/v2, go/v3, ansible/v1, helm/v1) Added the `opm` and `catalog-build` Makefile targets to
+      download [`opm`](https://github.com/operator-framework/operator-registry/blob/v1.15.1/docs/design/opm-tooling.md)
+      and build operator catalogs either from scratch or an existing catalog.
+    kind: addition
+    migration:
+      header: (go/v2, go/v3, ansible/v1, helm/v1) Add `opm` and `catalog-build` Makefile targets
+      body: >
+        The `opm` and `catalog-build` Makefile targets were added so operator developers who
+        want to create their own catalogs for their operator or add their operator's bundle(s) to an
+        existing catalog can do so. If this sounds like you, add the following lines to the bottom
+        of your Makefile:
+
+        ```make
+        .PHONY: opm
+        OPM = ./bin/opm
+        opm:
+        ifeq (,$(wildcard $(OPM)))
+        ifeq (,$(shell which opm 2>/dev/null))
+        	@{ \
+        	set -e ;\
+        	mkdir -p $(dir $(OPM)) ;\
+        	curl -sSLo $(OPM) https://github.com/operator-framework/operator-registry/releases/download/v1.15.1/$(OS)-$(ARCH)-opm ;\
+        	chmod +x $(OPM) ;\
+        	}
+        else
+        OPM = $(shell which opm)
+        endif
+        endif
+
+        BUNDLE_IMGS ?= $(BUNDLE_IMG)
+        CATALOG_IMG ?= $(IMAGE_TAG_BASE)-catalog:v$(VERSION)
+        ifneq ($(origin CATALOG_BASE_IMG), undefined)
+        FROM_INDEX_OPT := --from-index $(CATALOG_BASE_IMG)
+        endif
+        .PHONY: catalog-build
+        catalog-build: opm
+        	$(OPM) index add --mode semver --tag $(CATALOG_IMG) --bundles $(BUNDLE_IMGS) $(FROM_INDEX_OPT)
+
+        # Push the catalog image.
+        .PHONY: catalog-push
+        catalog-push:
+        	$(MAKE) docker-push IMG=$(CATALOG_IMG)
+        ```
+
+        If updating a Go operator project, additionally add the following Makefile variables:
+
+        ```make
+        OS = $(shell go env GOOS)
+        ARCH = $(shell go env GOARCH)
+        ```
+  - description: >
+      (go/v2, go/v3, ansible/v1, helm/v1) Changed `BUNDLE_IMG` and added `IMAGE_TAG_BASE` Makefile variables
+      to allow one line bundle and catalog image builds.
+    kind: change
+    migration:
+      header: (go/v2, go/v3, ansible/v1, helm/v1) Changed `BUNDLE_IMG` and added `IMAGE_TAG_BASE` Makefile variables
+      body: >
+        The following Makefile changes were made to allow `make bundle-build bundle-push catalog-build catalog-push`
+        and encode image repo/namespace information in the Makefile by default:
+
+        ```diff
+        +IMAGE_TAG_BASE ?= <registry>/<operator name>
+        +
+        -BUNDLE_IMG ?= controller-bundle:$(VERSION)
+        +BUNDLE_IMG ?= $(IMAGE_TAG_BASE)-bundle:v$(VERSION)
+        ```
+
+        For example, if `IMAGE_TAG_BASE ?= foo/bar-operator` then running `make bundle-build bundle-push catalog-build catalog-push`
+        would build `foo/bar-operator-bundle:v0.0.1` and `foo/bar-operator-catalog:v0.0.1` then push them to the
+        `docker.io/foo` namespaced registry.

internal/plugins/manifests/api.go

@@ -30,8 +30,7 @@ import (
 // RunCreateAPI runs the manifests SDK phase 2 plugin.
 func RunCreateAPI(cfg config.Config, gvk resource.GVK) error {
 	// Only run these if project version is v3.
-	isV3 := cfg.GetVersion().Compare(cfgv3.Version) == 0
-	if !isV3 {
+	if cfg.GetVersion().Compare(cfgv3.Version) != 0 {
 		return nil
 	}
 

internal/plugins/manifests/init.go

@@ -19,18 +19,23 @@ import (
 	"fmt"
 	"io/ioutil"
 	"os"
+	"path/filepath"
+	"strings"
 
 	"sigs.k8s.io/kubebuilder/v3/pkg/config"
 	cfgv3 "sigs.k8s.io/kubebuilder/v3/pkg/config/v3"
 
 	"github.com/operator-framework/operator-sdk/internal/util/projutil"
 )
 
+// Version of `opm` to download and use for building index images.
+// This version's release artifacts *must* contain a binary for multiple arches; certain releases do not.
+const opmVersion = "v1.15.1"
+
 // RunInit modifies the project scaffolded by kubebuilder's Init plugin.
 func RunInit(cfg config.Config) error {
 	// Only run these if project version is v3.
-	isV3 := cfg.GetVersion().Compare(cfgv3.Version) == 0
-	if !isV3 {
+	if cfg.GetVersion().Compare(cfgv3.Version) != 0 {
 		return nil
 	}
 
@@ -43,26 +48,44 @@ func RunInit(cfg config.Config) error {
 
 // initUpdateMakefile updates a vanilla kubebuilder Makefile with operator-sdk recipes.
 func initUpdateMakefile(cfg config.Config, filePath string) error {
+	operatorType := projutil.PluginKeyToOperatorType(cfg.GetLayout())
+	if operatorType == projutil.OperatorTypeUnknown {
+		return fmt.Errorf("unsupported plugin key %q", cfg.GetLayout())
+	}
+
 	makefileBytes, err := ioutil.ReadFile(filePath)
 	if err != nil {
 		return err
 	}
 
 	// Prepend bundle variables.
-	makefileBytes = append([]byte(makefileBundleVarFragment), makefileBytes...)
+	projectName := cfg.GetProjectName()
+	if projectName == "" {
+		dir, err := os.Getwd()
+		if err != nil {
+			return fmt.Errorf("error getting current directory: %v", err)
+		}
+		projectName = strings.ToLower(filepath.Base(dir))
+	}
+	makefileBytes = append([]byte(fmt.Sprintf(makefileBundleVarFragment, cfg.GetDomain(), projectName)), makefileBytes...)
 
 	// Append bundle recipes.
-	operatorType := projutil.PluginKeyToOperatorType(cfg.GetLayout())
 	switch operatorType {
-	case projutil.OperatorTypeUnknown:
-		return fmt.Errorf("unsupported plugin key %q", cfg.GetLayout())
 	case projutil.OperatorTypeGo:
 		makefileBytes = append(makefileBytes, []byte(makefileBundleFragmentGo)...)
 	default:
 		makefileBytes = append(makefileBytes, []byte(makefileBundleFragmentNonGo)...)
 	}
+	makefileBytes = append(makefileBytes, []byte(makefileBundleBuildPushFragment)...)
 
-	makefileBytes = append(makefileBytes, []byte(makefileBundleBuildFragment)...)
+	// Append catalog recipes.
+	switch operatorType {
+	case projutil.OperatorTypeGo:
+		makefileBytes = append(makefileBytes, []byte(fmt.Sprintf(makefileOPMFragmentGo, opmVersion))...)
+	default:
+		makefileBytes = append(makefileBytes, []byte(fmt.Sprintf(makefileOPMFragmentNonGo, opmVersion))...)
+	}
+	makefileBytes = append(makefileBytes, []byte(makefileCatalogBuildFragment)...)
 
 	var mode os.FileMode = 0644
 	if info, err := os.Stat(filePath); err != nil {
@@ -73,14 +96,14 @@ func initUpdateMakefile(cfg config.Config, filePath string) error {
 
 // Makefile fragments to add to the base Makefile.
 const (
-	makefileBundleVarFragment = `# VERSION defines the project version for the bundle. 
+	makefileBundleVarFragment = `# VERSION defines the project version for the bundle.
 # Update this value when you upgrade the version of your project.
 # To re-generate a bundle for another specific version without changing the standard setup, you can:
 # - use the VERSION as arg of the bundle target (e.g make bundle VERSION=0.0.2)
 # - use environment variables to overwrite this value (e.g export VERSION=0.0.2)
 VERSION ?= 0.0.1
 
-# CHANNELS define the bundle channels used in the bundle. 
+# CHANNELS define the bundle channels used in the bundle.
 # Add a new line here if you would like to change its default config. (E.g CHANNELS = "preview,fast,stable")
 # To re-generate a bundle for other specific channels without changing the standard setup, you can:
 # - use the CHANNELS as arg of the bundle target (e.g make bundle CHANNELS=preview,fast,stable)
@@ -89,7 +112,7 @@ ifneq ($(origin CHANNELS), undefined)
 BUNDLE_CHANNELS := --channels=$(CHANNELS)
 endif
 
-# DEFAULT_CHANNEL defines the default channel used in the bundle. 
+# DEFAULT_CHANNEL defines the default channel used in the bundle.
 # Add a new line here if you would like to change its default config. (E.g DEFAULT_CHANNEL = "stable")
 # To re-generate a bundle for any other default channel without changing the default setup, you can:
 # - use the DEFAULT_CHANNEL as arg of the bundle target (e.g make bundle DEFAULT_CHANNEL=stable)
@@ -99,32 +122,106 @@ BUNDLE_DEFAULT_CHANNEL := --default-channel=$(DEFAULT_CHANNEL)
 endif
 BUNDLE_METADATA_OPTS ?= $(BUNDLE_CHANNELS) $(BUNDLE_DEFAULT_CHANNEL)
 
-# BUNDLE_IMG defines the image:tag used for the bundle. 
+# IMAGE_TAG_BASE defines the docker.io namespace and part of the image name for remote images.
+# This variable is used to construct full image tags for bundle and catalog images.
+#
+# For example, running 'make bundle-build bundle-push catalog-build catalog-push' will build and push both
+# %[1]s/%[2]s-bundle:$VERSION and %[1]s/%[2]s-catalog:$VERSION.
+IMAGE_TAG_BASE ?= %[1]s/%[2]s
+
+# BUNDLE_IMG defines the image:tag used for the bundle.
 # You can use it as an arg. (E.g make bundle-build BUNDLE_IMG=<some-registry>/<project-name-bundle>:<tag>)
-BUNDLE_IMG ?= controller-bundle:$(VERSION)
+BUNDLE_IMG ?= $(IMAGE_TAG_BASE)-bundle:v$(VERSION)
 `
 
 	makefileBundleFragmentGo = `
-.PHONY: bundle ## Generate bundle manifests and metadata, then validate generated files.
-bundle: manifests kustomize
+.PHONY: bundle
+bundle: manifests kustomize ## Generate bundle manifests and metadata, then validate generated files.
 	operator-sdk generate kustomize manifests -q
 	cd config/manager && $(KUSTOMIZE) edit set image controller=$(IMG)
 	$(KUSTOMIZE) build config/manifests | operator-sdk generate bundle -q --overwrite --version $(VERSION) $(BUNDLE_METADATA_OPTS)
 	operator-sdk bundle validate ./bundle
 `
 
 	makefileBundleFragmentNonGo = `
-.PHONY: bundle ## Generate bundle manifests and metadata, then validate generated files.
-bundle: kustomize
+.PHONY: bundle
+bundle: kustomize ## Generate bundle manifests and metadata, then validate generated files.
 	operator-sdk generate kustomize manifests -q
 	cd config/manager && $(KUSTOMIZE) edit set image controller=$(IMG)
 	$(KUSTOMIZE) build config/manifests | operator-sdk generate bundle -q --overwrite --version $(VERSION) $(BUNDLE_METADATA_OPTS)
 	operator-sdk bundle validate ./bundle
 `
 
-	makefileBundleBuildFragment = `
-.PHONY: bundle-build ## Build the bundle image.
-bundle-build:
+	makefileBundleBuildPushFragment = `
+.PHONY: bundle-build
+bundle-build: ## Build the bundle image.
 	docker build -f bundle.Dockerfile -t $(BUNDLE_IMG) .
+
+.PHONY: bundle-push
+bundle-push: ## Push the bundle image.
+	$(MAKE) docker-push IMG=$(BUNDLE_IMG)
+`
+
+	makefileOPMFragmentGo = `
+.PHONY: opm
+OPM = ./bin/opm
+opm: ## Download opm locally if necessary.
+ifeq (,$(wildcard $(OPM)))
+ifeq (,$(shell which opm 2>/dev/null))
+	@{ \
+	set -e ;\
+	mkdir -p $(dir $(OPM)) ;\
+	OS=$(shell go env GOOS) && ARCH=$(shell go env GOARCH) && \
+	curl -sSLo $(OPM) https://github.com/operator-framework/operator-registry/releases/download/%[1]s/$${OS}-$${ARCH}-opm ;\
+	chmod +x $(OPM) ;\
+	}
+else
+OPM = $(shell which opm)
+endif
+endif
+`
+
+	makefileOPMFragmentNonGo = `
+.PHONY: opm
+OPM = ./bin/opm
+opm: ## Download opm locally if necessary.
+ifeq (,$(wildcard $(OPM)))
+ifeq (,$(shell which opm 2>/dev/null))
+	@{ \
+	set -e ;\
+	mkdir -p $(dir $(OPM)) ;\
+	curl -sSLo $(OPM) https://github.com/operator-framework/operator-registry/releases/download/%[1]s/$(OS)-$(ARCH)-opm ;\
+	chmod +x $(OPM) ;\
+	}
+else
+OPM = $(shell which opm)
+endif
+endif
+`
+
+	makefileCatalogBuildFragment = `
+# A comma-separated list of bundle images (e.g. make catalog-build BUNDLE_IMGS=example.com/operator-bundle:v0.1.0,example.com/operator-bundle:v0.2.0).
+# These images MUST exist in a registry and be pull-able.
+BUNDLE_IMGS ?= $(BUNDLE_IMG)
+
+# 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)-catalog:v$(VERSION)
+
+# Set CATALOG_BASE_IMG to an existing catalog image tag to add $BUNDLE_IMGS to that image.
+ifneq ($(origin CATALOG_BASE_IMG), undefined)
+FROM_INDEX_OPT := --from-index $(CATALOG_BASE_IMG)
+endif
+
+# Build a catalog image by adding bundle images to an empty catalog using the operator package manager tool, 'opm'.
+# This recipe invokes 'opm' in 'semver' bundle add mode. For more information on add modes, see:
+# https://github.com/operator-framework/community-operators/blob/7f1438c/docs/packaging-operator.md#updating-your-existing-operator
+.PHONY: catalog-build
+catalog-build: opm ## Build a catalog image.
+	$(OPM) index add --mode semver --tag $(CATALOG_IMG) --bundles $(BUNDLE_IMGS) $(FROM_INDEX_OPT)
+
+# Push the catalog image.
+.PHONY: catalog-push
+catalog-push: ## Push a catalog image.
+	$(MAKE) docker-push IMG=$(CATALOG_IMG)
 `
 )