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

@@ -10,100 +10,129 @@ 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. 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 is
+ // not being used by another subscription.
  DeleteIfUnused RemovalAction = "DeleteIfUnused"
 )
 
-// RemovalBehavior defines resource behavior when policy is removed
+// RemovalBehavior defines resource behavior when the operator policy is removed.
 type RemovalBehavior struct {
- // Kind OperatorGroup
+ // OperatorGroups is the removal action for kind OperatorGroup.
  OperatorGroups RemovalAction `json:"operatorGroups,omitempty"`
- // Kind Subscription
+
+ // Subscriptions is the removal action for kind Subscription.
  Subscriptions RemovalAction `json:"subscriptions,omitempty"`
- // Kind ClusterServiceVersion
+
+ // CSVs is the removal action for kind ClusterServiceVersion.
  CSVs RemovalAction `json:"clusterServiceVersions,omitempty"`
- // Kind InstallPlan
+
+ // InstallPlan is the removal action for kind InstallPlan.
  InstallPlan RemovalAction `json:"installPlans,omitempty"`
- // Kind CustomResourceDefinitions
+
+ // CRDs is the removal action for kind CustomResourceDefinition.
  CRDs RemovalAction `json:"customResourceDefinitions,omitempty"`
- // Kind APIServiceDefinitions
+
+ // APIServiceDefinitions is the removal action for kind APIServices that have been defined in the
+ // associated ClusterServiceVersion.
  APIServiceDefinitions RemovalAction `json:"apiServiceDefinitions,omitempty"`
 }
 
-// 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
-
- // 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 the OperatorGroup to be handled. Include the name, namespace, and any
+ // `spec` fields for the OperatorGroup. 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
+ // Subscription specifies the operator Subscription to be handled. 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:validation:Required
+ //
  // +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 nonempty 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"`
-
- // FUTURE
- //nolint:dupword
- // RemovalBehavior RemovalBehavior `json:"removalBehavior,omitempty"`
- //nolint:dupword
- // StatusConfig StatusConfig `json:"statusConfig,omitempty"`
 }
 
-// OperatorPolicyStatus defines the observed state of OperatorPolicy
+// OperatorPolicyStatus reports the observed state of the operators resulting 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 reports 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"`
 }
 
+// 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)
 
@@ -116,9 +145,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 {
@@ -129,10 +158,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. Operator policy eases the management
+// of OLM 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"`
@@ -141,9 +172,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"`