fix(crd): fix OLM descriptors and documentation (#260) (#264)

* fix(crd): fix OLM descriptors and documentation * Rename Event Options to Event Template in OLM UI * Add patch (cherry picked from commit ecf0b5c) Co-authored-by: Elliott Baron <ebaron@redhat.com>
cryostatio · Sep 17, 2021 · 12ff784 · 12ff784
1 parent 9e89e39
commit 12ff784
Show file tree

Hide file tree

Showing 13 changed files with 77 additions and 48 deletions.
diff --git a/api/v1beta1/cryostat_types.go b/api/v1beta1/cryostat_types.go
@@ -146,7 +146,9 @@ type PersistentVolumeClaimConfig struct {
 // +kubebuilder:storageversion
 // +kubebuilder:resource:path=cryostats,scope=Namespaced
 
-// Cryostat is the Schema for the cryostats API
+// Cryostat contains configuration options for controlling the Deployment of
+// the Cryostat application and its related components. A Cryostat instance
+// must be created to instruct the operator to deploy the Cryostat application.
 //+operator-sdk:csv:customresourcedefinitions:resources={{Deployment,v1},{Ingress,v1},{PersistentVolumeClaim,v1},{Secret,v1},{Service,v1},{Route,v1},{ConsoleLink,v1}}
 type Cryostat struct {
 	metav1.TypeMeta   `json:",inline"`

diff --git a/api/v1beta1/flightrecorder_types.go b/api/v1beta1/flightrecorder_types.go
@@ -153,7 +153,9 @@ type JMXAuthSecret struct {
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 
-// FlightRecorder is the Schema for the flightrecorders API
+// FlightRecorder represents a target Pod that is capable of creating JDK Flight Recordings
+// using Cryostat. The Cryostat operator creates FlightRecorder objects when it finds
+// compatible Pods.
 //+operator-sdk:csv:customresourcedefinitions:resources={{Pod,v1},{Secret,v1},{Service,v1}}
 type FlightRecorder struct {
 	metav1.TypeMeta   `json:",inline"`

diff --git a/api/v1beta1/recording_types.go b/api/v1beta1/recording_types.go
@@ -46,28 +46,26 @@ type RecordingSpec struct {
 	// Name of the recording to be created.
 	// +operator-sdk:csv:customresourcedefinitions:type=spec
 	Name string `json:"name"`
-	// TODO Maybe replace with more specific type (e.g. "typeID, option, value" tuples)
-
-	// A list of event options to use when creating the recording.
-	// These are used to enable and fine-tune individual events.
-	// Examples: "jdk.ExecutionSample:enabled=true", "jdk.ExecutionSample:period=200ms"
-	// +operator-sdk:csv:customresourcedefinitions:type=spec,xDescriptors={"urn:alm:descriptor:com.tectonic.ui:text"}
+	// Name of the event template to use when creating the recording. Must be prefixed with "template=".
+	// e.g. template=Profiling
+	// +operator-sdk:csv:customresourcedefinitions:type=spec,displayName="Event Template",xDescriptors={"urn:alm:descriptor:com.tectonic.ui:text"}
 	// +listType=atomic
 	EventOptions []string `json:"eventOptions"`
 	// The requested total duration of the recording, a zero value will record indefinitely.
-	// +operator-sdk:csv:customresourcedefinitions:type=spec,xDescriptors={"urn:alm:descriptor:com.tectonic.ui:number"}
+	// The duration format is a combination of hours (h), minutes (m) and seconds (s). e.g. 30s, 0s, 1h30m
+	// +operator-sdk:csv:customresourcedefinitions:type=spec,xDescriptors={"urn:alm:descriptor:com.tectonic.ui:text"}
 	Duration metav1.Duration `json:"duration"`
 	// Desired state of the recording. If omitted, RUNNING will be assumed.
 	// +kubebuilder:validation:Enum=RUNNING;STOPPED
 	// +operator-sdk:csv:customresourcedefinitions:type=spec,xDescriptors={"urn:alm:descriptor:com.tectonic.ui:select:RUNNING","urn:alm:descriptor:com.tectonic.ui:select:STOPPED"}
-
 	// +optional
 	State *RecordingState `json:"state,omitempty"`
 	// Whether this recording should be saved to persistent storage. If true, the JFR file will be retained until
 	// this object is deleted. If false, the JFR file will be deleted when its corresponding JVM exits.
 	// +operator-sdk:csv:customresourcedefinitions:type=spec,xDescriptors={"urn:alm:descriptor:com.tectonic.ui:checkbox"}
 	Archive bool `json:"archive"`
-	// Reference to the FlightRecorder object that corresponds to this Recording
+	// Reference to the FlightRecorder object that corresponds to this Recording. Select the FlightRecorder
+	// with the name of the target Pod for this Recording.
 	// +operator-sdk:csv:customresourcedefinitions:type=spec
 	FlightRecorder *corev1.LocalObjectReference `json:"flightRecorder"`
 }
@@ -123,7 +121,8 @@ type RecordingStatus struct {
 // +kubebuilder:storageversion
 // +kubebuilder:resource:path=recordings,scope=Namespaced
 
-// Recording is the Schema for the recordings API
+// Recording represents a JDK Flight Recording. Create a Recording object to instruct Cryostat to start a new
+// recording for a Pod. An alternative to managing recordings with the Cryostat web application.
 //+operator-sdk:csv:customresourcedefinitions:resources={{Pod,v1},{Secret,v1},{Service,v1}}
 type Recording struct {
 	metav1.TypeMeta   `json:",inline"`

diff --git a/bundle/manifests/cryostat-operator.clusterserviceversion.yaml b/bundle/manifests/cryostat-operator.clusterserviceversion.yaml
@@ -72,7 +72,7 @@ spec:
   apiservicedefinitions: {}
   customresourcedefinitions:
     owned:
-    - description: Cryostat is the Schema for the cryostats API
+    - description: Cryostat contains configuration options for controlling the Deployment of the Cryostat application and its related components. A Cryostat instance must be created to instruct the operator to deploy the Cryostat application.
       displayName: Cryostat
       kind: Cryostat
       name: cryostats.operator.cryostat.io
@@ -140,7 +140,7 @@ spec:
         x-descriptors:
         - urn:alm:descriptor:org.w3:link
       version: v1beta1
-    - description: FlightRecorder is the Schema for the flightrecorders API
+    - description: FlightRecorder represents a target Pod that is capable of creating JDK Flight Recordings using Cryostat. The Cryostat operator creates FlightRecorder objects when it finds compatible Pods.
       displayName: Flight Recorder
       kind: FlightRecorder
       name: flightrecorders.operator.cryostat.io
@@ -177,7 +177,7 @@ spec:
         displayName: Templates
         path: templates
       version: v1beta1
-    - description: Recording is the Schema for the recordings API
+    - description: Recording represents a JDK Flight Recording. Create a Recording object to instruct Cryostat to start a new recording for a Pod. An alternative to managing recordings with the Cryostat web application.
       displayName: Recording
       kind: Recording
       name: recordings.operator.cryostat.io
@@ -197,23 +197,26 @@ spec:
         path: archive
         x-descriptors:
         - urn:alm:descriptor:com.tectonic.ui:checkbox
-      - description: The requested total duration of the recording, a zero value will record indefinitely.
+      - description: The requested total duration of the recording, a zero value will record indefinitely. The duration format is a combination of hours (h), minutes (m) and seconds (s). e.g. 30s, 0s, 1h30m
         displayName: Duration
         path: duration
         x-descriptors:
-        - urn:alm:descriptor:com.tectonic.ui:number
-      - description: 'A list of event options to use when creating the recording. These are used to enable and fine-tune individual events. Examples: "jdk.ExecutionSample:enabled=true", "jdk.ExecutionSample:period=200ms"'
-        displayName: Event Options
+        - urn:alm:descriptor:com.tectonic.ui:text
+      - description: Name of the event template to use when creating the recording. Must be prefixed with "template=". e.g. template=Profiling
+        displayName: Event Template
         path: eventOptions
         x-descriptors:
         - urn:alm:descriptor:com.tectonic.ui:text
-      - description: Reference to the FlightRecorder object that corresponds to this Recording
+      - description: Reference to the FlightRecorder object that corresponds to this Recording. Select the FlightRecorder with the name of the target Pod for this Recording.
         displayName: Flight Recorder
-        path: flightRecorder
+        path: flightRecorder.name
+        x-descriptors:
+        - urn:alm:descriptor:io.kubernetes:operator.cryostat.io:v1beta1:FlightRecorder
       - description: Name of the recording to be created.
         displayName: Name
         path: name
-      - displayName: State
+      - description: Desired state of the recording. If omitted, RUNNING will be assumed.
+        displayName: State
         path: state
         x-descriptors:
         - urn:alm:descriptor:com.tectonic.ui:select:RUNNING

diff --git a/bundle/manifests/operator.cryostat.io_cryostats.yaml b/bundle/manifests/operator.cryostat.io_cryostats.yaml
@@ -17,7 +17,7 @@ spec:
   - name: v1beta1
     schema:
       openAPIV3Schema:
-        description: Cryostat is the Schema for the cryostats API
+        description: Cryostat contains configuration options for controlling the Deployment of the Cryostat application and its related components. A Cryostat instance must be created to instruct the operator to deploy the Cryostat application.
         properties:
           apiVersion:
             description: 'APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'

diff --git a/bundle/manifests/operator.cryostat.io_flightrecorders.yaml b/bundle/manifests/operator.cryostat.io_flightrecorders.yaml
@@ -17,7 +17,7 @@ spec:
   - name: v1beta1
     schema:
       openAPIV3Schema:
-        description: FlightRecorder is the Schema for the flightrecorders API
+        description: FlightRecorder represents a target Pod that is capable of creating JDK Flight Recordings using Cryostat. The Cryostat operator creates FlightRecorder objects when it finds compatible Pods.
         properties:
           apiVersion:
             description: 'APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'

diff --git a/bundle/manifests/operator.cryostat.io_recordings.yaml b/bundle/manifests/operator.cryostat.io_recordings.yaml
@@ -17,7 +17,7 @@ spec:
   - name: v1beta1
     schema:
       openAPIV3Schema:
-        description: Recording is the Schema for the recordings API
+        description: Recording represents a JDK Flight Recording. Create a Recording object to instruct Cryostat to start a new recording for a Pod. An alternative to managing recordings with the Cryostat web application.
         properties:
           apiVersion:
             description: 'APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'
@@ -34,16 +34,16 @@ spec:
                 description: Whether this recording should be saved to persistent storage. If true, the JFR file will be retained until this object is deleted. If false, the JFR file will be deleted when its corresponding JVM exits.
                 type: boolean
               duration:
-                description: The requested total duration of the recording, a zero value will record indefinitely.
+                description: The requested total duration of the recording, a zero value will record indefinitely. The duration format is a combination of hours (h), minutes (m) and seconds (s). e.g. 30s, 0s, 1h30m
                 type: string
               eventOptions:
-                description: 'A list of event options to use when creating the recording. These are used to enable and fine-tune individual events. Examples: "jdk.ExecutionSample:enabled=true", "jdk.ExecutionSample:period=200ms"'
+                description: Name of the event template to use when creating the recording. Must be prefixed with "template=". e.g. template=Profiling
                 items:
                   type: string
                 type: array
                 x-kubernetes-list-type: atomic
               flightRecorder:
-                description: Reference to the FlightRecorder object that corresponds to this Recording
+                description: Reference to the FlightRecorder object that corresponds to this Recording. Select the FlightRecorder with the name of the target Pod for this Recording.
                 properties:
                   name:
                     description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid?'
@@ -53,7 +53,7 @@ spec:
                 description: Name of the recording to be created.
                 type: string
               state:
-                description: RecordingState describes the current state of the recording according to JFR
+                description: Desired state of the recording. If omitted, RUNNING will be assumed.
                 enum:
                 - RUNNING
                 - STOPPED

diff --git a/config/crd/bases/operator.cryostat.io_cryostats.yaml b/config/crd/bases/operator.cryostat.io_cryostats.yaml
@@ -19,7 +19,9 @@ spec:
   - name: v1beta1
     schema:
       openAPIV3Schema:
-        description: Cryostat is the Schema for the cryostats API
+        description: Cryostat contains configuration options for controlling the Deployment
+          of the Cryostat application and its related components. A Cryostat instance
+          must be created to instruct the operator to deploy the Cryostat application.
         properties:
           apiVersion:
             description: 'APIVersion defines the versioned schema of this representation

diff --git a/config/crd/bases/operator.cryostat.io_flightrecorders.yaml b/config/crd/bases/operator.cryostat.io_flightrecorders.yaml
@@ -19,7 +19,9 @@ spec:
   - name: v1beta1
     schema:
       openAPIV3Schema:
-        description: FlightRecorder is the Schema for the flightrecorders API
+        description: FlightRecorder represents a target Pod that is capable of creating
+          JDK Flight Recordings using Cryostat. The Cryostat operator creates FlightRecorder
+          objects when it finds compatible Pods.
         properties:
           apiVersion:
             description: 'APIVersion defines the versioned schema of this representation

diff --git a/config/crd/bases/operator.cryostat.io_recordings.yaml b/config/crd/bases/operator.cryostat.io_recordings.yaml
@@ -19,7 +19,9 @@ spec:
   - name: v1beta1
     schema:
       openAPIV3Schema:
-        description: Recording is the Schema for the recordings API
+        description: Recording represents a JDK Flight Recording. Create a Recording
+          object to instruct Cryostat to start a new recording for a Pod. An alternative
+          to managing recordings with the Cryostat web application.
         properties:
           apiVersion:
             description: 'APIVersion defines the versioned schema of this representation
@@ -44,19 +46,20 @@ spec:
                 type: boolean
               duration:
                 description: The requested total duration of the recording, a zero
-                  value will record indefinitely.
+                  value will record indefinitely. The duration format is a combination
+                  of hours (h), minutes (m) and seconds (s). e.g. 30s, 0s, 1h30m
                 type: string
               eventOptions:
-                description: 'A list of event options to use when creating the recording.
-                  These are used to enable and fine-tune individual events. Examples:
-                  "jdk.ExecutionSample:enabled=true", "jdk.ExecutionSample:period=200ms"'
+                description: Name of the event template to use when creating the recording.
+                  Must be prefixed with "template=". e.g. template=Profiling
                 items:
                   type: string
                 type: array
                 x-kubernetes-list-type: atomic
               flightRecorder:
                 description: Reference to the FlightRecorder object that corresponds
-                  to this Recording
+                  to this Recording. Select the FlightRecorder with the name of the
+                  target Pod for this Recording.
                 properties:
                   name:
                     description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
@@ -67,8 +70,8 @@ spec:
                 description: Name of the recording to be created.
                 type: string
               state:
-                description: RecordingState describes the current state of the recording
-                  according to JFR
+                description: Desired state of the recording. If omitted, RUNNING will
+                  be assumed.
                 enum:
                 - RUNNING
                 - STOPPED

diff --git a/config/manifests/bases/cryostat-operator.clusterserviceversion.yaml b/config/manifests/bases/cryostat-operator.clusterserviceversion.yaml
@@ -63,7 +63,7 @@ spec:
   apiservicedefinitions: {}
   customresourcedefinitions:
     owned:
-    - description: Cryostat is the Schema for the cryostats API
+    - description: Cryostat contains configuration options for controlling the Deployment of the Cryostat application and its related components. A Cryostat instance must be created to instruct the operator to deploy the Cryostat application.
       displayName: Cryostat
       kind: Cryostat
       name: cryostats.operator.cryostat.io
@@ -131,7 +131,7 @@ spec:
         x-descriptors:
         - urn:alm:descriptor:org.w3:link
       version: v1beta1
-    - description: FlightRecorder is the Schema for the flightrecorders API
+    - description: FlightRecorder represents a target Pod that is capable of creating JDK Flight Recordings using Cryostat. The Cryostat operator creates FlightRecorder objects when it finds compatible Pods.
       displayName: Flight Recorder
       kind: FlightRecorder
       name: flightrecorders.operator.cryostat.io
@@ -168,7 +168,7 @@ spec:
         displayName: Templates
         path: templates
       version: v1beta1
-    - description: Recording is the Schema for the recordings API
+    - description: Recording represents a JDK Flight Recording. Create a Recording object to instruct Cryostat to start a new recording for a Pod. An alternative to managing recordings with the Cryostat web application.
       displayName: Recording
       kind: Recording
       name: recordings.operator.cryostat.io
@@ -188,23 +188,24 @@ spec:
         path: archive
         x-descriptors:
         - urn:alm:descriptor:com.tectonic.ui:checkbox
-      - description: The requested total duration of the recording, a zero value will record indefinitely.
+      - description: The requested total duration of the recording, a zero value will record indefinitely. The duration format is a combination of hours (h), minutes (m) and seconds (s). e.g. 30s, 0s, 1h30m
         displayName: Duration
         path: duration
         x-descriptors:
-        - urn:alm:descriptor:com.tectonic.ui:number
-      - description: 'A list of event options to use when creating the recording. These are used to enable and fine-tune individual events. Examples: "jdk.ExecutionSample:enabled=true", "jdk.ExecutionSample:period=200ms"'
-        displayName: Event Options
+        - urn:alm:descriptor:com.tectonic.ui:text
+      - description: Name of the event template to use when creating the recording. Must be prefixed with "template=". e.g. template=Profiling
+        displayName: Event Template
         path: eventOptions
         x-descriptors:
         - urn:alm:descriptor:com.tectonic.ui:text
-      - description: Reference to the FlightRecorder object that corresponds to this Recording
+      - description: Reference to the FlightRecorder object that corresponds to this Recording. Select the FlightRecorder with the name of the target Pod for this Recording.
         displayName: Flight Recorder
         path: flightRecorder
       - description: Name of the recording to be created.
         displayName: Name
         path: name
-      - displayName: State
+      - description: Desired state of the recording. If omitted, RUNNING will be assumed.
+        displayName: State
         path: state
         x-descriptors:
         - urn:alm:descriptor:com.tectonic.ui:select:RUNNING

diff --git a/config/manifests/kustomization.yaml b/config/manifests/kustomization.yaml
@@ -1,4 +1,13 @@
 resources:
+- bases/cryostat-operator.clusterserviceversion.yaml
 - ../default
 - ../samples
 - ../scorecard
+
+patches:
+- path: xdescriptors_patch.yaml
+  target:
+    group: operators.coreos.com
+    version: v1alpha1
+    kind: ClusterServiceVersion
+    name: cryostat-operator.v0.0.0
diff --git a/config/manifests/xdescriptors_patch.yaml b/config/manifests/xdescriptors_patch.yaml
@@ -0,0 +1,6 @@
+- op: replace
+  path: /spec/customresourcedefinitions/owned/2/specDescriptors/3/path
+  value: flightRecorder.name
+- op: add
+  path: /spec/customresourcedefinitions/owned/2/specDescriptors/3/x-descriptors
+  value: [ "urn:alm:descriptor:io.kubernetes:operator.cryostat.io:v1beta1:FlightRecorder" ]