From 215536545def6eff9c6c82b15319385f6126d2b4 Mon Sep 17 00:00:00 2001 From: Dale Haiducek <19750917+dhaiducek@users.noreply.github.com> Date: Wed, 20 Mar 2024 09:48:28 -0400 Subject: [PATCH] Update CRD descriptions ref: https://issues.redhat.com/browse/ACM-8992 Signed-off-by: Dale Haiducek <19750917+dhaiducek@users.noreply.github.com> --- api/v1/configurationpolicy_types.go | 432 ++++++++++-------- api/v1/zz_generated.deepcopy.go | 65 +-- api/v1beta1/operatorpolicy_types.go | 151 +++--- ...r-management.io_configurationpolicies.yaml | 204 +++++---- ...luster-management.io_operatorpolicies.yaml | 96 ++-- ...r-management.io_configurationpolicies.yaml | 204 +++++---- ...luster-management.io_operatorpolicies.yaml | 96 ++-- 7 files changed, 696 insertions(+), 552 deletions(-) diff --git a/api/v1/configurationpolicy_types.go b/api/v1/configurationpolicy_types.go index 9411ab40..cf7c417a 100644 --- a/api/v1/configurationpolicy_types.go +++ b/api/v1/configurationpolicy_types.go @@ -15,31 +15,18 @@ import ( "sigs.k8s.io/controller-runtime/pkg/client" ) -// A custom type is required since there is no way to have a kubebuilder marker -// apply to the items of a slice. - // +kubebuilder:validation:MinLength=1 type NonEmptyString string -// RemediationAction : enforce or inform +// RemediationAction specifies the remediation of the policy. The parameter values are enforce and +// inform. +// // +kubebuilder:validation:Enum=Inform;inform;Enforce;enforce type RemediationAction string -// Severity : low, medium, high, or critical -// +kubebuilder:validation:Enum=low;Low;medium;Medium;high;High;critical;Critical -type Severity string - -// PruneObjectBehavior is used to remove objects that are managed by the -// policy upon policy deletion. -// +kubebuilder:validation:Enum=DeleteAll;DeleteIfCreated;None; -type PruneObjectBehavior string - const ( - // Enforce is an remediationAction to make changes Enforce RemediationAction = "Enforce" - - // Inform is an remediationAction to only inform - Inform RemediationAction = "Inform" + Inform RemediationAction = "Inform" ) func (ra RemediationAction) IsInform() bool { @@ -50,48 +37,29 @@ func (ra RemediationAction) IsEnforce() bool { return strings.EqualFold(string(ra), string(Enforce)) } -// ComplianceState shows the state of enforcement -type ComplianceState string - -const ( - // Compliant is an ComplianceState - Compliant ComplianceState = "Compliant" - - // NonCompliant is an ComplianceState - NonCompliant ComplianceState = "NonCompliant" - - // UnknownCompliancy is an ComplianceState - UnknownCompliancy ComplianceState = "UnknownCompliancy" - - // Terminating is a ComplianceState - Terminating ComplianceState = "Terminating" -) +// Severity is a user-defined severity for when an object is found out of compliance with this +// configuration policy. Accepted values are low, medium, high, and critical. +// +// +kubebuilder:validation:Enum=low;Low;medium;Medium;high;High;critical;Critical +type Severity string -// Condition is the base struct for representing resource conditions -type Condition struct { - // Type of condition, e.g Complete or Failed. - Type string `json:"type"` - // Status of the condition, one of True, False, Unknown. - Status corev1.ConditionStatus `json:"status,omitempty" protobuf:"bytes,12,rep,name=status"` - // The last time the condition transitioned from one status to another. - // +optional - LastTransitionTime metav1.Time `json:"lastTransitionTime,omitempty" protobuf:"bytes,3,opt,name=lastTransitionTime"` - // The reason for the condition's last transition. - // +optional - Reason string `json:"reason,omitempty" protobuf:"bytes,4,opt,name=reason"` - // A human readable message indicating details about the transition. - // +optional - Message string `json:"message,omitempty" protobuf:"bytes,5,opt,name=message"` -} +// PruneObjectBehavior is used to remove objects that are managed by the policy upon policy +// deletion. +// +// +kubebuilder:validation:Enum=DeleteAll;DeleteIfCreated;None; +type PruneObjectBehavior string type Target struct { - // 'include' is an array of filepath expressions to include objects by name. + // Include is an array of filepath expressions to include objects by name. Include []NonEmptyString `json:"include,omitempty"` - // 'exclude' is an array of filepath expressions to exclude objects by name. + + // Exclude is an array of filepath expressions to exclude objects by name. Exclude []NonEmptyString `json:"exclude,omitempty"` - // 'matchLabels' is a map of {key,value} pairs matching objects by label. + + // MatchLabels is a map of {key,value} pairs matching objects by label. MatchLabels *map[string]string `json:"matchLabels,omitempty"` - // 'matchExpressions' is an array of label selector requirements matching objects by label. + + // MatchExpressions is an array of label selector requirements matching objects by label. MatchExpressions *[]metav1.LabelSelectorRequirement `json:"matchExpressions,omitempty"` } @@ -113,24 +81,27 @@ func (t Target) String() string { return fmt.Sprintf(fmtSelectorStr, t.Include, t.Exclude, *t.MatchLabels, *t.MatchExpressions) } -// Configures the minimum elapsed time before a ConfigurationPolicy is reevaluated. If the policy -// spec is changed, or if the list of namespaces selected by the policy changes, the policy may be -// evaluated regardless of the settings here. +// EvaluationInterval configures the minimum elapsed time before a configuration policy is +// reevaluated. If the policy spec is changed, or if the list of namespaces selected by the policy +// changes, the policy may be evaluated regardless of the settings here. type EvaluationInterval struct { + // Compliant is the minimum elapsed time before a configuration policy is reevaluated when in the + // compliant state. Set this to "never" to disable reevaluation when in the compliant state. + // //+kubebuilder:validation:Pattern=`^(?:(?:(?:[0-9]+(?:.[0-9])?)(?:h|m|s|(?:ms)|(?:us)|(?:ns)))|never)+$` - // The minimum elapsed time before a ConfigurationPolicy is reevaluated when in the compliant state. Set this to - // "never" to disable reevaluation when in the compliant state. Compliant string `json:"compliant,omitempty"` + // NonCompliant is the minimum elapsed time before a configuration policy is reevaluated when in + // the noncompliant state. Set this to "never" to disable reevaluation when in the noncompliant + // state. + // //+kubebuilder:validation:Pattern=`^(?:(?:(?:[0-9]+(?:.[0-9])?)(?:h|m|s|(?:ms)|(?:us)|(?:ns)))|never)+$` - // The minimum elapsed time before a ConfigurationPolicy is reevaluated when in the noncompliant state. Set this to - // "never" to disable reevaluation when in the noncompliant state. NonCompliant string `json:"noncompliant,omitempty"` } var ErrIsNever = errors.New("the interval is set to never") -// parseInterval converts the input string to a duration. The default value is 0s. ErrIsNever is returned when the -// string is set to "never". +// parseInterval converts the input string to a duration. The default value is 0s. ErrIsNever is +// returned when the string is set to "never". func (e EvaluationInterval) parseInterval(interval string) (time.Duration, error) { if interval == "" { return 0, nil @@ -148,61 +119,54 @@ func (e EvaluationInterval) parseInterval(interval string) (time.Duration, error return parsedInterval, nil } -// GetCompliantInterval converts the Compliant interval to a duration. ErrIsNever is returned when the string -// is set to "never". +// GetCompliantInterval converts the Compliant interval to a duration. ErrIsNever is returned when +// the string is set to "never". func (e EvaluationInterval) GetCompliantInterval() (time.Duration, error) { return e.parseInterval(e.Compliant) } -// GetNonCompliantInterval converts the NonCompliant interval to a duration. ErrIsNever is returned when the string -// is set to "never". +// GetNonCompliantInterval converts the NonCompliant interval to a duration. ErrIsNever is returned +// when the string is set to "never". func (e EvaluationInterval) GetNonCompliantInterval() (time.Duration, error) { return e.parseInterval(e.NonCompliant) } -// ConfigurationPolicySpec defines the desired state of ConfigurationPolicy -type ConfigurationPolicySpec struct { - Severity Severity `json:"severity,omitempty"` // low, medium, high - RemediationAction RemediationAction `json:"remediationAction"` // enforce, inform - // 'namespaceSelector' defines the list of namespaces to include/exclude for objects defined in - // spec.objectTemplates. All selector rules are ANDed. If 'include' is not provided but - // 'matchLabels' and/or 'matchExpressions' are, 'include' will behave as if ['*'] were given. If - // 'matchExpressions' and 'matchLabels' are both not provided, 'include' must be provided to - // retrieve namespaces. - NamespaceSelector Target `json:"namespaceSelector,omitempty"` - // 'object-templates' and 'object-templates-raw' are arrays of objects for the configuration - // policy to check, create, modify, or delete on the cluster. 'object-templates' is an array - // of objects, while 'object-templates-raw' is a string containing an array of objects in - // YAML format. Only one of the two object-templates variables can be set in a given - // configurationPolicy. - ObjectTemplates []*ObjectTemplate `json:"object-templates,omitempty"` - // 'object-templates' and 'object-templates-raw' are arrays of objects for the configuration - // policy to check, create, modify, or delete on the cluster. 'object-templates' is an array - // of objects, while 'object-templates-raw' is a string containing an array of objects in - // YAML format. Only one of the two object-templates variables can be set in a given - // configurationPolicy. - ObjectTemplatesRaw string `json:"object-templates-raw,omitempty"` - EvaluationInterval EvaluationInterval `json:"evaluationInterval,omitempty"` - // +kubebuilder:default:=None - PruneObjectBehavior PruneObjectBehavior `json:"pruneObjectBehavior,omitempty"` -} +// ComplianceType describes how objects on the cluster should be compared with the configuration +// policy's object definition. Options are "MustHave", "MustOnlyHave", or "MustNotHave". +// +// +kubebuilder:validation:Enum=MustHave;Musthave;musthave;MustOnlyHave;Mustonlyhave;mustonlyhave;MustNotHave;Mustnothave;mustnothave +type ComplianceType string -// ObjectTemplate describes how an object should look -type ObjectTemplate struct { - // ComplianceType specifies whether it is: musthave, mustnothave, mustonlyhave - ComplianceType ComplianceType `json:"complianceType"` +const ( + // MustNotHave is a ComplianceType to not match an object definition. + MustNotHave ComplianceType = "MustNotHave" - MetadataComplianceType MetadataComplianceType `json:"metadataComplianceType,omitempty"` + // MustHave is a ComplianceType to match an object definition as a subset of the whole object. + MustHave ComplianceType = "MustHave" - // ObjectDefinition defines required fields for the object - // +kubebuilder:pruning:PreserveUnknownFields - ObjectDefinition runtime.RawExtension `json:"objectDefinition"` + // MustOnlyHave is a ComplianceType to match an object definition exactly with the object. + MustOnlyHave ComplianceType = "MustOnlyHave" +) - // RecordDiff specifies whether (and where) to log the diff between the object on the - // cluster and the objectDefinition in the policy. Defaults to "None". - RecordDiff RecordDiff `json:"recordDiff,omitempty"` +func (c ComplianceType) IsMustHave() bool { + return strings.EqualFold(string(c), string(MustHave)) +} + +func (c ComplianceType) IsMustOnlyHave() bool { + return strings.EqualFold(string(c), string(MustOnlyHave)) +} + +func (c ComplianceType) IsMustNotHave() bool { + return strings.EqualFold(string(c), string(MustNotHave)) } +// MetadataComplianceType describes how the labels/annotations of objects on the cluster should be +// compared with the configuration policy's object definition. Options are "MustHave" or +// "MustOnlyHave". +// +// +kubebuilder:validation:Enum=MustHave;Musthave;musthave;MustOnlyHave;Mustonlyhave;mustonlyhave +type MetadataComplianceType string + // +kubebuilder:validation:Enum=Log;None type RecordDiff string @@ -211,120 +175,133 @@ const ( RecordDiffNone RecordDiff = "None" ) -// ConfigurationPolicyStatus defines the observed state of ConfigurationPolicy -type ConfigurationPolicyStatus struct { - ComplianceState ComplianceState `json:"compliant,omitempty"` // Compliant/NonCompliant/UnknownCompliancy - CompliancyDetails []TemplateStatus `json:"compliancyDetails,omitempty"` // reason for non-compliancy - // An ISO-8601 timestamp of the last time the policy was evaluated - LastEvaluated string `json:"lastEvaluated,omitempty"` - // The generation of the ConfigurationPolicy object when it was last evaluated - LastEvaluatedGeneration int64 `json:"lastEvaluatedGeneration,omitempty"` - // List of resources processed by the policy - RelatedObjects []RelatedObject `json:"relatedObjects,omitempty"` -} +// ObjectTemplate describes how an object should look +type ObjectTemplate struct { + ComplianceType ComplianceType `json:"complianceType"` + MetadataComplianceType MetadataComplianceType `json:"metadataComplianceType,omitempty"` -// CompliancePerClusterStatus contains aggregate status of other policies in cluster -type CompliancePerClusterStatus struct { - AggregatePolicyStatus map[string]*ConfigurationPolicyStatus `json:"aggregatePoliciesStatus,omitempty"` - ComplianceState ComplianceState `json:"compliant,omitempty"` - ClusterName string `json:"clustername,omitempty"` + // ObjectDefinition defines required fields, in whole or in part, to be compared with objects on + // the cluster. + // + // +kubebuilder:pruning:PreserveUnknownFields + ObjectDefinition runtime.RawExtension `json:"objectDefinition"` + + // RecordDiff specifies whether (and where) to log the diff between the object on the + // cluster and the objectDefinition in the policy. Defaults to "None". + RecordDiff RecordDiff `json:"recordDiff,omitempty"` } -// ComplianceMap map to hold CompliancePerClusterStatus objects -type ComplianceMap map[string]*CompliancePerClusterStatus +// ConfigurationPolicySpec defines the desired configuration of objects on the cluster along with +// how the configuration policy should handle when the cluster doesn't match the configuration +// policy. +type ConfigurationPolicySpec struct { + Severity Severity `json:"severity,omitempty"` + RemediationAction RemediationAction `json:"remediationAction"` + EvaluationInterval EvaluationInterval `json:"evaluationInterval,omitempty"` + // +kubebuilder:default:=None + PruneObjectBehavior PruneObjectBehavior `json:"pruneObjectBehavior,omitempty"` -//+kubebuilder:object:root=true -//+kubebuilder:subresource:status -//+kubebuilder:printcolumn:name="Compliance state",type="string",JSONPath=".status.compliant" + // NamespaceSelector defines the list of namespaces to include/exclude for objects defined in + // spec.object-templates. All selector rules are ANDed. If 'include' is not provided but + // 'matchLabels' and/or 'matchExpressions' are, 'include' will behave as if ['*'] were given. If + // 'matchExpressions' and 'matchLabels' are both not provided, 'include' must be provided to + // retrieve namespaces. + NamespaceSelector Target `json:"namespaceSelector,omitempty"` -// ConfigurationPolicy is the Schema for the configurationpolicies API -type ConfigurationPolicy struct { - metav1.TypeMeta `json:",inline"` - metav1.ObjectMeta `json:"metadata,omitempty"` + // 'object-templates' is an array of object configurations for the configuration policy to check, create, modify, or + // delete objects on the cluster. Keys inside of the objectDefinition in an object template may point to values that + // have Go templates. For more advanced Go templating such as `range` loops and `if` conditionals, use + // 'object-templates-raw'. Only one of 'object-templates' and 'object-templates-raw' may be set in a configuration + // policy. + // For more on the Go templates, see https://github.com/stolostron/go-template-utils/blob/main/README.md + ObjectTemplates []*ObjectTemplate `json:"object-templates,omitempty"` - Spec *ConfigurationPolicySpec `json:"spec,omitempty"` - Status ConfigurationPolicyStatus `json:"status,omitempty"` + // 'object-templates-raw' is a string containing Go templates that must ultimately produce an + // array of object configurations in YAML format to be used as 'object-templates'. Only one of + // 'object-templates' and 'object-templates-raw' may be set in a configuration policy. + // For more on the Go templates, see https://github.com/stolostron/go-template-utils/blob/main/README.md + ObjectTemplatesRaw string `json:"object-templates-raw,omitempty"` } -//+kubebuilder:object:root=true +// ComplianceState reports the observed status resulting from the policy's definition(s). +// +// +kubebuilder:validation:Enum=Compliant;Pending;NonCompliant;Terminating +type ComplianceState string -// ConfigurationPolicyList contains a list of ConfigurationPolicy -type ConfigurationPolicyList struct { - metav1.TypeMeta `json:",inline"` - metav1.ListMeta `json:"metadata,omitempty"` - Items []ConfigurationPolicy `json:"items"` -} +const ( + Compliant ComplianceState = "Compliant" + NonCompliant ComplianceState = "NonCompliant" + UnknownCompliancy ComplianceState = "UnknownCompliancy" + Terminating ComplianceState = "Terminating" +) -// TemplateStatus hold the status result -type TemplateStatus struct { - ComplianceState ComplianceState `json:"Compliant,omitempty"` // Compliant, NonCompliant, UnknownCompliancy +// Condition contains the details of an evaluation of an object-template. +type Condition struct { + // Type is the type of condition, either "violation" or "notification". + Type string `json:"type"` + + // Status is an unused field. If set, it's set to "True". + Status corev1.ConditionStatus `json:"status,omitempty" protobuf:"bytes,12,rep,name=status"` + + // LastTransitionTime is the most recent time the condition transitioned to the current condition. + // // +optional - // +patchMergeKey=type - // +patchStrategy=merge - Conditions []Condition `json:"conditions,omitempty"` + LastTransitionTime metav1.Time `json:"lastTransitionTime,omitempty" protobuf:"bytes,3,opt,name=lastTransitionTime"` - Validity Validity `json:"Validity,omitempty"` // a template can be invalid if it has conflicting roles + // Reason is a brief reason for the condition. + // + // +optional + Reason string `json:"reason,omitempty" protobuf:"bytes,4,opt,name=reason"` + + // Message is a human-readable message indicating details about the condition. + // + // +optional + Message string `json:"message,omitempty" protobuf:"bytes,5,opt,name=message"` } -// Validity describes if it is valid or not -type Validity struct { +type Validity struct { // UNUSED (attached to a field marked as deprecated) Valid *bool `json:"valid,omitempty"` Reason string `json:"reason,omitempty"` } -// ComplianceType describes whether we must or must not have a given resource -// +kubebuilder:validation:Enum=MustHave;Musthave;musthave;MustOnlyHave;Mustonlyhave;mustonlyhave;MustNotHave;Mustnothave;mustnothave -type ComplianceType string - -const ( - // MustNotHave is an enforcement state to exclude a resource - MustNotHave ComplianceType = "Mustnothave" - - // MustHave is an enforcement state to include a resource - MustHave ComplianceType = "Musthave" - - // MustOnlyHave is an enforcement state to exclusively include a resource - MustOnlyHave ComplianceType = "Mustonlyhave" -) - -func (c ComplianceType) IsMustHave() bool { - return strings.EqualFold(string(c), string(MustHave)) -} +// TemplateStatus reports the compliance details resulting from the definitions in an +// object-template. +type TemplateStatus struct { + ComplianceState ComplianceState `json:"Compliant,omitempty"` -func (c ComplianceType) IsMustOnlyHave() bool { - return strings.EqualFold(string(c), string(MustOnlyHave)) -} + // Conditions contains the details from the latest evaluation of the object-template. + // + // +optional + // +patchMergeKey=type + // +patchStrategy=merge + Conditions []Condition `json:"conditions,omitempty"` -func (c ComplianceType) IsMustNotHave() bool { - return strings.EqualFold(string(c), string(MustNotHave)) + // Deprecated + Validity Validity `json:"Validity,omitempty"` } -// MetadataComplianceType describes how to check compliance for the labels/annotations of a given object -// +kubebuilder:validation:Enum=MustHave;Musthave;musthave;MustOnlyHave;Mustonlyhave;mustonlyhave -type MetadataComplianceType string +// ObjectMetadata contains the metadata for an object matched by the configuration policy. +type ObjectMetadata struct { + // Name of the related object. + Name string `json:"name,omitempty"` -// RelatedObject is the list of objects matched by this Policy resource. -type RelatedObject struct { - // - Object ObjectResource `json:"object,omitempty"` - // - Compliant string `json:"compliant,omitempty"` - // - Reason string `json:"reason,omitempty"` - Properties *ObjectProperties `json:"properties,omitempty"` + // Namespace of the related object. + Namespace string `json:"namespace,omitempty"` } -// ObjectResource is an object identified by the policy as a resource that needs to be validated. +// ObjectResource contains details about an object matched by the configuration policy. type ObjectResource struct { - // Kind of the referent. More info: - // https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + Metadata ObjectMetadata `json:"metadata,omitempty"` + + // Kind of the related object. Kind string `json:"kind,omitempty"` - // API version of the referent. + + // API version of the related object. APIVersion string `json:"apiVersion,omitempty"` - // Metadata values from the referent. - Metadata ObjectMetadata `json:"metadata,omitempty"` } +// ObjectResourceFromObj mutates a Kubernetes object into an ObjectResource type to populate the +// policy status with related objects. func ObjectResourceFromObj(obj client.Object) ObjectResource { name := obj.GetName() if name == "" { @@ -341,23 +318,80 @@ func ObjectResourceFromObj(obj client.Object) ObjectResource { } } -// ObjectMetadata contains the resource metadata for an object being processed by the policy -type ObjectMetadata struct { - // Name of the referent. More info: - // https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - Name string `json:"name,omitempty"` - // Namespace of the referent. More info: - // https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - Namespace string `json:"namespace,omitempty"` -} - +// Properties are additional properties of the related object relevant to the configuration policy. type ObjectProperties struct { - // Whether the object was created by the parent policy + // CreatedByPolicy reports whether the object was created by the configuration policy, which is + // important when pruning is configured. CreatedByPolicy *bool `json:"createdByPolicy,omitempty"` - // Store object UID to help track object ownership for deletion + + // UID stores the object UID to help track object ownership for deletion when pruning is + // configured. UID string `json:"uid,omitempty"` } +// RelatedObject contains the details of an object matched by the configuration policy. +type RelatedObject struct { + Properties *ObjectProperties `json:"properties,omitempty"` + + // ObjectResource contains the identifying fields of the related object. + Object ObjectResource `json:"object,omitempty"` + + // Compliant is whether the related object is compliant with the configuration policy's + // definition(s). + Compliant string `json:"compliant,omitempty"` + + // Reason is a human-readable message of why the related object has a particular compliance. + Reason string `json:"reason,omitempty"` +} + +// ConfigurationPolicyStatus reports the observed status of the configuration policy resulting from +// its object definition(s). +type ConfigurationPolicyStatus struct { + ComplianceState ComplianceState `json:"compliant,omitempty"` + + // CompliancyDetails is a list of statuses matching 1-1 with each of the items in the + // object-templates array. + CompliancyDetails []TemplateStatus `json:"compliancyDetails,omitempty"` + + // LastEvaluated is an ISO-8601 timestamp of the last time the policy was evaluated. + LastEvaluated string `json:"lastEvaluated,omitempty"` + + // LastEvaluatedGeneration is the generation of the ConfigurationPolicy object when it was last + // evaluated. + LastEvaluatedGeneration int64 `json:"lastEvaluatedGeneration,omitempty"` + + // RelatedObjects is a list of objects processed by the configuration policy due to its + // object-templates. + RelatedObjects []RelatedObject `json:"relatedObjects,omitempty"` +} + +// ConfigurationPolicy is the Schema for the configurationpolicies API. A configuration policy +// contains, in whole or in part, an object definition to compare with objects on the cluster. If +// the configuration policy's definition doesn't match the objects on the cluster, the configuration +// policy will report a non-compliant status. Furthermore, if the RemediationAction is set to +// "enforce" and the name of the object is available, the configuration policy controller will patch +// the object to match in order to make the configuration policy compliant. +// +// +kubebuilder:object:root=true +// +kubebuilder:subresource:status +// +kubebuilder:printcolumn:name="Compliance state",type="string",JSONPath=".status.compliant" +type ConfigurationPolicy struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + + Spec *ConfigurationPolicySpec `json:"spec,omitempty"` + Status ConfigurationPolicyStatus `json:"status,omitempty"` +} + +// ConfigurationPolicyList contains a list of configuration policies. +// +// +kubebuilder:object:root=true +type ConfigurationPolicyList struct { + metav1.TypeMeta `json:",inline"` + metav1.ListMeta `json:"metadata,omitempty"` + Items []ConfigurationPolicy `json:"items"` +} + func init() { SchemeBuilder.Register(&ConfigurationPolicy{}, &ConfigurationPolicyList{}) } diff --git a/api/v1/zz_generated.deepcopy.go b/api/v1/zz_generated.deepcopy.go index 87dc4c0f..f3e686cc 100644 --- a/api/v1/zz_generated.deepcopy.go +++ b/api/v1/zz_generated.deepcopy.go @@ -12,67 +12,6 @@ import ( "k8s.io/apimachinery/pkg/runtime" ) -// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. -func (in ComplianceMap) DeepCopyInto(out *ComplianceMap) { - { - in := &in - *out = make(ComplianceMap, len(*in)) - for key, val := range *in { - var outVal *CompliancePerClusterStatus - if val == nil { - (*out)[key] = nil - } else { - inVal := (*in)[key] - in, out := &inVal, &outVal - *out = new(CompliancePerClusterStatus) - (*in).DeepCopyInto(*out) - } - (*out)[key] = outVal - } - } -} - -// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ComplianceMap. -func (in ComplianceMap) DeepCopy() ComplianceMap { - if in == nil { - return nil - } - out := new(ComplianceMap) - in.DeepCopyInto(out) - return *out -} - -// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. -func (in *CompliancePerClusterStatus) DeepCopyInto(out *CompliancePerClusterStatus) { - *out = *in - if in.AggregatePolicyStatus != nil { - in, out := &in.AggregatePolicyStatus, &out.AggregatePolicyStatus - *out = make(map[string]*ConfigurationPolicyStatus, len(*in)) - for key, val := range *in { - var outVal *ConfigurationPolicyStatus - if val == nil { - (*out)[key] = nil - } else { - inVal := (*in)[key] - in, out := &inVal, &outVal - *out = new(ConfigurationPolicyStatus) - (*in).DeepCopyInto(*out) - } - (*out)[key] = outVal - } - } -} - -// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CompliancePerClusterStatus. -func (in *CompliancePerClusterStatus) DeepCopy() *CompliancePerClusterStatus { - if in == nil { - return nil - } - out := new(CompliancePerClusterStatus) - in.DeepCopyInto(out) - return out -} - // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. func (in *Condition) DeepCopyInto(out *Condition) { *out = *in @@ -155,6 +94,7 @@ func (in *ConfigurationPolicyList) DeepCopyObject() runtime.Object { // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. func (in *ConfigurationPolicySpec) DeepCopyInto(out *ConfigurationPolicySpec) { *out = *in + out.EvaluationInterval = in.EvaluationInterval in.NamespaceSelector.DeepCopyInto(&out.NamespaceSelector) if in.ObjectTemplates != nil { in, out := &in.ObjectTemplates, &out.ObjectTemplates @@ -167,7 +107,6 @@ func (in *ConfigurationPolicySpec) DeepCopyInto(out *ConfigurationPolicySpec) { } } } - out.EvaluationInterval = in.EvaluationInterval } // DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ConfigurationPolicySpec. @@ -294,12 +233,12 @@ func (in *ObjectTemplate) DeepCopy() *ObjectTemplate { // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. func (in *RelatedObject) DeepCopyInto(out *RelatedObject) { *out = *in - out.Object = in.Object if in.Properties != nil { in, out := &in.Properties, &out.Properties *out = new(ObjectProperties) (*in).DeepCopyInto(*out) } + out.Object = in.Object } // DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new RelatedObject. diff --git a/api/v1beta1/operatorpolicy_types.go b/api/v1beta1/operatorpolicy_types.go index a77ef632..a15c121a 100644 --- a/api/v1beta1/operatorpolicy_types.go +++ b/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"` diff --git a/deploy/crds/kustomize_configurationpolicy/policy.open-cluster-management.io_configurationpolicies.yaml b/deploy/crds/kustomize_configurationpolicy/policy.open-cluster-management.io_configurationpolicies.yaml index fa4c0edf..0aab4bf2 100644 --- a/deploy/crds/kustomize_configurationpolicy/policy.open-cluster-management.io_configurationpolicies.yaml +++ b/deploy/crds/kustomize_configurationpolicy/policy.open-cluster-management.io_configurationpolicies.yaml @@ -21,8 +21,13 @@ spec: name: v1 schema: openAPIV3Schema: - description: ConfigurationPolicy is the Schema for the configurationpolicies - API + description: |- + ConfigurationPolicy is the Schema for the configurationpolicies API. A configuration policy + contains, in whole or in part, an object definition to compare with objects on the cluster. If + the configuration policy's definition doesn't match the objects on the cluster, the configuration + policy will report a non-compliant status. Furthermore, if the RemediationAction is set to + "enforce" and the name of the object is available, the configuration policy controller will patch + the object to match in order to make the configuration policy compliant. properties: apiVersion: description: |- @@ -42,52 +47,56 @@ spec: metadata: type: object spec: - description: ConfigurationPolicySpec defines the desired state of ConfigurationPolicy + description: |- + ConfigurationPolicySpec defines the desired configuration of objects on the cluster along with + how the configuration policy should handle when the cluster doesn't match the configuration + policy. properties: evaluationInterval: description: |- - Configures the minimum elapsed time before a ConfigurationPolicy is reevaluated. If the policy - spec is changed, or if the list of namespaces selected by the policy changes, the policy may be - evaluated regardless of the settings here. + EvaluationInterval configures the minimum elapsed time before a configuration policy is + reevaluated. If the policy spec is changed, or if the list of namespaces selected by the policy + changes, the policy may be evaluated regardless of the settings here. properties: compliant: description: |- - The minimum elapsed time before a ConfigurationPolicy is reevaluated when in the compliant state. Set this to - "never" to disable reevaluation when in the compliant state. + Compliant is the minimum elapsed time before a configuration policy is reevaluated when in the + compliant state. Set this to "never" to disable reevaluation when in the compliant state. pattern: ^(?:(?:(?:[0-9]+(?:.[0-9])?)(?:h|m|s|(?:ms)|(?:us)|(?:ns)))|never)+$ type: string noncompliant: description: |- - The minimum elapsed time before a ConfigurationPolicy is reevaluated when in the noncompliant state. Set this to - "never" to disable reevaluation when in the noncompliant state. + NonCompliant is the minimum elapsed time before a configuration policy is reevaluated when in + the noncompliant state. Set this to "never" to disable reevaluation when in the noncompliant + state. pattern: ^(?:(?:(?:[0-9]+(?:.[0-9])?)(?:h|m|s|(?:ms)|(?:us)|(?:ns)))|never)+$ type: string type: object namespaceSelector: description: |- - 'namespaceSelector' defines the list of namespaces to include/exclude for objects defined in - spec.objectTemplates. All selector rules are ANDed. If 'include' is not provided but + NamespaceSelector defines the list of namespaces to include/exclude for objects defined in + spec.object-templates. All selector rules are ANDed. If 'include' is not provided but 'matchLabels' and/or 'matchExpressions' are, 'include' will behave as if ['*'] were given. If 'matchExpressions' and 'matchLabels' are both not provided, 'include' must be provided to retrieve namespaces. properties: exclude: - description: '''exclude'' is an array of filepath expressions - to exclude objects by name.' + description: Exclude is an array of filepath expressions to exclude + objects by name. items: minLength: 1 type: string type: array include: - description: '''include'' is an array of filepath expressions - to include objects by name.' + description: Include is an array of filepath expressions to include + objects by name. items: minLength: 1 type: string type: array matchExpressions: - description: '''matchExpressions'' is an array of label selector - requirements matching objects by label.' + description: MatchExpressions is an array of label selector requirements + matching objects by label. items: description: |- A label selector requirement is a selector that contains values, a key, and an operator that @@ -119,23 +128,25 @@ spec: matchLabels: additionalProperties: type: string - description: '''matchLabels'' is a map of {key,value} pairs matching - objects by label.' + description: MatchLabels is a map of {key,value} pairs matching + objects by label. type: object type: object object-templates: description: |- - 'object-templates' and 'object-templates-raw' are arrays of objects for the configuration - policy to check, create, modify, or delete on the cluster. 'object-templates' is an array - of objects, while 'object-templates-raw' is a string containing an array of objects in - YAML format. Only one of the two object-templates variables can be set in a given - configurationPolicy. + 'object-templates' is an array of object configurations for the configuration policy to check, create, modify, or + delete objects on the cluster. Keys inside of the objectDefinition in an object template may point to values that + have Go templates. For more advanced Go templating such as `range` loops and `if` conditionals, use + 'object-templates-raw'. Only one of 'object-templates' and 'object-templates-raw' may be set in a configuration + policy. + For more on the Go templates, see https://github.com/stolostron/go-template-utils/blob/main/README.md items: description: ObjectTemplate describes how an object should look properties: complianceType: - description: 'ComplianceType specifies whether it is: musthave, - mustnothave, mustonlyhave' + description: |- + ComplianceType describes how objects on the cluster should be compared with the configuration + policy's object definition. Options are "MustHave", "MustOnlyHave", or "MustNotHave". enum: - MustHave - Musthave @@ -148,8 +159,10 @@ spec: - mustnothave type: string metadataComplianceType: - description: MetadataComplianceType describes how to check compliance - for the labels/annotations of a given object + description: |- + MetadataComplianceType describes how the labels/annotations of objects on the cluster should be + compared with the configuration policy's object definition. Options are "MustHave" or + "MustOnlyHave". enum: - MustHave - Musthave @@ -159,8 +172,9 @@ spec: - mustonlyhave type: string objectDefinition: - description: ObjectDefinition defines required fields for the - object + description: |- + ObjectDefinition defines required fields, in whole or in part, to be compared with objects on + the cluster. type: object x-kubernetes-preserve-unknown-fields: true recordDiff: @@ -178,24 +192,25 @@ spec: type: array object-templates-raw: description: |- - 'object-templates' and 'object-templates-raw' are arrays of objects for the configuration - policy to check, create, modify, or delete on the cluster. 'object-templates' is an array - of objects, while 'object-templates-raw' is a string containing an array of objects in - YAML format. Only one of the two object-templates variables can be set in a given - configurationPolicy. + 'object-templates-raw' is a string containing Go templates that must ultimately produce an + array of object configurations in YAML format to be used as 'object-templates'. Only one of + 'object-templates' and 'object-templates-raw' may be set in a configuration policy. + For more on the Go templates, see https://github.com/stolostron/go-template-utils/blob/main/README.md type: string pruneObjectBehavior: default: None description: |- - PruneObjectBehavior is used to remove objects that are managed by the - policy upon policy deletion. + PruneObjectBehavior is used to remove objects that are managed by the policy upon policy + deletion. enum: - DeleteAll - DeleteIfCreated - None type: string remediationAction: - description: 'RemediationAction : enforce or inform' + description: |- + RemediationAction specifies the remediation of the policy. The parameter values are enforce and + inform. enum: - Inform - inform @@ -203,7 +218,9 @@ spec: - enforce type: string severity: - description: 'Severity : low, medium, high, or critical' + description: |- + Severity is a user-defined severity for when an object is found out of compliance with this + configuration policy. Accepted values are low, medium, high, and critical. enum: - low - Low @@ -218,17 +235,30 @@ spec: - remediationAction type: object status: - description: ConfigurationPolicyStatus defines the observed state of ConfigurationPolicy + description: |- + ConfigurationPolicyStatus reports the observed status of the configuration policy resulting from + its object definition(s). properties: compliancyDetails: + description: |- + CompliancyDetails is a list of statuses matching 1-1 with each of the items in the + object-templates array. items: - description: TemplateStatus hold the status result + description: |- + TemplateStatus reports the compliance details resulting from the definitions in an + object-template. properties: Compliant: - description: ComplianceState shows the state of enforcement + description: ComplianceState reports the observed status resulting + from the policy's definition(s). + enum: + - Compliant + - Pending + - NonCompliant + - Terminating type: string Validity: - description: Validity describes if it is valid or not + description: Deprecated properties: reason: type: string @@ -236,28 +266,31 @@ spec: type: boolean type: object conditions: + description: Conditions contains the details from the latest + evaluation of the object-template. items: - description: Condition is the base struct for representing - resource conditions + description: Condition contains the details of an evaluation + of an object-template. properties: lastTransitionTime: - description: The last time the condition transitioned - from one status to another. + description: LastTransitionTime is the most recent time + the condition transitioned to the current condition. format: date-time type: string message: - description: A human readable message indicating details - about the transition. + description: Message is a human-readable message indicating + details about the condition. type: string reason: - description: The reason for the condition's last transition. + description: Reason is a brief reason for the condition. type: string status: - description: Status of the condition, one of True, False, - Unknown. + description: Status is an unused field. If set, it's set + to "True". type: string type: - description: Type of condition, e.g Complete or Failed. + description: Type is the type of condition, either "violation" + or "notification". type: string required: - type @@ -266,64 +299,77 @@ spec: type: object type: array compliant: - description: ComplianceState shows the state of enforcement + description: ComplianceState reports the observed status resulting + from the policy's definition(s). + enum: + - Compliant + - Pending + - NonCompliant + - Terminating type: string lastEvaluated: - description: An ISO-8601 timestamp of the last time the policy was - evaluated + description: LastEvaluated is an ISO-8601 timestamp of the last time + the policy was evaluated. type: string lastEvaluatedGeneration: - description: The generation of the ConfigurationPolicy object when - it was last evaluated + description: |- + LastEvaluatedGeneration is the generation of the ConfigurationPolicy object when it was last + evaluated. format: int64 type: integer relatedObjects: - description: List of resources processed by the policy + description: |- + RelatedObjects is a list of objects processed by the configuration policy due to its + object-templates. items: - description: RelatedObject is the list of objects matched by this - Policy resource. + description: RelatedObject contains the details of an object matched + by the configuration policy. properties: compliant: + description: |- + Compliant is whether the related object is compliant with the configuration policy's + definition(s). type: string object: - description: ObjectResource is an object identified by the policy - as a resource that needs to be validated. + description: ObjectResource contains the identifying fields + of the related object. properties: apiVersion: - description: API version of the referent. + description: API version of the related object. type: string kind: - description: |- - Kind of the referent. More info: - https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + description: Kind of the related object. type: string metadata: - description: Metadata values from the referent. + description: ObjectMetadata contains the metadata for an + object matched by the configuration policy. properties: name: - description: |- - Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + description: Name of the related object. type: string namespace: - description: |- - Namespace of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ + description: Namespace of the related object. type: string type: object type: object properties: + description: Properties are additional properties of the related + object relevant to the configuration policy. properties: createdByPolicy: - description: Whether the object was created by the parent - policy + description: |- + CreatedByPolicy reports whether the object was created by the configuration policy, which is + important when pruning is configured. type: boolean uid: - description: Store object UID to help track object ownership - for deletion + description: |- + UID stores the object UID to help track object ownership for deletion when pruning is + configured. type: string type: object reason: + description: Reason is a human-readable message of why the related + object has a particular compliance. type: string type: object type: array diff --git a/deploy/crds/kustomize_operatorpolicy/policy.open-cluster-management.io_operatorpolicies.yaml b/deploy/crds/kustomize_operatorpolicy/policy.open-cluster-management.io_operatorpolicies.yaml index be7e48bc..d22cdae2 100644 --- a/deploy/crds/kustomize_operatorpolicy/policy.open-cluster-management.io_operatorpolicies.yaml +++ b/deploy/crds/kustomize_operatorpolicy/policy.open-cluster-management.io_operatorpolicies.yaml @@ -17,7 +17,10 @@ spec: - name: v1beta1 schema: openAPIV3Schema: - description: OperatorPolicy is the Schema for the operatorpolicies API + description: |- + 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. properties: apiVersion: description: |- @@ -37,11 +40,13 @@ spec: metadata: type: object spec: - description: OperatorPolicySpec defines the desired state of OperatorPolicy + description: OperatorPolicySpec defines the desired state of a particular + operator on the cluster. properties: complianceType: - description: ComplianceType describes whether we must or must not - have a given resource + description: |- + ComplianceType describes how objects on the cluster should be compared with the configuration + policy's object definition. Options are "MustHave", "MustOnlyHave", or "MustNotHave". enum: - MustHave - Musthave @@ -55,13 +60,15 @@ spec: type: string operatorGroup: description: |- - 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/ + 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/ type: object x-kubernetes-preserve-unknown-fields: true remediationAction: - description: 'RemediationAction : enforce or inform' + description: |- + RemediationAction specifies the remediation of the policy. The parameter values are enforce and + inform. enum: - Inform - inform @@ -69,7 +76,9 @@ spec: - enforce type: string severity: - description: 'Severity : low, medium, high, or critical' + description: |- + Severity is a user-defined severity for when an object is found out of compliance with this + configuration policy. Accepted values are low, medium, high, and critical. enum: - low - Low @@ -82,15 +91,16 @@ spec: type: string subscription: description: |- - 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/ type: object x-kubernetes-preserve-unknown-fields: true versions: description: |- - 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. items: minLength: 1 type: string @@ -100,13 +110,22 @@ spec: - subscription type: object status: - description: OperatorPolicyStatus defines the observed state of OperatorPolicy + description: |- + OperatorPolicyStatus reports the observed state of the operators resulting from the + specifications given in the operator policy. properties: compliant: - description: Most recent compliance state of the policy + description: ComplianceState reports the most recent compliance state + of the operator policy. + enum: + - Compliant + - Pending + - NonCompliant + - Terminating type: string conditions: - description: Historic details on the condition of the policy + description: Conditions reports historic details on the condition + of the operator policy. items: description: "Condition contains details for one aspect of the current state of this API Resource.\n---\nThis struct is intended for @@ -179,52 +198,57 @@ spec: - type x-kubernetes-list-type: map relatedObjects: - description: List of resources processed by the policy + description: RelatedObjects reports a list of resources associated + with the operator policy. items: - description: RelatedObject is the list of objects matched by this - Policy resource. + description: RelatedObject contains the details of an object matched + by the configuration policy. properties: compliant: + description: |- + Compliant is whether the related object is compliant with the configuration policy's + definition(s). type: string object: - description: ObjectResource is an object identified by the policy - as a resource that needs to be validated. + description: ObjectResource contains the identifying fields + of the related object. properties: apiVersion: - description: API version of the referent. + description: API version of the related object. type: string kind: - description: |- - Kind of the referent. More info: - https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + description: Kind of the related object. type: string metadata: - description: Metadata values from the referent. + description: ObjectMetadata contains the metadata for an + object matched by the configuration policy. properties: name: - description: |- - Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + description: Name of the related object. type: string namespace: - description: |- - Namespace of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ + description: Namespace of the related object. type: string type: object type: object properties: + description: Properties are additional properties of the related + object relevant to the configuration policy. properties: createdByPolicy: - description: Whether the object was created by the parent - policy + description: |- + CreatedByPolicy reports whether the object was created by the configuration policy, which is + important when pruning is configured. type: boolean uid: - description: Store object UID to help track object ownership - for deletion + description: |- + UID stores the object UID to help track object ownership for deletion when pruning is + configured. type: string type: object reason: + description: Reason is a human-readable message of why the related + object has a particular compliance. type: string type: object type: array diff --git a/deploy/crds/policy.open-cluster-management.io_configurationpolicies.yaml b/deploy/crds/policy.open-cluster-management.io_configurationpolicies.yaml index 6be90138..8b14a8aa 100644 --- a/deploy/crds/policy.open-cluster-management.io_configurationpolicies.yaml +++ b/deploy/crds/policy.open-cluster-management.io_configurationpolicies.yaml @@ -23,8 +23,13 @@ spec: name: v1 schema: openAPIV3Schema: - description: ConfigurationPolicy is the Schema for the configurationpolicies - API + description: |- + ConfigurationPolicy is the Schema for the configurationpolicies API. A configuration policy + contains, in whole or in part, an object definition to compare with objects on the cluster. If + the configuration policy's definition doesn't match the objects on the cluster, the configuration + policy will report a non-compliant status. Furthermore, if the RemediationAction is set to + "enforce" and the name of the object is available, the configuration policy controller will patch + the object to match in order to make the configuration policy compliant. properties: apiVersion: description: |- @@ -44,7 +49,10 @@ spec: metadata: type: object spec: - description: ConfigurationPolicySpec defines the desired state of ConfigurationPolicy + description: |- + ConfigurationPolicySpec defines the desired configuration of objects on the cluster along with + how the configuration policy should handle when the cluster doesn't match the configuration + policy. oneOf: - required: - object-templates @@ -53,48 +61,49 @@ spec: properties: evaluationInterval: description: |- - Configures the minimum elapsed time before a ConfigurationPolicy is reevaluated. If the policy - spec is changed, or if the list of namespaces selected by the policy changes, the policy may be - evaluated regardless of the settings here. + EvaluationInterval configures the minimum elapsed time before a configuration policy is + reevaluated. If the policy spec is changed, or if the list of namespaces selected by the policy + changes, the policy may be evaluated regardless of the settings here. properties: compliant: description: |- - The minimum elapsed time before a ConfigurationPolicy is reevaluated when in the compliant state. Set this to - "never" to disable reevaluation when in the compliant state. + Compliant is the minimum elapsed time before a configuration policy is reevaluated when in the + compliant state. Set this to "never" to disable reevaluation when in the compliant state. pattern: ^(?:(?:(?:[0-9]+(?:.[0-9])?)(?:h|m|s|(?:ms)|(?:us)|(?:ns)))|never)+$ type: string noncompliant: description: |- - The minimum elapsed time before a ConfigurationPolicy is reevaluated when in the noncompliant state. Set this to - "never" to disable reevaluation when in the noncompliant state. + NonCompliant is the minimum elapsed time before a configuration policy is reevaluated when in + the noncompliant state. Set this to "never" to disable reevaluation when in the noncompliant + state. pattern: ^(?:(?:(?:[0-9]+(?:.[0-9])?)(?:h|m|s|(?:ms)|(?:us)|(?:ns)))|never)+$ type: string type: object namespaceSelector: description: |- - 'namespaceSelector' defines the list of namespaces to include/exclude for objects defined in - spec.objectTemplates. All selector rules are ANDed. If 'include' is not provided but + NamespaceSelector defines the list of namespaces to include/exclude for objects defined in + spec.object-templates. All selector rules are ANDed. If 'include' is not provided but 'matchLabels' and/or 'matchExpressions' are, 'include' will behave as if ['*'] were given. If 'matchExpressions' and 'matchLabels' are both not provided, 'include' must be provided to retrieve namespaces. properties: exclude: - description: '''exclude'' is an array of filepath expressions - to exclude objects by name.' + description: Exclude is an array of filepath expressions to exclude + objects by name. items: minLength: 1 type: string type: array include: - description: '''include'' is an array of filepath expressions - to include objects by name.' + description: Include is an array of filepath expressions to include + objects by name. items: minLength: 1 type: string type: array matchExpressions: - description: '''matchExpressions'' is an array of label selector - requirements matching objects by label.' + description: MatchExpressions is an array of label selector requirements + matching objects by label. items: description: |- A label selector requirement is a selector that contains values, a key, and an operator that @@ -126,23 +135,25 @@ spec: matchLabels: additionalProperties: type: string - description: '''matchLabels'' is a map of {key,value} pairs matching - objects by label.' + description: MatchLabels is a map of {key,value} pairs matching + objects by label. type: object type: object object-templates: description: |- - 'object-templates' and 'object-templates-raw' are arrays of objects for the configuration - policy to check, create, modify, or delete on the cluster. 'object-templates' is an array - of objects, while 'object-templates-raw' is a string containing an array of objects in - YAML format. Only one of the two object-templates variables can be set in a given - configurationPolicy. + 'object-templates' is an array of object configurations for the configuration policy to check, create, modify, or + delete objects on the cluster. Keys inside of the objectDefinition in an object template may point to values that + have Go templates. For more advanced Go templating such as `range` loops and `if` conditionals, use + 'object-templates-raw'. Only one of 'object-templates' and 'object-templates-raw' may be set in a configuration + policy. + For more on the Go templates, see https://github.com/stolostron/go-template-utils/blob/main/README.md items: description: ObjectTemplate describes how an object should look properties: complianceType: - description: 'ComplianceType specifies whether it is: musthave, - mustnothave, mustonlyhave' + description: |- + ComplianceType describes how objects on the cluster should be compared with the configuration + policy's object definition. Options are "MustHave", "MustOnlyHave", or "MustNotHave". enum: - MustHave - Musthave @@ -155,8 +166,10 @@ spec: - mustnothave type: string metadataComplianceType: - description: MetadataComplianceType describes how to check compliance - for the labels/annotations of a given object + description: |- + MetadataComplianceType describes how the labels/annotations of objects on the cluster should be + compared with the configuration policy's object definition. Options are "MustHave" or + "MustOnlyHave". enum: - MustHave - Musthave @@ -166,8 +179,9 @@ spec: - mustonlyhave type: string objectDefinition: - description: ObjectDefinition defines required fields for the - object + description: |- + ObjectDefinition defines required fields, in whole or in part, to be compared with objects on + the cluster. type: object x-kubernetes-preserve-unknown-fields: true recordDiff: @@ -185,24 +199,25 @@ spec: type: array object-templates-raw: description: |- - 'object-templates' and 'object-templates-raw' are arrays of objects for the configuration - policy to check, create, modify, or delete on the cluster. 'object-templates' is an array - of objects, while 'object-templates-raw' is a string containing an array of objects in - YAML format. Only one of the two object-templates variables can be set in a given - configurationPolicy. + 'object-templates-raw' is a string containing Go templates that must ultimately produce an + array of object configurations in YAML format to be used as 'object-templates'. Only one of + 'object-templates' and 'object-templates-raw' may be set in a configuration policy. + For more on the Go templates, see https://github.com/stolostron/go-template-utils/blob/main/README.md type: string pruneObjectBehavior: default: None description: |- - PruneObjectBehavior is used to remove objects that are managed by the - policy upon policy deletion. + PruneObjectBehavior is used to remove objects that are managed by the policy upon policy + deletion. enum: - DeleteAll - DeleteIfCreated - None type: string remediationAction: - description: 'RemediationAction : enforce or inform' + description: |- + RemediationAction specifies the remediation of the policy. The parameter values are enforce and + inform. enum: - Inform - inform @@ -210,7 +225,9 @@ spec: - enforce type: string severity: - description: 'Severity : low, medium, high, or critical' + description: |- + Severity is a user-defined severity for when an object is found out of compliance with this + configuration policy. Accepted values are low, medium, high, and critical. enum: - low - Low @@ -225,17 +242,30 @@ spec: - remediationAction type: object status: - description: ConfigurationPolicyStatus defines the observed state of ConfigurationPolicy + description: |- + ConfigurationPolicyStatus reports the observed status of the configuration policy resulting from + its object definition(s). properties: compliancyDetails: + description: |- + CompliancyDetails is a list of statuses matching 1-1 with each of the items in the + object-templates array. items: - description: TemplateStatus hold the status result + description: |- + TemplateStatus reports the compliance details resulting from the definitions in an + object-template. properties: Compliant: - description: ComplianceState shows the state of enforcement + description: ComplianceState reports the observed status resulting + from the policy's definition(s). + enum: + - Compliant + - Pending + - NonCompliant + - Terminating type: string Validity: - description: Validity describes if it is valid or not + description: Deprecated properties: reason: type: string @@ -243,28 +273,31 @@ spec: type: boolean type: object conditions: + description: Conditions contains the details from the latest + evaluation of the object-template. items: - description: Condition is the base struct for representing - resource conditions + description: Condition contains the details of an evaluation + of an object-template. properties: lastTransitionTime: - description: The last time the condition transitioned - from one status to another. + description: LastTransitionTime is the most recent time + the condition transitioned to the current condition. format: date-time type: string message: - description: A human readable message indicating details - about the transition. + description: Message is a human-readable message indicating + details about the condition. type: string reason: - description: The reason for the condition's last transition. + description: Reason is a brief reason for the condition. type: string status: - description: Status of the condition, one of True, False, - Unknown. + description: Status is an unused field. If set, it's set + to "True". type: string type: - description: Type of condition, e.g Complete or Failed. + description: Type is the type of condition, either "violation" + or "notification". type: string required: - type @@ -273,64 +306,77 @@ spec: type: object type: array compliant: - description: ComplianceState shows the state of enforcement + description: ComplianceState reports the observed status resulting + from the policy's definition(s). + enum: + - Compliant + - Pending + - NonCompliant + - Terminating type: string lastEvaluated: - description: An ISO-8601 timestamp of the last time the policy was - evaluated + description: LastEvaluated is an ISO-8601 timestamp of the last time + the policy was evaluated. type: string lastEvaluatedGeneration: - description: The generation of the ConfigurationPolicy object when - it was last evaluated + description: |- + LastEvaluatedGeneration is the generation of the ConfigurationPolicy object when it was last + evaluated. format: int64 type: integer relatedObjects: - description: List of resources processed by the policy + description: |- + RelatedObjects is a list of objects processed by the configuration policy due to its + object-templates. items: - description: RelatedObject is the list of objects matched by this - Policy resource. + description: RelatedObject contains the details of an object matched + by the configuration policy. properties: compliant: + description: |- + Compliant is whether the related object is compliant with the configuration policy's + definition(s). type: string object: - description: ObjectResource is an object identified by the policy - as a resource that needs to be validated. + description: ObjectResource contains the identifying fields + of the related object. properties: apiVersion: - description: API version of the referent. + description: API version of the related object. type: string kind: - description: |- - Kind of the referent. More info: - https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + description: Kind of the related object. type: string metadata: - description: Metadata values from the referent. + description: ObjectMetadata contains the metadata for an + object matched by the configuration policy. properties: name: - description: |- - Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + description: Name of the related object. type: string namespace: - description: |- - Namespace of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ + description: Namespace of the related object. type: string type: object type: object properties: + description: Properties are additional properties of the related + object relevant to the configuration policy. properties: createdByPolicy: - description: Whether the object was created by the parent - policy + description: |- + CreatedByPolicy reports whether the object was created by the configuration policy, which is + important when pruning is configured. type: boolean uid: - description: Store object UID to help track object ownership - for deletion + description: |- + UID stores the object UID to help track object ownership for deletion when pruning is + configured. type: string type: object reason: + description: Reason is a human-readable message of why the related + object has a particular compliance. type: string type: object type: array diff --git a/deploy/crds/policy.open-cluster-management.io_operatorpolicies.yaml b/deploy/crds/policy.open-cluster-management.io_operatorpolicies.yaml index 05f74803..ad89b11c 100644 --- a/deploy/crds/policy.open-cluster-management.io_operatorpolicies.yaml +++ b/deploy/crds/policy.open-cluster-management.io_operatorpolicies.yaml @@ -19,7 +19,10 @@ spec: - name: v1beta1 schema: openAPIV3Schema: - description: OperatorPolicy is the Schema for the operatorpolicies API + description: |- + 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. properties: apiVersion: description: |- @@ -39,23 +42,27 @@ spec: metadata: type: object spec: - description: OperatorPolicySpec defines the desired state of OperatorPolicy + description: OperatorPolicySpec defines the desired state of a particular + operator on the cluster. properties: complianceType: - description: ComplianceType describes whether we must or must not - have a given resource + description: |- + ComplianceType describes how objects on the cluster should be compared with the configuration + policy's object definition. Options are "MustHave", "MustOnlyHave", or "MustNotHave". enum: - musthave type: string operatorGroup: description: |- - 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/ + 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/ type: object x-kubernetes-preserve-unknown-fields: true remediationAction: - description: 'RemediationAction : enforce or inform' + description: |- + RemediationAction specifies the remediation of the policy. The parameter values are enforce and + inform. enum: - Inform - inform @@ -63,7 +70,9 @@ spec: - enforce type: string severity: - description: 'Severity : low, medium, high, or critical' + description: |- + Severity is a user-defined severity for when an object is found out of compliance with this + configuration policy. Accepted values are low, medium, high, and critical. enum: - low - Low @@ -76,15 +85,16 @@ spec: type: string subscription: description: |- - 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/ type: object x-kubernetes-preserve-unknown-fields: true versions: description: |- - 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. items: minLength: 1 type: string @@ -94,13 +104,22 @@ spec: - subscription type: object status: - description: OperatorPolicyStatus defines the observed state of OperatorPolicy + description: |- + OperatorPolicyStatus reports the observed state of the operators resulting from the + specifications given in the operator policy. properties: compliant: - description: Most recent compliance state of the policy + description: ComplianceState reports the most recent compliance state + of the operator policy. + enum: + - Compliant + - Pending + - NonCompliant + - Terminating type: string conditions: - description: Historic details on the condition of the policy + description: Conditions reports historic details on the condition + of the operator policy. items: description: "Condition contains details for one aspect of the current state of this API Resource.\n---\nThis struct is intended for @@ -173,52 +192,57 @@ spec: - type x-kubernetes-list-type: map relatedObjects: - description: List of resources processed by the policy + description: RelatedObjects reports a list of resources associated + with the operator policy. items: - description: RelatedObject is the list of objects matched by this - Policy resource. + description: RelatedObject contains the details of an object matched + by the configuration policy. properties: compliant: + description: |- + Compliant is whether the related object is compliant with the configuration policy's + definition(s). type: string object: - description: ObjectResource is an object identified by the policy - as a resource that needs to be validated. + description: ObjectResource contains the identifying fields + of the related object. properties: apiVersion: - description: API version of the referent. + description: API version of the related object. type: string kind: - description: |- - Kind of the referent. More info: - https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + description: Kind of the related object. type: string metadata: - description: Metadata values from the referent. + description: ObjectMetadata contains the metadata for an + object matched by the configuration policy. properties: name: - description: |- - Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + description: Name of the related object. type: string namespace: - description: |- - Namespace of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ + description: Namespace of the related object. type: string type: object type: object properties: + description: Properties are additional properties of the related + object relevant to the configuration policy. properties: createdByPolicy: - description: Whether the object was created by the parent - policy + description: |- + CreatedByPolicy reports whether the object was created by the configuration policy, which is + important when pruning is configured. type: boolean uid: - description: Store object UID to help track object ownership - for deletion + description: |- + UID stores the object UID to help track object ownership for deletion when pruning is + configured. type: string type: object reason: + description: Reason is a human-readable message of why the related + object has a particular compliance. type: string type: object type: array