Update CRD descriptions

ref: https://issues.redhat.com/browse/ACM-8992
Signed-off-by: Dale Haiducek <19750917+dhaiducek@users.noreply.github.com>

api/v1beta1/operatorpolicy_types.go

@@ -12,28 +12,21 @@ import (
  policyv1 "open-cluster-management.io/config-policy-controller/api/v1"
 )
 
-// StatusConfigAction : StatusMessageOnly or NonCompliant
-// +kubebuilder:validation:Enum=StatusMessageOnly;NonCompliant
-type StatusConfigAction string
-
-// RemovalAction : Keep, Delete, or DeleteIfUnused
+// RemovalAction is the behavior when the operator policy is removed. The supported options are
+// `Keep`, `Delete`, or `DeleteIfUnused`.
+//
+// +kubebuilder:validation:Enum=Keep;Delete;DeleteIfUnused
 type RemovalAction string
 
 const (
- // StatusMessageOnly is a StatusConfigAction that only shows the status message
- StatusMessageOnly StatusConfigAction = "StatusMessageOnly"
- // NonCompliant is a StatusConfigAction that shows the status message and sets
- // the compliance to NonCompliant
- NonCompliant StatusConfigAction = "NonCompliant"
-)
-
-const (
- // Keep is a RemovalBehavior indicating that the controller may not delete a type
+ // Keep is a RemovalBehavior indicating that the controller may not delete a type.
  Keep RemovalAction = "Keep"
- // Delete is a RemovalBehavior indicating that the controller may delete a type
+
+ // Delete is a RemovalBehavior indicating that the controller may delete a type.
  Delete RemovalAction = "Delete"
- // DeleteIfUnused is a RemovalBehavior indicating that the controller may delete
- // a type only if is not being used by another subscription
+
+ // DeleteIfUnused is a RemovalBehavior indicating that the controller may delete a type only if it
+ // is not being used by another subscription.
  DeleteIfUnused RemovalAction = "DeleteIfUnused"
 )
 
@@ -50,32 +43,40 @@ func (ra RemovalAction) IsDeleteIfUnused() bool {
 }
 
 type RemovalBehavior struct {
+ // Use the `operatorGroups` parameter to specify whether to delete the OperatorGroup. The default
+ // value is `DeleteIfUnused`, which only deletes the OperatorGroup if there is not another
+ // resource using it.
+ //
  //+kubebuilder:default=DeleteIfUnused
  //+kubebuilder:validation:Enum=Keep;DeleteIfUnused
- // Specifies whether to delete the OperatorGroup; defaults to 'DeleteIfUnused' which
- // will only delete the OperatorGroup if there is not another resource using it.
  OperatorGroups RemovalAction `json:"operatorGroups,omitempty"`
 
+ // Use the `subscriptions` parameter to specify whether to delete the Subscription. The default
+ // value is `Delete`.
+ //
  //+kubebuilder:default=Delete
  //+kubebuilder:validation:Enum=Keep;Delete
- // Specifies whether to delete the Subscription; defaults to 'Delete'
  Subscriptions RemovalAction `json:"subscriptions,omitempty"`
 
+ // Use the `clusterServiceVersions` parameter to specify whether to delete the
+ // ClusterServiceVersion. The default value is `Delete`.
+ //
  //+kubebuilder:default=Delete
  //+kubebuilder:validation:Enum=Keep;Delete
- // Specifies whether to delete the ClusterServiceVersion; defaults to 'Delete'
  CSVs RemovalAction `json:"clusterServiceVersions,omitempty"`
 
+ // Use the customResourceDefinitions parameter to specify whether to delete any
+ // CustomResourceDefinitions associated with the operator. The default value is `Keep`, because
+ // deleting them should be done deliberately.
+ //
  //+kubebuilder:default=Keep
  //+kubebuilder:validation:Enum=Keep;Delete
- // Specifies whether to delete any CustomResourceDefinitions associated with the operator;
- // defaults to 'Keep' because deleting them should be done deliberately
  CRDs RemovalAction `json:"customResourceDefinitions,omitempty"`
 }
 
