revamped artifacts to give good UX to the flow (#1)

Signed-off-by: Jordan Keister <[email protected]>

Author: grokspawn

.github/workflows/ci.yaml

@@ -2,8 +2,7 @@ name: CI
 
 on:
   push:
-    branches:
-      - '**'
+    branches: [ main ]
   pull_request:
     branches: [ main ]
 
@@ -16,7 +15,7 @@ jobs:
     - name: Check out code into the Go module directory
       uses: actions/checkout@v2
 
-    - name: Build
+    - name: Build Catalog
       run: make catalog
 
     - name: Validate
@@ -25,11 +24,6 @@ jobs:
         catalog: catalog
 
     - name: Release
-      #      if: github.event_name == 'push'
-      #uses: catalog-release-bot/catalog-release-bot@main
-      #with:
-      #  catalogDir: catalog
-      #  packageName: example-operator
       if: github.event_name == 'push'
       uses: grokspawn/[email protected]
       env:

Makefile

@@ -1,50 +1,95 @@
 
-OPERATOR_NAME = example-operator
-VERSION ?= "latest"
-INDEX_IMAGE = "quay.io/joelanford/example-operator-index:$(VERSION)"
-
-catalog: bin/opm bin/yq veneer.yaml convert.sh
-	rm -rf catalog && \
-		mkdir -p catalog/$(OPERATOR_NAME) && \
-		./convert.sh veneer.yaml > catalog/$(OPERATOR_NAME)/catalog.yaml && \
-		cp CATALOG_OWNERS catalog/$(OPERATOR_NAME)/OWNERS && \
-		echo "OWNERS" > catalog/$(OPERATOR_NAME)/.indexignore
-
-.PHONY: sanity
-sanity: catalog bin/opm pretest
-	bin/opm validate catalog
-
-.PHONY: pretest
-pretest: bin/yq catalog
-	@./sanity.sh -n $(OPERATOR_NAME) -f catalog/$(OPERATOR_NAME)/catalog.yaml;
-	@if [ $$? -ne 0 ] ; then \
-	   echo "operator name in veneer and Makefile do not agree"; \
-	   false; \
-	fi
-
-.PHONY: build
-build: catalog sanity bin/opm bin/yq
-	bin/opm alpha generate dockerfile catalog
-	docker build -t $(INDEX_IMAGE) -f catalog.Dockerfile .
-	rm catalog.Dockerfile
-
-.PHONY: push
-push: build
-	docker push $(INDEX_IMAGE)
+OPERATOR_NAME = testoperator
+OPERATOR_CATALOG_DIR = catalog/$(OPERATOR_NAME)
+OPERATOR_CATALOG_CONTRIBUTION = $(OPERATOR_CATALOG_DIR)/catalog.yaml
+YQ = bin/yq
+
+
+# the catalog contribution target will enforce that the user selected an FBC build approach and generated the catalog
+$(OPERATOR_CATALOG_CONTRIBUTION):
+	@echo "$(OPERATOR_CATALOG_CONTRIBUTION) does not exist"; \
+         echo ">>> you must first customize and execute 'make catalog' to generate the catalog contribution"; \
+         false;
+
+.PHONY: catalog
+# replace this stub with one customized to serve your needs ... some examples below
+catalog: $(OPERATOR_CATALOG_CONTRIBUTION)
+
+# in order to have a deliverable target, the CI workflow executes the target "catalog" and wraps the resulting catalog contribution in
+# a PR to the modeled catalog repo
+#
+# here are a few examples of different approaches to fulfilling this target
+# comment out / customize the one that makes the most sense, or use them as examples in defining your own
+#
+# --- BASIC VENEER ---
+#catalog: basic framework
+#
+# --- SEMVER VENEER ---
+#catalog: semver framework
+#
+#  --- COMPOUND VENEER ---
+#  this case is for when a single veneer cannot support the use-case, and automated changes to the generated FBC need to be made before it is complete
+#  this example models the need to set the v0.2.1 of the operator with the `olm.deprecated` property, to prevent installation
+#
+#catalog: $(YQ) semver framework
+#	$(YQ) eval 'select(.name == "testoperator.v0.2.1" and .schema == "olm.bundle").properties += [{"type" : "olm.deprecated", "value" : "true"}]' -i  $(OPERATOR_CATALOG_CONTRIBUTION)
+
+# framework target provides two pieces that are helpful for any veneer approach:  
+#  - an OWNERS file to provide default contribution control
+#  - an .indexignore file to illustrate how to add content to the FBC contribution which should be 
+#    excluded from validation via `opm validate`
+.PHONY: framework
+framework: CATALOG_OWNERS
+	cp CATALOG_OWNERS $(OPERATOR_CATALOG_DIR)/OWNERS && \
+         echo "OWNERS" > $(OPERATOR_CATALOG_DIR)/.indexignore
+
+
+# basic target provides an example FBC generation from a `basic` veneer type.  
+# this example takes a single file as input and generates a well-formed FBC operator contribution as an output
+# the 'validate' target should be used next to validate the output
+.PHONY: basic
+basic: bin/opm basic-veneer.yaml clean
+	mkdir -p $(OPERATOR_CATALOG_DIR) && bin/opm alpha render-veneer basic -o yaml basic-veneer.yaml > $(OPERATOR_CATALOG_CONTRIBUTION)
+
+
+# semver target provides an example FBC generation from a `semver` veneer type.  
+# this example takes a single file as input and generates a well-formed FBC operator contribution as an output
+# the 'validate' target should be used next to validate the output
+.PHONY: semver
+semver: bin/opm semver-veneer.yaml clean
+	mkdir -p $(OPERATOR_CATALOG_DIR) && bin/opm alpha render-veneer semver -o yaml semver-veneer.yaml > $(OPERATOR_CATALOG_CONTRIBUTION)
+
+
+# validate target illustrates FBC validation
+# all FBC must pass opm validation in order to be able to be used in a catalog
+.PHONY: validate
+validate: bin/opm $(OPERATOR_CATALOG_CONTRIBUTION) preverify
+	bin/opm validate catalog && echo "catalog validation passed" || echo "catalog validation failed"
+
+
+# preverify target ensures that the operator name is consistent between the destination directory and the generated catalog
+# since the veneer will be modified outside the build process but needs to be consistent with the directory name
+.PHONY: preverify
+preverify: $(YQ) $(OPERATOR_CATALOG_CONTRIBUTION)
+	./validate.sh -n $(OPERATOR_NAME) -f $(OPERATOR_CATALOG_CONTRIBUTION)
+
 
 .PHONY: clean
 clean:
-	rm -r catalog
+	rm -rf catalog
+
 
 OS=$(shell uname -s | tr '[:upper:]' '[:lower:]')
 ARCH=$(shell uname -m | sed 's/x86_64/amd64/')
-OPM_VERSION=v1.19.5
+OPM_VERSION ?= v1.26.1
 bin/opm:
 	mkdir -p bin
 	curl -sLO https://github.com/operator-framework/operator-registry/releases/download/$(OPM_VERSION)/$(OS)-$(ARCH)-opm && chmod +x $(OS)-$(ARCH)-opm && mv $(OS)-$(ARCH)-opm bin/opm
 
+
 YQ_VERSION=v4.22.1
 YQ_BINARY=yq_$(OS)_$(ARCH)
-bin/yq:
+$(YQ):
 	if [ ! -e bin ] ; then mkdir -p bin; fi
-	wget  https://github.com/mikefarah/yq/releases/download/${YQ_VERSION}/${YQ_BINARY} -O bin/${YQ_BINARY} && mv -f bin/${YQ_BINARY} bin/yq && chmod +x bin/yq
+	wget  https://github.com/mikefarah/yq/releases/download/${YQ_VERSION}/${YQ_BINARY} -O bin/${YQ_BINARY} && mv -f bin/${YQ_BINARY} $(YQ) && chmod +x $(YQ)
+

README.md

@@ -1,6 +1,97 @@
 # example-operator-index
+Welcome! This repository provides a starting point for those interested in maintaining the catalog information for their operator and illustrates how that information contributes to an overall catalog ecosystem. 
 
+
+## Quickstart
+1. fork this repository
+2. adjust destination fields in .github/workflows/ci.yaml as necessary, commit and push changes
+3. adjust Makefile `$OPERATOR_NAME` for your operator's name
+2. decide on an approach: basic veneer, semver veneer, custom veneers, raw FBC, etc. and adjust the 'catalog' target in Makefile to generate your desired FBC
+4. run local tests (`make catalog`, `make validate`, etc.) until happy with the generated FBC
+6. add, commit, and push the changes
+7. verify that CI passes and opens a PR in the catalog repository
+
+
+
+## Detailed HOWTO
+### Actors and Terms
+- [`File-Based Catalog`](https://olm.operatorframework.io/docs/reference/file-based-catalogs/) (FBC) is the declarative expression of operators and their relationships with other operators, other versions of themselves.
+- [`Veneers`](https://olm.operatorframework.io/docs/reference/veneers/) are a general class of objects which can provide a simplified interaction with FBC.
+- `Operator Author` is the role related to expressing an individual operator versions, channels, properties, etc. in a destination catalog.
+- `Catalog` is the destination FBC-based catalog composed of the FBC contributions of one or more operators.
+- `Catalog Owner` is the role related to integrating Operator Authors' catalog contributions.
+- `Catalog Contribution` is the FBC that an Operator Author needs to convey to the Catalog Owner.  The format needs to be negotiated with the Catalog Owner.
+For this example, the Catalog Owner receives contributions of a single, unversioned directory named after the operator which contain all FBC files, e.g.:
+
+```tree
+catalog
+└── testoperator
+    ├── .indexignore
+    ├── OWNERS
+    └── catalog.yaml
+```
+
+
+### Lifecycle
+This repository models a single operator author contributing their FBC to a catalog.  This repository has pre-configured GitHub actions to deliver the FBC to an example [catalog GitHub repository](https://github.com/grokspawn/cool-catalog/).  The actions will generate the FBC from this repository and open a pull request on the catalog repository to merge them.  (See that repository for more information about the lifecycle steps after creating the pull request.)
+
+
+```mermaid
+%%{init: {'securityLevel': 'strict', 'theme':'forest'}}%%
+
+sequenceDiagram
+autonumber
+participant User
+participant LocalRepo
+participant RemoteRepo
+participant GHAction
+participant CatalogRepo
+activate User
+activate RemoteRepo
+User-->RemoteRepo: fork and clone repository
+activate LocalRepo
+User->>LocalRepo: update CI destination
+LocalRepo->>RemoteRepo: push CI changes to remote
+activate RemoteRepo
+User->>LocalRepo: update 'catalog' target
+LocalRepo->>RemoteRepo: push changes to remote
+deactivate LocalRepo
+deactivate User
+RemoteRepo--xGHAction: <<push trigger>
+deactivate RemoteRepo
+activate GHAction
+GHAction->>GHAction: Generate FBC from 'catalog' target
+GHAction->>GHAction: validate FBC
+activate CatalogRepo
+GHAction->>CatalogRepo: Open PR in catalog destination
+deactivate GHAction
+deactivate CatalogRepo
+
+```
+
+1. Fork and Clone Remote Repository  
+IMPORTANT!  Any operator-specific changes contributions to the parent repository will be discarded.
+
+2. Update CI Destination  
+Customize `.github/workflows/ci.yaml` to your needs, including setting the `destination_repo` to the URI of your catalog repository. 
+
+3. Push Changes to Remote
+Push the CI changes to the remote branch so they will trigger later when you push catalog contributions.
+
+4. Update 'catalog' target
+Locally, update the catalog target in the Makefile to generate your FBC.  Example targets are provided in the Makefile (with supporting artifacts) to support to the following scenarios:  
+   1. Basic veneer generates FBC.
+   2. Semver veneer generates FBC.
+   3. Compound veneer generates and post-processes FBC. 
+
+5. Push Changes to Remote  
+Once the `catalog` make target and the resulting FBC are ready, push the changes to the remote repository.  This will trigger the remote actions to generate a pull request against the destination catalog repository as specified in #2.
+
+
+
+<!--
 ## Demo
-Recorded demo of modifying veneer.yaml, building, and pushing veneer to collection repository. 
+Recorded demo of modifying a `basic veneer` file "basic-veneer.yaml", generating an FBC from it, and pushing that FBC as a PR to a catalog repository.
 
 ![asciicast](demo/fbc-veneer-demo-console.gif)
+ -->

basic-veneer.yaml

@@ -0,0 +1,19 @@
+---
+schema: olm.package
+name: testoperator
+defaultChannel: stable
+---
+schema: olm.channel
+package: testoperator
+name: stable
+entries:
+- name: testoperator.v0.1.0
+- name: testoperator.v0.2.0
+  replaces: testoperator.v0.1.0
+---
+schema: olm.bundle
+image: quay.io/ankitathomas/olm:testoperator.v0.1.0
+---
+schema: olm.bundle
+image: quay.io/ankitathomas/olm:testoperator.v0.2.0
+

build.sh

@@ -1,4 +1,4 @@
-#! /bin/bash
+#!/usr/bin/env bash
 #  PNAME=$$(bin/yq "select(.schema == \"olm.package\") | .name" catalog/$(OPERATOR_NAME)/catalog.yaml)
 #  @echo `bin/yq "select(.schema == \"olm.package\") | .name" catalog/$(OPERATOR_NAME)/catalog.yaml`
 #  @export PNAME=$(shell bin/yq "select(.schema == \"olm.package\") | .name" catalog/$(OPERATOR_NAME)/catalog.yaml)
@@ -13,13 +13,21 @@ function usage () {
   exit 1
 }
 
+function logit() {
+    if [ $QUIET_MODE -eq 0 ]; then
+        echo $1
+    fi
+}
+
 YQ=bin/yq
+QUIET_MODE=0
 
-while getopts 'n:f:' arg; 
+while getopts 'n:f:q' arg; 
 do
   case "$arg" in
     f) FILENAME=$OPTARG ;;
     n) PKGNAME=$OPTARG ;;
+    q) QUIET_MODE=1 ;;
     h) usage ;; 
   esac
 done
