internal/scaffold/olm-catalog: populate CSV customresourcedefinitions from Go type annotations

doc/user/olm-catalog/csv-annotations.md

@@ -0,0 +1,195 @@
+# Code Annotations for Cluster Service Versions
+
+## Overview
+
+This document describes the semantics of Cluster Service Version (CSV) [code annotations][code-annotations-design] and lists all possible annotations.
+
+## Usage
+
+All annotations have a `+operator-sdk:gen-csv` prefix, denoting that they're parsed while executing [`operator-sdk olm-catalog gen-csv`][sdk-cli-ref].
+
+### Paths
+
+Paths are dot-separated string hierarchies with the above prefix that map to CSV [`spec`][csv-spec] field names.
+
+Example: `+operator-sdk:gen-csv:customresourcedefinitions.specDescriptors.displayName="Pod Count"`
+
+#### customresourcedefinitions
+
+- `customresourcedefinitions`: child path token
+	- `displayName`: quoted string or string literal
+	- `resources`: quoted string or string literal, in the format `"kind,version,\"name\""` or `` `kind,version,"name"` ``, where `kind`, `version`, and `name` are fields in each CSV `resources` entry
+	- `specDescriptors`, `statusDescriptors`: bool, or child path token
+		- `displayName`: quoted string or string literal
+		- `x-descriptors`: quoted string or string literal comma-separated list of [`x-descriptor`][csv-x-desc] UI hints.
+
+**NOTES**
+- `specDescriptors` and `statusDescriptors` with a value of `true` is required for each field to be included in their respective `customresourcedefinitions` CSV fields. See the examples below.
+- `customresourcedefinitions` top-level `kind`, `name`, and `version` fields are parsed from API code.
+- All `description` fields are parsed from type declaration and `struct` type field comments.
+- `path` is parsed out of a field's JSON tag and merged with parent field path's in dot-hierarchy notation.
+
+### Examples
+
+These examples assume `Memcached`, `MemcachedSpec`, and `MemcachedStatus` are the example projects' kind, spec, and status.
+
+1. Set a display name for a `customresourcedefinitions` kind entry:
+
+```go
+// +operator-sdk:gen-csv:customresourcedefinitions.displayName="Memcached App"
+type Memcached struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   MemcachedSpec   `json:"spec,omitempty"`
+	Status MemcachedStatus `json:"status,omitempty"`
+}
+```
+
+2. Set `displayName`, `path`, `x-descriptors`, and `description` on a field for a `customresourcedefinitions.specDescriptors` entry:
+
+```go
+type MemcachedSpec struct {
+	// Size is the size of the memcached deployment. <-- This will become Size's specDescriptors.description.
+	// +operator-sdk:gen-csv:customresourcedefinitions.specDescriptors=true
+	// +operator-sdk:gen-csv:customresourcedefinitions.specDescriptors.displayName="Pod Count"
+	// +operator-sdk:gen-csv:customresourcedefinitions.specDescriptors.x-descriptors="urn:alm:descriptor:com.tectonic.ui:podCount,urn:alm:descriptor:io.kubernetes:custom"
+	Size int32 `json:"size"` // <-- Size's specDescriptors.path is inferred from this JSON tag.
+}
+```
+
+3. Let the SDK infer all un-annotated paths on a field for a `customresourcedefinitions.specDescriptors` entry:
+
+```go
+type MemcachedSpec struct {
+	// Size is the size of the memcached deployment.
+	// +operator-sdk:gen-csv:customresourcedefinitions.specDescriptors=true
+	Size int32 `json:"size"`
+}
+```
+
+The SDK uses the `Size` fields' `json` tag name as `path`, `Size` as `displayName`, and field comments as `description`.
+
+The SDK also checks `path` elements against a list of well-known path to x-descriptor string mappings and either uses a match as `x-descriptors`, or does not set `x-descriptors`. Supported mappings:
+
+#### Spec x-descriptors
+
+| PATH | X-DESCRIPTOR |
+| --- | --- |
+| `size` | `urn:alm:descriptor:com.tectonic.ui:podCount` |
+| `podCount` | `urn:alm:descriptor:com.tectonic.ui:podCount` |
+| `endpoints` | `urn:alm:descriptor:com.tectonic.ui:endpointList` |
+| `endpointList` | `urn:alm:descriptor:com.tectonic.ui:endpointList` |
+| `label` | `urn:alm:descriptor:com.tectonic.ui:label` |
+| `resources` | `urn:alm:descriptor:com.tectonic.ui:resourceRequirements` |
+| `resourceRequirements` | `urn:alm:descriptor:com.tectonic.ui:resourceRequirements` |
+| `selector` | `urn:alm:descriptor:com.tectonic.ui:selector:` |
+| `namespaceSelector` | `urn:alm:descriptor:com.tectonic.ui:namespaceSelector` |
+| none | `urn:alm:descriptor:io.kubernetes:` |
+| `booleanSwitch` | `urn:alm:descriptor:com.tectonic.ui:booleanSwitch` |
+| `password` | `urn:alm:descriptor:com.tectonic.ui:password` |
+| `checkbox` | `urn:alm:descriptor:com.tectonic.ui:checkbox` |
+| `imagePullPolicy` | `urn:alm:descriptor:com.tectonic.ui:imagePullPolicy` |
+| `updateStrategy` | `urn:alm:descriptor:com.tectonic.ui:updateStrategy` |
+| `text` | `urn:alm:descriptor:com.tectonic.ui:text` |
+| `number` | `urn:alm:descriptor:com.tectonic.ui:number` |
+| `nodeAffinity` | `urn:alm:descriptor:com.tectonic.ui:nodeAffinity` |
+| `podAffinity` | `urn:alm:descriptor:com.tectonic.ui:podAffinity` |
+| `podAntiAffinity` | `urn:alm:descriptor:com.tectonic.ui:podAntiAffinity` |
+| none | `urn:alm:descriptor:com.tectonic.ui:fieldGroup:` |
+| none | `urn:alm:descriptor:com.tectonic.ui:arrayFieldGroup:` |
+| none | `urn:alm:descriptor:com.tectonic.ui:select:` |
+| `advanced` | `urn:alm:descriptor:com.tectonic.ui:advanced` |
+
+#### Status x-descriptors
+
+| PATH | X-DESCRIPTOR |
+| --- | --- |
+| `podStatuses` | `urn:alm:descriptor:com.tectonic.ui:podStatuses` |
+| `size` | `urn:alm:descriptor:com.tectonic.ui:podCount` |
+| `podCount` | `urn:alm:descriptor:com.tectonic.ui:podCount` |
+| `link` | `urn:alm:descriptor:org.w3:link` |
+| `w3link` | `urn:alm:descriptor:org.w3:link` |
+| `conditions` | `urn:alm:descriptor:io.kubernetes.conditions` |
+| `text` | `urn:alm:descriptor:text` |
+| `prometheusEndpoint` | `urn:alm:descriptor:prometheusEndpoint` |
+| `phase` | `urn:alm:descriptor:io.kubernetes.phase` |
+| `k8sPhase` | `urn:alm:descriptor:io.kubernetes.phase` |
+| `reason` | `urn:alm:descriptor:io.kubernetes.phase:reason` |
+| `k8sReason` | `urn:alm:descriptor:io.kubernetes.phase:reason` |
+| none | `urn:alm:descriptor:io.kubernetes:` |
+
+**NOTE:** any x-descriptor that ends in `:` will not be inferred by `path` element, ex. `urn:alm:descriptor:io.kubernetes:`. Use the `x-descriptors` annotation if you want to enable one for your type.
+
+4. A comprehensive example:
+- Infer `path`, `description`, `displayName`, and `x-descriptors` for `specDescriptors` and `statusDescriptors` entries.
+- Create three `resources` entries each with `kind`, `version`, and `name` values.
+
+```go
+// Represents a cluster of Memcached apps
+// +operator-sdk:gen-csv:customresourcedefinitions.displayName="Memcached App"
+// +operator-sdk:gen-csv:customresourcedefinitions.resources="Deployment,v1,\"memcached-operator\""
+// +operator-sdk:gen-csv:customresourcedefinitions.resources=`Service,v1,"memcached-operator"`
+type Memcached struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   MemcachedSpec   `json:"spec,omitempty"`
+	Status MemcachedStatus `json:"status,omitempty"`
+}
+
+type MemcachedSpec struct {
+	Pods MemcachedPods `json:"pods"`
+}
+
+type MemcachedStatus struct {
+	Pods MemcachedPods `json:"podStatuses"`
+}
+
+type MemcachedPods struct {
+	// Size is the size of the memcached deployment.
+	// +operator-sdk:gen-csv:customresourcedefinitions.specDescriptors=true
+	// +operator-sdk:gen-csv:customresourcedefinitions.statusDescriptors=true
+	Size int32 `json:"size"`
+}
+```
+
+The generated `customresourcedefinitions` will look like:
+
+```yaml
+customresourcedefinitions:
+  owned:
+  - description: Represents a cluster of Memcached apps
+    displayName: Memcached App
+    kind: Memcached
+    name: memcacheds.cache.example.com
+    version: v1alpha1
+    resources:
+    - kind: Deployment
+      name: A Kubernetes Deployment
+      version: v1
+    - kind: ReplicaSet
+      name: A Kubernetes ReplicaSet
+      version: v1beta2
+    - kind: Pod
+      name: A Kubernetes Pod
+      version: v1
+    specDescriptors:
+    - description: The desired number of member Pods for the deployment.
+      displayName: Size
+      path: pods.size
+      x-descriptors:
+      - 'urn:alm:descriptor:com.tectonic.ui:podCount'
+    statusDescriptors:
+    - description: The desired number of member Pods for the deployment.
+      displayName: Size
+      path: podStatuses.size
+      x-descriptors:
+      - 'urn:alm:descriptor:com.tectonic.ui:podStatuses'
+      - 'urn:alm:descriptor:com.tectonic.ui:podCount'
+```
+
+[code-annotations-design]:../../proposals/sdk-code-annotations.md
+[sdk-cli-ref]:../../sdk-cli-reference.md#gen-csv
+[csv-x-desc]:https://github.com/openshift/console/blob/feabd61/frontend/packages/operator-lifecycle-manager/src/components/descriptors/types.ts#L3-L39
+[csv-spec]:https://github.com/operator-framework/operator-lifecycle-manager/blob/e0eea22/doc/design/building-your-csv.md