-// ApplyDefaults ensures that unset fields in a RemovalBehavior behave as if they were
-// set to the default values. In a cluster, kubernetes API validation should ensure that
-// there are no unset values, and should apply the default values itself.
+// ApplyDefaults ensures that unset fields in a RemovalBehavior behave as if they were set to the
+// default values. In a cluster, Kubernetes API validation should ensure that there are no unset
+// values and should apply the default values itself.
 func (rb RemovalBehavior) ApplyDefaults() RemovalBehavior {
  withDefaults := *rb.DeepCopy()
 
@@ -98,54 +99,89 @@ func (rb RemovalBehavior) ApplyDefaults() RemovalBehavior {
  return withDefaults
 }
 
-// StatusConfig defines how resource statuses affect the OperatorPolicy status and compliance
+// StatusConfigAction configures how a status condition is reported when the involved operators are
+// out of compliance with the operator policy. Options are `StatusMessageOnly` or `NonCompliant`.
+//
+// +kubebuilder:validation:Enum=StatusMessageOnly;NonCompliant
+type StatusConfigAction string
+
+const (
+ // StatusMessageOnly is a StatusConfigAction that only shows the status message.
+ StatusMessageOnly StatusConfigAction = "StatusMessageOnly"
+
+ // NonCompliant is a StatusConfigAction that shows the status message and sets the compliance to
+ // NonCompliant.
+ NonCompliant StatusConfigAction = "NonCompliant"
+)
+
+// StatusConfig defines how resource statuses affect the overall operator policy status and
+// compliance.
 type StatusConfig struct {
+ // CatalogSourcesUnhealthy defines how the CatalogSourcesUnhealthy condition affects the operator
+ // policy status.
  CatalogSourceUnhealthy StatusConfigAction `json:"catalogSourceUnhealthy,omitempty"`
+
+ // DeploymentsUnavailable defines how the DeploymentsUnavailable condition affects the operator
+ // policy status.
  DeploymentsUnavailable StatusConfigAction `json:"deploymentsUnavailable,omitempty"`
- UpgradesAvailable StatusConfigAction `json:"upgradesAvailable,omitempty"`
- UpgradesProgressing StatusConfigAction `json:"upgradesProgressing,omitempty"`
+
+ // UpgradesAvailable defines how the UpgradesAvailable condition affects the operator policy
+ // status.
+ UpgradesAvailable StatusConfigAction `json:"upgradesAvailable,omitempty"`
+
+ // UpgradesProgressing defines how the UpgradesProgressing condition affects the operator policy
+ // status.
+ UpgradesProgressing StatusConfigAction `json:"upgradesProgressing,omitempty"`
 }
 
-// OperatorPolicySpec defines the desired state of OperatorPolicy
+// OperatorPolicySpec defines the desired state of a particular operator on the cluster.
 type OperatorPolicySpec struct {
- Severity policyv1.Severity `json:"severity,omitempty"` // low, medium, high
- RemediationAction policyv1.RemediationAction `json:"remediationAction,omitempty"` // inform, enforce
- ComplianceType policyv1.ComplianceType `json:"complianceType"` // musthave, mustnothave
-
- // Include the name, namespace, and any `spec` fields for the OperatorGroup.
- // For more info, see `kubectl explain operatorgroup.spec` or
- // https://olm.operatorframework.io/docs/concepts/crds/operatorgroup/
+ Severity policyv1.Severity `json:"severity,omitempty"`
+ RemediationAction policyv1.RemediationAction `json:"remediationAction,omitempty"`
+ ComplianceType policyv1.ComplianceType `json:"complianceType"`
+
+ // OperatorGroup specifies which `OperatorGroup` to inspect. Include the name, namespace, and any
+ // `spec` fields for the operator group. For more info, see `kubectl explain operatorgroups.spec`
+ // or view https://olm.operatorframework.io/docs/concepts/crds/operatorgroup/.
+ //
  // +kubebuilder:pruning:PreserveUnknownFields
  // +optional
  OperatorGroup *runtime.RawExtension `json:"operatorGroup,omitempty"`
 
- // Include the namespace, and any `spec` fields for the Subscription.
- // For more info, see `kubectl explain subscription.spec` or
- // https://olm.operatorframework.io/docs/concepts/crds/subscription/
- // +kubebuilder:validation:Required
+ // Subscription specifies which operator `Subscription` resource to inspect. Include the
+ // namespace, and any `spec` fields for the Subscription. For more info, see `kubectl explain
+ // subscriptions.operators.coreos.com.spec` or view
+ // https://olm.operatorframework.io/docs/concepts/crds/subscription/.
+ //
  // +kubebuilder:pruning:PreserveUnknownFields
  Subscription runtime.RawExtension `json:"subscription"`
 
- // Versions is a list of nonempty strings that specifies which installed versions are compliant when
- // in 'inform' mode, and which installPlans are approved when in 'enforce' mode
+ // Versions is a list of non-empty strings that specifies which installed versions are compliant
+ // when in `inform` mode and which `InstallPlans` are approved when in `enforce` mode.
  Versions []policyv1.NonEmptyString `json:"versions,omitempty"`
 
+ // Use RemovalBehavior to define what resources need to be removed when enforcing `mustnothave`
+ // policies. When in `inform` mode, any resources that are deleted if the policy is set to
+ // `enforce` makes the policy noncompliant, but resources that are kept are compliant.
+ //
  //+kubebuilder:default={}
- // RemovalBehavior defines what resources will be removed by enforced mustnothave policies.
- // When in inform mode, any resources that would be deleted if the policy was enforced will
- // be causes for NonCompliance, but resources that would be kept will be considered Compliant.
  RemovalBehavior RemovalBehavior `json:"removalBehavior,omitempty"`
 }
 
-// OperatorPolicyStatus defines the observed state of OperatorPolicy
+// OperatorPolicyStatus is the observed state of the operators from the specifications given in the
+// operator policy.
 type OperatorPolicyStatus struct {
- // Most recent compliance state of the policy
+ // ComplianceState reports the most recent compliance state of the operator policy.
  ComplianceState policyv1.ComplianceState `json:"compliant,omitempty"`
- // Historic details on the condition of the policy
+
+ // Conditions includes historic details on the condition of the operator policy.
+ //
  // +listType=map
  // +listMapKey=type
  Conditions []metav1.Condition `json:"conditions,omitempty"`
- // List of resources processed by the policy
+
+ // RelatedObjects reports a list of resources associated with the operator policy.
+ //
  // +optional
  RelatedObjects []policyv1.RelatedObject `json:"relatedObjects"`
 
@@ -157,6 +193,8 @@ type OperatorPolicyStatus struct {
  OverlappingPolicies []string `json:"overlappingPolicies,omitempty"`
 }
 
+// RelatedObjsOfKind iterates over the related objects in the status and returns a map of the index
+// in the array to the related object that has the given kind.
 func (status OperatorPolicyStatus) RelatedObjsOfKind(kind string) map[int]policyv1.RelatedObject {
  objs := make(map[int]policyv1.RelatedObject)
 
@@ -169,9 +207,9 @@ func (status OperatorPolicyStatus) RelatedObjsOfKind(kind string) map[int]policy
  return objs
 }
 
-// Searches the conditions of the policy, and returns the index and condition matching the
-// given condition Type. It will return -1 as the index if no condition of the specified
-// Type is found.
+// GetCondition iterates over the status conditions of the policy and returns the index and
+// condition matching the given condition Type. It will return -1 as the index if no condition of
+// the specified Type is found.
 func (status OperatorPolicyStatus) GetCondition(condType string) (int, metav1.Condition) {
  for i, cond := range status.Conditions {
  if cond.Type == condType {
@@ -182,10 +220,12 @@ func (status OperatorPolicyStatus) GetCondition(condType string) (int, metav1.Co
  return -1, metav1.Condition{}
 }
 
-//+kubebuilder:object:root=true
-//+kubebuilder:subresource:status
-
-// OperatorPolicy is the Schema for the operatorpolicies API
+// OperatorPolicy is the schema for the operatorpolicies API. You can use the operator policy to
+// manage operators by providing automation for their management and reporting on the status across
+// the various operator objects.
+//
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
 type OperatorPolicy struct {
  metav1.TypeMeta `json:",inline"`
  metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -194,9 +234,9 @@ type OperatorPolicy struct {
  Status OperatorPolicyStatus `json:"status,omitempty"`
 }
 
-//+kubebuilder:object:root=true
-
-// OperatorPolicyList contains a list of OperatorPolicy
+// OperatorPolicyList contains a list of operator policies.
+//
+// +kubebuilder:object:root=true
 type OperatorPolicyList struct {
  metav1.TypeMeta `json:",inline"`
  metav1.ListMeta `json:"metadata,omitempty"`