@@ -30,37 +38,37 @@ shift `expr $OPTIND - 1`
 
 if [ -z $FILENAME ]
 then
-  echo "veneer-file-name is empty"
+  logit "veneer-file-name is empty"
   usage
 fi
 
 if [ ! -e $FILENAME ]
 then
-  echo "$FILENAME does not exist"
+  logit "$FILENAME does not exist"
   exit 253
 fi
 
 if [ -z $PKGNAME ]
 then
-  echo "package-name is empty"
+  logit "package-name is empty"
   usage
 fi
 
 if [ ! -e $YQ ]
 then
-  echo "unable to find yq binary: $YQ"
+  logit "unable to find yq binary: $YQ"
   exit 255
 fi
 
 SCHEMA_PNAME=$($YQ "select(.schema == \"olm.package\") | .name" ${FILENAME})
 if [ $SCHEMA_PNAME != $PKGNAME ] 
 then
-  echo "operator name in veneer and Makefile do not agree:"
-  echo "    Makefile(${SCHEMA_PNAME})"
-  echo "    veneer(  ${PKGNAME})"
+  logit "operator name in catalog and Makefile do not agree:"
+  logit "    Makefile(${SCHEMA_PNAME})"
+  logit "    catalog (${PKGNAME})"
   exit 254
 else
-  echo "operator name match between veneer and Makefile"
+  logit "operator name match between catalog and Makefile"
 fi