go.mod

@@ -15,6 +15,7 @@ require (
 	github.com/elazarl/goproxy v0.0.0-20190421051319-9d40249d3c2f // indirect
 	github.com/elazarl/goproxy/ext v0.0.0-20190421051319-9d40249d3c2f // indirect
 	github.com/fatih/camelcase v1.0.0 // indirect
+	github.com/fatih/structtag v1.1.0
 	github.com/ghodss/yaml v1.0.1-0.20180820084758-c7ce16629ff4
 	github.com/go-logr/logr v0.1.0
 	github.com/go-logr/zapr v0.1.1

go.sum

@@ -153,6 +153,8 @@ github.com/fatih/camelcase v0.0.0-20160318181535-f6a740d52f96/go.mod h1:yN2Sb0lF
 github.com/fatih/camelcase v1.0.0 h1:hxNvNX/xYBp0ovncs8WyWZrOrpBNub/JfaMvbURyft8=
 github.com/fatih/camelcase v1.0.0/go.mod h1:yN2Sb0lFhZJUdVvtELVWefmrXpuZESvPmqwoZc+/fpc=
 github.com/fatih/color v1.7.0/go.mod h1:Zm6kSWBoL9eyXnKyktHP6abPY2pDugNf5KwzbycvMj4=
+github.com/fatih/structtag v1.1.0 h1:6j4mUV/ES2duvnAzKMFkN6/A5mCaNYPD3xfbAkLLOF8=
+github.com/fatih/structtag v1.1.0/go.mod h1:mBJUNpUnHmRKrKlQQlmCrh5PuhftFbNv8Ys4/aAZl94=
 github.com/fsnotify/fsnotify v1.4.7 h1:IXs+QLmnXW2CcXuY+8Mzv/fWEsPGWxqefPtCP5CnV9I=
 github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo=
 github.com/ghodss/yaml v0.0.0-20150909031657-73d445a93680/go.mod h1:4dBDuWmgqj2HViK6kFavaiC9ZROes6MMH2rRYeMEF04=

internal/annotations/prefix.go

@@ -27,8 +27,28 @@ const (
 	valueSep  = "="
 )
 
+// joinWithTrim is like strings.Join() but trims sep from each element in elems
+// prior to joining elems. Code modified from strings.Join().
+func joinWithTrim(sep string, elems ...string) string {
+	switch len(elems) {
+	case 0:
+		return ""
+	case 1:
+		return elems[0]
+	}
+	b := strings.Builder{}
+	b.WriteString(strings.Trim(elems[0], sep))
+	for _, e := range elems[1:] {
+		if e = strings.Trim(e, sep); e != "" {
+			b.WriteString(sep)
+			b.WriteString(e)
+		}
+	}
+	return b.String()
+}
+
 func JoinPrefix(tokens ...string) string {
-	return strings.Join(tokens, prefixSep)
+	return joinWithTrim(prefixSep, tokens...)
 }
 
 func SplitPrefix(prefix string) ([]string, error) {
@@ -51,7 +71,7 @@ func SplitPrefix(prefix string) ([]string, error) {
 }
 
 func JoinPath(elements ...string) string {
-	return strings.Join(elements, pathSep)
+	return joinWithTrim(pathSep, elements...)
 }
 
 func SplitPath(path string) ([]string, error) {
@@ -71,7 +91,7 @@ func SplitPath(path string) ([]string, error) {
 }
 
 func JoinAnnotation(prefixedPath, value string) string {
-	return prefixedPath + valueSep + value
+	return strings.Trim(prefixedPath, valueSep) + valueSep + strings.Trim(value, valueSep)
 }
 
 func SplitAnnotation(annotation string) (prefixedPath, val string, err error) {

internal/scaffold/olm-catalog/csv_updaters.go

@@ -20,6 +20,8 @@ import (
 	"sort"
 	"strings"
 
+	"github.com/operator-framework/operator-sdk/internal/scaffold"
+	"github.com/operator-framework/operator-sdk/internal/scaffold/olm-catalog/descriptor"
 	"github.com/operator-framework/operator-sdk/pkg/k8sutil"
 
 	"github.com/ghodss/yaml"
@@ -277,6 +279,11 @@ func (store *updaterStore) AddOwnedCRD(yamlDoc []byte) error {
 			Kind:    kind,
 		}
 		store.crds.crIDs[crdDescID(crdDesc)] = struct{}{}
+		// Parse CRD descriptors from source code comments and annotations.
+		gvk := schema.GroupVersionKind{Group: crd.Spec.Group, Version: ver, Kind: kind}
+		if err := descriptor.GetCRDDescriptorForGVK(scaffold.ApisDir, &crdDesc, gvk); err != nil {
+			return errors.Wrapf(err, "failed to set CRD descriptors for %s", gvk)
+		}
 		store.crds.Owned = append(store.crds.Owned, crdDesc)
 	}
 	return nil
@@ -317,22 +324,24 @@ func getGVKID(g, v, k string) string {
 
 // Apply updates csv's "owned" CRDDescriptions. "required" CRDDescriptions are
 // left as-is, since they are user-defined values.
-// Apply will only make a new spec.customresourcedefinitions.owned element if
-// the CRD key is not in spec.customresourcedefinitions.owned already.
+// Apply will only make a new spec.customresourcedefinitions.owned element for
+// a type if an annotation is present on that type's declaration.
 func (u *CustomResourceDefinitionsUpdate) Apply(csv *olmapiv1alpha1.ClusterServiceVersion) error {
-	set := make(map[string]olmapiv1alpha1.CRDDescription)
-	for _, csvDesc := range csv.Spec.CustomResourceDefinitions.Owned {
-		set[crdDescID(csvDesc)] = csvDesc
-	}
-	newDescs := []olmapiv1alpha1.CRDDescription{}
-	for _, uDesc := range u.Owned {
-		if csvDesc, ok := set[crdDescID(uDesc)]; !ok {
-			newDescs = append(newDescs, uDesc)
-		} else {
-			newDescs = append(newDescs, csvDesc)
+	// Currently this updater does not support ActionDescriptor annotations,
+	// so use those currently set in csv.
+	actionDescriptors := map[string][]olmapiv1alpha1.ActionDescriptor{}
+	for _, desc := range csv.Spec.CustomResourceDefinitions.Owned {
+		actionDescriptors[crdDescID(desc)] = desc.ActionDescriptor
+	}
+	// Copy owned CRDDescriptions while preserving ActionDescriptors.
+	owned := make([]olmapiv1alpha1.CRDDescription, len(u.Owned))
+	copy(owned, u.Owned)
+	csv.Spec.CustomResourceDefinitions.Owned = owned
+	for i, desc := range csv.Spec.CustomResourceDefinitions.Owned {
+		if ad, ok := actionDescriptors[crdDescID(desc)]; ok {
+			csv.Spec.CustomResourceDefinitions.Owned[i].ActionDescriptor = ad
 		}
 	}
-	csv.Spec.CustomResourceDefinitions.Owned = newDescs
 	sort.Sort(descSorter(csv.Spec.CustomResourceDefinitions.Owned))
 	sort.Sort(descSorter(csv.Spec.CustomResourceDefinitions.Required))
 	return nil