doc/design/milestone-0.0.7/csv-generation.md: explanation of and example code for 'CSVUpdater' interface

Author: estroz

doc/design/milestone-0.0.7/csv-generation.md

@@ -42,7 +42,80 @@ type CSVUpdater interface {
 }
 ```
 
-`Apply` will use data from the underlying implementer of the `CSVUpdater` interface to operate on `*v1alpha1.ClusterServiceVersion` instance fields relevant to that updater. The OLM defines the entire CSV spec [in Golang][olm-code-csv-spec] as separate `struct` components, each of which we can alias to implement `CSVUpdater`. Once sub-step 2 is reached when creating or updating a CSV, `renderCSV` will extract each yaml document discovered, and pass document data into a dispatcher function. The dispatcher selects the correct `CSVUpdater` to populate based on the documents' `Kind` yaml object, a manifest type identifier used in all (TODO: verify) operator manifests.
+`Apply` will use data from the underlying implementer of the `CSVUpdater` interface to operate on `*v1alpha1.ClusterServiceVersion` instance fields relevant to that updater. The OLM defines the entire CSV spec [in Golang][olm-code-csv-spec] as a (versioned) hierarchy of `struct` components, each of which we can alias to implement `CSVUpdater`. Once sub-step 2 is reached when creating or updating a CSV, `renderCSV` will extract each yaml document discovered, and pass document data into a dispatcher function. The dispatcher selects the correct `CSVUpdater` to populate based on the documents' `Kind` yaml object, a manifest type identifier used in all (*TODO*: verify) operator manifests. We access the latest version of CSV format and maintain OLM compatibility by leveraging the OLM spec implementations, rather than implementing the spec locally. The following is an example implementation of an [install strategy][olm-csv-install-strat-doc] `CSVUpdater`:
+
+```Go
+import (
+  ...
+  appsv1 "k8s.io/api/apps/v1"
+  rbacv1beta1 "k8s.io/api/rbac/v1beta1"
+	"github.com/operator-framework/operator-lifecycle-manager/pkg/api/apis/operators/v1alpha1"
+  "github.com/operator-framework/operator-lifecycle-manager/pkg/controller/install"
+)
+
+// CSVInstallStrategyUpdate embeds the OLM's install strategy spec.
+type CSVInstallStrategyUpdate struct {
+	*install.StrategyDetailsDeployment
+  
+  // Future utility fields go here.
+}
+
+// getLocalInstallStrategyCache retrieves the local cache singleton and returns the install strategy cache.
+func getLocalInstallStrategyCache() *CSVInstallStrategyUpdate {
+	factory := getLocalCacheFactory()
+	return factory.InstallStrategyCache
+}
+
+// AddDeploymentSpecToCSVInstallStrategyUpdate adds an RBAC Role to the local cache singletons' permissions.
+func AddRoleToCSVInstallStrategyUpdate(yamlDoc []byte) error {
+	localInstallStrategyUpdate := getLocalInstallStrategyCache()
+
+	newRBACRole := new(rbacv1beta1.Role)
+	_ = yaml.Unmarshal(yamlDoc, newRBACRole)
+
+	newPermissions := install.StrategyDeploymentPermissions{
+		ServiceAccountName: newRole.ObjectMeta.Name,
+		Rules:              newRole.Rules,
+	}
+	localInstallStrategyUpdate.Permissions = append(localInstallStrategyUpdate.Permissions, newPermissions)
+
+	return nil
+}
+
+// AddDeploymentSpecToCSVInstallStrategyUpdate adds a Deployment to the local cache singletons' install strategy.
+func AddDeploymentSpecToCSVInstallStrategyUpdate(yamlDoc []byte) error {
+	localInstallStrategyUpdate := getLocalInstallStrategyCache()
+
+	newDeployment := new(appsv1.Deployment)
+	_ = yaml.Unmarshal(yamlDoc, newDeployment)
+  
+	newDeploymentSpec := install.StrategyDeploymentSpec{
+		Name: newDeployment.ObjectMeta.Name,
+		Spec: newDeployment.Spec,
+	}
+	localInstallStrategyUpdate.DeploymentSpecs = append(localInstallStrategyUpdate.DeploymentSpecs, newDeploymentSpec)
+
+	return nil
+}
+
+// Apply applies cached updates in CSVInstallStrategyUpdate to the appropriate csv fields.
+func (us *CSVInstallStrategyUpdate) Apply(csv *v1alpha1.ClusterServiceVersion) error {
+	// Get install strategy from csv.
+	var resolver *install.StrategyResolver
+	strat, _ := resolver.UnmarshalStrategy(csv.Spec.InstallStrategy)
+	installStrat, _ := strat.(*install.StrategyDetailsDeployment)
+
+	// Update permissions and deployments with custom field update methods.
+	us.updatePermissions(installStrat)
+	us.updateDeploymentSpecs(installStrat)
+
+	// Re-serialize permissions into csv install strategy.
+	updatedStrat, _ := json.Marshal(installStrat)
+	csv.Spec.InstallStrategy.StrategySpecRaw = updatedStrat
+
+	return nil
+}
+```
 
 ### User-defined yaml objects
 
@@ -106,11 +179,7 @@ customresourcedefinitions:
       ...
 ```
 
-Each of the above yaml objects corresponds to homonymous `spec` object children described by the CSV [`spec` documentation][olm-csv-spec-doc]. [Here][describe-yaml-example] is an example `describe.yaml` a Prometheus operator developer would write to assist in CSV generation.
-
-## API
-
-## Reference
+Each of the above yaml objects corresponds to homonymous `spec` object children described by the CSV [`spec` documentation][olm-csv-spec-doc]. [Here][describe-yaml-example] is a workable, complex example `describe.yaml` a Prometheus operator developer would write to assist the SDK in CSV generation.
 
 
 [olm-csv-definition]:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Documentation/design/building-your-csv.md#what-is-a-cluster-service-version-csv
@@ -119,4 +188,5 @@ Each of the above yaml objects corresponds to homonymous `spec` object children
 [olm-code-csv-struct]:https://github.com/operator-framework/operator-lifecycle-manager/blob/8799f39ef342dc1ff7430eba7a88c1c3c70cbdcc/pkg/api/apis/operators/v1alpha1/clusterserviceversion_types.go#L261
 [olm-code-csv-spec]:https://github.com/operator-framework/operator-lifecycle-manager/blob/8799f39ef342dc1ff7430eba7a88c1c3c70cbdcc/pkg/api/apis/operators/v1alpha1/clusterserviceversion_types.go
 [olm-csv-spec-doc]:https://github.com/operator-framework/operator-lifecycle-manager/blob/16ff8f983b50503c4d8b8015bd0c14b5c7d6786a/Documentation/design/building-your-csv.md#building-a-cluster-service-version-csv-for-the-operator-framework
+[olm-csv-install-strat-doc]:https://github.com/operator-framework/operator-lifecycle-manager/blob/16ff8f983b50503c4d8b8015bd0c14b5c7d6786a/Documentation/design/building-your-csv.md#operator-install
 [describe-yaml-example]:example.describe.yaml