diff --git a/api/v1/configurationpolicy_types.go b/api/v1/configurationpolicy_types.go index e0a07f67..42ffedad 100644 --- a/api/v1/configurationpolicy_types.go +++ b/api/v1/configurationpolicy_types.go @@ -16,31 +16,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 is 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 { @@ -51,48 +38,30 @@ 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 noncompliant with this configuration +// policy. The supported options 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 either case: a +// change to the policy that causes an object to no longer be managed by the policy, or the deletion +// of the policy. +// +// +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"` } @@ -114,24 +83,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 might 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 @@ -149,62 +121,89 @@ 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 object definition +// of the configuration policy. The supported options are `MustHave`, `MustOnlyHave`, or +// `MustNotHave`. +// +// +kubebuilder:validation:Enum=MustHave;Musthave;musthave;MustOnlyHave;Mustonlyhave;mustonlyhave;MustNotHave;Mustnothave;mustnothave +type ComplianceType string + +const ( + // MustNotHave is a ComplianceType to not match an object definition. + MustNotHave ComplianceType = "MustNotHave" + + // MustHave is a ComplianceType to match an object definition as a subset of the whole object. + MustHave ComplianceType = "MustHave" + + // MustOnlyHave is a ComplianceType to match an object definition exactly with the object. + MustOnlyHave ComplianceType = "MustOnlyHave" +) + +func (c ComplianceType) IsMustHave() bool { + return strings.EqualFold(string(c), string(MustHave)) } -// ObjectTemplate describes how an object should look -type ObjectTemplate struct { - // ComplianceType specifies whether it is: musthave, mustnothave, mustonlyhave - ComplianceType ComplianceType `json:"complianceType"` +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 and annotations of objects on the cluster should +// be compared with the object definition of the configuration policy. The supported options are +// `MustHave` or `MustOnlyHave`. The default value is the value defined in `complianceType` for the +// object template. +// +// +kubebuilder:validation:Enum=MustHave;Musthave;musthave;MustOnlyHave;Mustonlyhave;mustonlyhave +type MetadataComplianceType string + +// +kubebuilder:validation:Enum=Log;InStatus;None +type RecordDiff string + +const ( + RecordDiffLog RecordDiff = "Log" + RecordDiffInStatus RecordDiff = "InStatus" + RecordDiffNone RecordDiff = "None" + // Censored is only used as an internal value to indicate a diff shouldn't be automatically generated. + RecordDiffCensored RecordDiff = "Censored" +) +// ObjectTemplate describes the desired state of an object on the cluster. +type ObjectTemplate struct { + ComplianceType ComplianceType `json:"complianceType"` MetadataComplianceType MetadataComplianceType `json:"metadataComplianceType,omitempty"` - // ObjectDefinition defines required fields for the object + // ObjectDefinition defines required fields 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" when the object kind is - // ConfigMap, OAuthAccessToken, OAuthAuthorizeTokens, Route, or Secret. Defaults to "InStatus" otherwise. + // RecordDiff specifies whether and where to log the difference between the object on the cluster + // and the `objectDefinition` in the policy. The supported options are `InStatus` to record the + // difference in the policy status field, `Log` to log the difference in the + // config-policy-controller pod, and `None` to not log the diff. The default value is `None` for + // object kinds that include sensitive data including `ConfigMap`, `OAuthAccessToken`, + // `OAuthAuthorizeTokens`, `Route`, and `Secret`. For all other kinds, the default value is + // `InStatus`. RecordDiff RecordDiff `json:"recordDiff,omitempty"` } +// RecordDiffWithDefault parses the `objectDefinition` in the policy for the kind and returns the +// default `recordDiff` value depending on whether the kind contains sensitive data. func (o *ObjectTemplate) RecordDiffWithDefault() RecordDiff { if o.RecordDiff != "" { return o.RecordDiff @@ -233,131 +232,115 @@ func (o *ObjectTemplate) RecordDiffWithDefault() RecordDiff { return RecordDiffInStatus } -// +kubebuilder:validation:Enum=Log;InStatus;None -type RecordDiff string +// ConfigurationPolicySpec defines the desired configuration of objects on the cluster, along with +// how the controller 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"` -const ( - RecordDiffLog RecordDiff = "Log" - RecordDiffInStatus RecordDiff = "InStatus" - RecordDiffNone RecordDiff = "None" - // Censored is only used as an internal value to indicate a diff shouldn't be automatically generated. - RecordDiffCensored RecordDiff = "Censored" -) + // NamespaceSelector defines the list of namespaces to include or exclude for objects defined in + // `spec["object-templates"]`. All selector rules are combined. 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"` -// 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"` -} + // The `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` can 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"` -// 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"` + // The `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` can 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"` } -// ComplianceMap map to hold CompliancePerClusterStatus objects -type ComplianceMap map[string]*CompliancePerClusterStatus - -//+kubebuilder:object:root=true -//+kubebuilder:subresource:status -//+kubebuilder:printcolumn:name="Compliance state",type="string",JSONPath=".status.compliant" +// ComplianceState reports the observed status from the definitions of the policy. +// +// +kubebuilder:validation:Enum=Compliant;Pending;NonCompliant;Terminating +type ComplianceState string -// ConfigurationPolicy is the Schema for the configurationpolicies API -type ConfigurationPolicy struct { - metav1.TypeMeta `json:",inline"` - metav1.ObjectMeta `json:"metadata,omitempty"` +const ( + Compliant ComplianceState = "Compliant" + NonCompliant ComplianceState = "NonCompliant" + UnknownCompliancy ComplianceState = "UnknownCompliancy" + Terminating ComplianceState = "Terminating" +) - Spec *ConfigurationPolicySpec `json:"spec,omitempty"` - Status ConfigurationPolicyStatus `json:"status,omitempty"` -} +// Condition contains the details of an evaluation of an `object-template`. +type Condition struct { + // Type is the type of condition. The supported options are `violation` or `notification`. + Type string `json:"type"` -//+kubebuilder:object:root=true + // Status is an unused field. If set, it's set to `True`. + Status corev1.ConditionStatus `json:"status,omitempty" protobuf:"bytes,12,rep,name=status"` -// ConfigurationPolicyList contains a list of ConfigurationPolicy -type ConfigurationPolicyList struct { - metav1.TypeMeta `json:",inline"` - metav1.ListMeta `json:"metadata,omitempty"` - Items []ConfigurationPolicy `json:"items"` -} + // LastTransitionTime is the most recent time the condition transitioned to the current condition. + // + // +optional + LastTransitionTime metav1.Time `json:"lastTransitionTime,omitempty" protobuf:"bytes,3,opt,name=lastTransitionTime"` -// TemplateStatus hold the status result -type TemplateStatus struct { - ComplianceState ComplianceState `json:"Compliant,omitempty"` // Compliant, NonCompliant, UnknownCompliancy + // Reason is a brief summary for the condition. + // // +optional - // +patchMergeKey=type - // +patchStrategy=merge - Conditions []Condition `json:"conditions,omitempty"` + Reason string `json:"reason,omitempty" protobuf:"bytes,4,opt,name=reason"` - Validity Validity `json:"Validity,omitempty"` // a template can be invalid if it has conflicting roles + // 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 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 == "" { @@ -374,24 +357,83 @@ 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 string `json:"uid,omitempty"` + + // UID stores the object UID to help track object ownership for deletion when pruning is + // configured. + UID string `json:"uid,omitempty"` + + // Diff stores the difference between the `objectDefinition` in the policy and the object on the + // cluster. Diff string `json:"diff,omitempty"` } +// RelatedObject contains the details of an object matched by the policy. +type RelatedObject struct { + Properties *ObjectProperties `json:"properties,omitempty"` + + // ObjectResource contains the identifying fields of the related object. + Object ObjectResource `json:"object,omitempty"` + + // Compliant represents whether the related object is compliant with the definition of the policy. + 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 is the observed status of the configuration policy from its object +// definitions. +type ConfigurationPolicyStatus struct { + ComplianceState ComplianceState `json:"compliant,omitempty"` + + // CompliancyDetails is a list of statuses matching one-to-one 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 definition of the configuration policy doesn't match the objects on the cluster, a +// noncompliant status is displayed. Furthermore, if the RemediationAction is set to `enforce` and +// the name of the object is available, the configuration policy controller creates or updates 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 ff12a83a..36c8ade8 100644 --- a/api/v1beta1/operatorpolicy_types.go +++ b/api/v1beta1/operatorpolicy_types.go @@ -12,28 +12,21 @@ import ( policyv1 "open-cluster-management.io/config-policy-controller/api/v1" ) -// StatusConfigAction : StatusMessageOnly or NonCompliant -// +kubebuilder:validation:Enum=StatusMessageOnly;NonCompliant -type StatusConfigAction string - -// RemovalAction : Keep, Delete, or DeleteIfUnused +// RemovalAction is the behavior when the operator policy is removed. The supported options are +// `Keep`, `Delete`, or `DeleteIfUnused`. +// +// +kubebuilder:validation:Enum=Keep;Delete;DeleteIfUnused type RemovalAction string const ( - // StatusMessageOnly is a StatusConfigAction that only shows the status message - StatusMessageOnly StatusConfigAction = "StatusMessageOnly" - // NonCompliant is a StatusConfigAction that shows the status message and sets - // the compliance to NonCompliant - NonCompliant StatusConfigAction = "NonCompliant" -) - -const ( - // Keep is a RemovalBehavior indicating that the controller may not delete a type + // Keep is a RemovalBehavior indicating that the controller may not delete a type. Keep RemovalAction = "Keep" - // Delete is a RemovalBehavior indicating that the controller may delete a type + + // Delete is a RemovalBehavior indicating that the controller may delete a type. Delete RemovalAction = "Delete" - // DeleteIfUnused is a RemovalBehavior indicating that the controller may delete - // a type only if is not being used by another subscription + + // DeleteIfUnused is a RemovalBehavior indicating that the controller may delete a type only if it + // is not being used by another subscription. DeleteIfUnused RemovalAction = "DeleteIfUnused" ) @@ -50,32 +43,40 @@ func (ra RemovalAction) IsDeleteIfUnused() bool { } type RemovalBehavior struct { + // Use the `operatorGroups` parameter to specify whether to delete the OperatorGroup. The default + // value is `DeleteIfUnused`, which only deletes the OperatorGroup if there is not another + // resource using it. + // //+kubebuilder:default=DeleteIfUnused //+kubebuilder:validation:Enum=Keep;DeleteIfUnused - // Specifies whether to delete the OperatorGroup; defaults to 'DeleteIfUnused' which - // will only delete the OperatorGroup if there is not another resource using it. OperatorGroups RemovalAction `json:"operatorGroups,omitempty"` + // Use the `subscriptions` parameter to specify whether to delete the Subscription. The default + // value is `Delete`. + // //+kubebuilder:default=Delete //+kubebuilder:validation:Enum=Keep;Delete - // Specifies whether to delete the Subscription; defaults to 'Delete' Subscriptions RemovalAction `json:"subscriptions,omitempty"` + // Use the `clusterServiceVersions` parameter to specify whether to delete the + // ClusterServiceVersion. The default value is `Delete`. + // //+kubebuilder:default=Delete //+kubebuilder:validation:Enum=Keep;Delete - // Specifies whether to delete the ClusterServiceVersion; defaults to 'Delete' CSVs RemovalAction `json:"clusterServiceVersions,omitempty"` + // Use the customResourceDefinitions parameter to specify whether to delete any + // CustomResourceDefinitions associated with the operator. The default value is `Keep`, because + // deleting them should be done deliberately. + // //+kubebuilder:default=Keep //+kubebuilder:validation:Enum=Keep;Delete - // Specifies whether to delete any CustomResourceDefinitions associated with the operator; - // defaults to 'Keep' because deleting them should be done deliberately CRDs RemovalAction `json:"customResourceDefinitions,omitempty"` } -// ApplyDefaults ensures that unset fields in a RemovalBehavior behave as if they were -// set to the default values. In a cluster, kubernetes API validation should ensure that -// there are no unset values, and should apply the default values itself. +// ApplyDefaults ensures that unset fields in a RemovalBehavior behave as if they were set to the +// default values. In a cluster, Kubernetes API validation should ensure that there are no unset +// values and should apply the default values itself. func (rb RemovalBehavior) ApplyDefaults() RemovalBehavior { withDefaults := *rb.DeepCopy() @@ -98,54 +99,89 @@ func (rb RemovalBehavior) ApplyDefaults() RemovalBehavior { return withDefaults } -// StatusConfig defines how resource statuses affect the OperatorPolicy status and compliance +// StatusConfigAction configures how a status condition is reported when the involved operators are +// out of compliance with the operator policy. Options are `StatusMessageOnly` or `NonCompliant`. +// +// +kubebuilder:validation:Enum=StatusMessageOnly;NonCompliant +type StatusConfigAction string + +const ( + // StatusMessageOnly is a StatusConfigAction that only shows the status message. + StatusMessageOnly StatusConfigAction = "StatusMessageOnly" + + // NonCompliant is a StatusConfigAction that shows the status message and sets the compliance to + // NonCompliant. + NonCompliant StatusConfigAction = "NonCompliant" +) + +// StatusConfig defines how resource statuses affect the overall operator policy status and +// compliance. type StatusConfig struct { + // CatalogSourcesUnhealthy defines how the CatalogSourcesUnhealthy condition affects the operator + // policy status. CatalogSourceUnhealthy StatusConfigAction `json:"catalogSourceUnhealthy,omitempty"` + + // DeploymentsUnavailable defines how the DeploymentsUnavailable condition affects the operator + // policy status. DeploymentsUnavailable StatusConfigAction `json:"deploymentsUnavailable,omitempty"` - UpgradesAvailable StatusConfigAction `json:"upgradesAvailable,omitempty"` - UpgradesProgressing StatusConfigAction `json:"upgradesProgressing,omitempty"` + + // UpgradesAvailable defines how the UpgradesAvailable condition affects the operator policy + // status. + UpgradesAvailable StatusConfigAction `json:"upgradesAvailable,omitempty"` + + // UpgradesProgressing defines how the UpgradesProgressing condition affects the operator policy + // status. + UpgradesProgressing StatusConfigAction `json:"upgradesProgressing,omitempty"` } -// OperatorPolicySpec defines the desired state of OperatorPolicy +// OperatorPolicySpec defines the desired state of a particular operator on the cluster. type OperatorPolicySpec struct { - Severity policyv1.Severity `json:"severity,omitempty"` // low, medium, high - RemediationAction policyv1.RemediationAction `json:"remediationAction,omitempty"` // inform, enforce - ComplianceType policyv1.ComplianceType `json:"complianceType"` // musthave, mustnothave - - // Include the name, namespace, and any `spec` fields for the OperatorGroup. - // For more info, see `kubectl explain operatorgroup.spec` or - // https://olm.operatorframework.io/docs/concepts/crds/operatorgroup/ + Severity policyv1.Severity `json:"severity,omitempty"` + RemediationAction policyv1.RemediationAction `json:"remediationAction,omitempty"` + ComplianceType policyv1.ComplianceType `json:"complianceType"` + + // OperatorGroup specifies which `OperatorGroup` to inspect. Include the name, namespace, and any + // `spec` fields for the operator group. For more info, see `kubectl explain operatorgroups.spec` + // or view https://olm.operatorframework.io/docs/concepts/crds/operatorgroup/. + // // +kubebuilder:pruning:PreserveUnknownFields // +optional OperatorGroup *runtime.RawExtension `json:"operatorGroup,omitempty"` - // Include the namespace, and any `spec` fields for the Subscription. - // For more info, see `kubectl explain subscription.spec` or - // https://olm.operatorframework.io/docs/concepts/crds/subscription/ - // +kubebuilder:validation:Required + // Subscription specifies which operator `Subscription` resource to inspect. Include the + // namespace, and any `spec` fields for the Subscription. For more info, see `kubectl explain + // subscriptions.operators.coreos.com.spec` or view + // https://olm.operatorframework.io/docs/concepts/crds/subscription/. + // // +kubebuilder:pruning:PreserveUnknownFields Subscription runtime.RawExtension `json:"subscription"` - // Versions is a list of nonempty strings that specifies which installed versions are compliant when - // in 'inform' mode, and which installPlans are approved when in 'enforce' mode + // Versions is a list of non-empty strings that specifies which installed versions are compliant + // when in `inform` mode and which `InstallPlans` are approved when in `enforce` mode. Versions []policyv1.NonEmptyString `json:"versions,omitempty"` + // Use RemovalBehavior to define what resources need to be removed when enforcing `mustnothave` + // policies. When in `inform` mode, any resources that are deleted if the policy is set to + // `enforce` makes the policy noncompliant, but resources that are kept are compliant. + // //+kubebuilder:default={} - // RemovalBehavior defines what resources will be removed by enforced mustnothave policies. - // When in inform mode, any resources that would be deleted if the policy was enforced will - // be causes for NonCompliance, but resources that would be kept will be considered Compliant. RemovalBehavior RemovalBehavior `json:"removalBehavior,omitempty"` } -// OperatorPolicyStatus defines the observed state of OperatorPolicy +// OperatorPolicyStatus is the observed state of the operators from the specifications given in the +// operator policy. type OperatorPolicyStatus struct { - // Most recent compliance state of the policy + // ComplianceState reports the most recent compliance state of the operator policy. ComplianceState policyv1.ComplianceState `json:"compliant,omitempty"` - // Historic details on the condition of the policy + + // Conditions includes historic details on the condition of the operator policy. + // // +listType=map // +listMapKey=type Conditions []metav1.Condition `json:"conditions,omitempty"` - // List of resources processed by the policy + + // RelatedObjects reports a list of resources associated with the operator policy. + // // +optional RelatedObjects []policyv1.RelatedObject `json:"relatedObjects"` @@ -157,6 +193,8 @@ type OperatorPolicyStatus struct { OverlappingPolicies []string `json:"overlappingPolicies,omitempty"` } +// RelatedObjsOfKind iterates over the related objects in the status and returns a map of the index +// in the array to the related object that has the given kind. func (status OperatorPolicyStatus) RelatedObjsOfKind(kind string) map[int]policyv1.RelatedObject { objs := make(map[int]policyv1.RelatedObject) @@ -169,9 +207,9 @@ func (status OperatorPolicyStatus) RelatedObjsOfKind(kind string) map[int]policy return objs } -// Searches the conditions of the policy, and returns the index and condition matching the -// given condition Type. It will return -1 as the index if no condition of the specified -// Type is found. +// GetCondition iterates over the status conditions of the policy and returns the index and +// condition matching the given condition Type. It will return -1 as the index if no condition of +// the specified Type is found. func (status OperatorPolicyStatus) GetCondition(condType string) (int, metav1.Condition) { for i, cond := range status.Conditions { if cond.Type == condType { @@ -182,10 +220,12 @@ func (status OperatorPolicyStatus) GetCondition(condType string) (int, metav1.Co return -1, metav1.Condition{} } -//+kubebuilder:object:root=true -//+kubebuilder:subresource:status - -// OperatorPolicy is the Schema for the operatorpolicies API +// OperatorPolicy is the schema for the operatorpolicies API. You can use the operator policy to +// manage operators by providing automation for their management and reporting on the status across +// the various operator objects. +// +// +kubebuilder:object:root=true +// +kubebuilder:subresource:status type OperatorPolicy struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` @@ -194,9 +234,9 @@ type OperatorPolicy struct { Status OperatorPolicyStatus `json:"status,omitempty"` } -//+kubebuilder:object:root=true - -// OperatorPolicyList contains a list of OperatorPolicy +// OperatorPolicyList contains a list of operator policies. +// +// +kubebuilder:object:root=true type OperatorPolicyList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata,omitempty"` 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 548f7575..ffd94acb 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 definition of the configuration policy doesn't match the objects on the cluster, a + noncompliant status is displayed. Furthermore, if the RemediationAction is set to `enforce` and + the name of the object is available, the configuration policy controller creates or updates the + object to match in order to make the configuration policy compliant. properties: apiVersion: description: |- @@ -42,52 +47,55 @@ 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 controller 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 might 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 - '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 + NamespaceSelector defines the list of namespaces to include or exclude for objects defined in + `spec["object-templates"]`. All selector rules are combined. 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 +127,27 @@ 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. + The `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` can 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 + description: ObjectTemplate describes the desired state of an object + on the cluster. properties: complianceType: - description: 'ComplianceType specifies whether it is: musthave, - mustnothave, mustonlyhave' + description: |- + ComplianceType describes how objects on the cluster should be compared with the object definition + of the configuration policy. The supported options are `MustHave`, `MustOnlyHave`, or + `MustNotHave`. enum: - MustHave - Musthave @@ -148,8 +160,11 @@ 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 and annotations of objects on the cluster should + be compared with the object definition of the configuration policy. The supported options are + `MustHave` or `MustOnlyHave`. The default value is the value defined in `complianceType` for the + object template. enum: - MustHave - Musthave @@ -159,15 +174,19 @@ spec: - mustonlyhave type: string objectDefinition: - description: ObjectDefinition defines required fields for the - object + description: ObjectDefinition defines required fields to be + compared with objects on the cluster. type: object x-kubernetes-preserve-unknown-fields: true recordDiff: description: |- - RecordDiff specifies whether (and where) to log the diff between the object on the - cluster and the objectDefinition in the policy. Defaults to "None" when the object kind is - ConfigMap, OAuthAccessToken, OAuthAuthorizeTokens, Route, or Secret. Defaults to "InStatus" otherwise. + RecordDiff specifies whether and where to log the difference between the object on the cluster + and the `objectDefinition` in the policy. The supported options are `InStatus` to record the + difference in the policy status field, `Log` to log the difference in the + config-policy-controller pod, and `None` to not log the diff. The default value is `None` for + object kinds that include sensitive data including `ConfigMap`, `OAuthAccessToken`, + `OAuthAuthorizeTokens`, `Route`, and `Secret`. For all other kinds, the default value is + `InStatus`. enum: - Log - InStatus @@ -180,24 +199,26 @@ 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. + The `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` can 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 either case: a + change to the policy that causes an object to no longer be managed by the policy, or the deletion + of the policy. enum: - DeleteAll - DeleteIfCreated - None type: string remediationAction: - description: 'RemediationAction : enforce or inform' + description: |- + RemediationAction is the remediation of the policy. The parameter values are `enforce` and + `inform`. enum: - Inform - inform @@ -205,7 +226,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 noncompliant with this configuration + policy. The supported options are `low`, `medium`, `high`, and `critical`. enum: - low - Low @@ -220,17 +243,29 @@ spec: - remediationAction type: object status: - description: ConfigurationPolicyStatus defines the observed state of ConfigurationPolicy + description: |- + ConfigurationPolicyStatus is the observed status of the configuration policy from its object + definitions. properties: compliancyDetails: + description: |- + CompliancyDetails is a list of statuses matching one-to-one with each of the items in the + `object-templates` array. items: - description: TemplateStatus hold the status result + description: TemplateStatus reports the compliance details from + the definitions in an `object-template`. properties: Compliant: - description: ComplianceState shows the state of enforcement + description: ComplianceState reports the observed status from + the definitions of the policy. + enum: + - Compliant + - Pending + - NonCompliant + - Terminating type: string Validity: - description: Validity describes if it is valid or not + description: Deprecated properties: reason: type: string @@ -238,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 summary 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. The supported + options are `violation` or `notification`. type: string required: - type @@ -268,66 +306,81 @@ spec: type: object type: array compliant: - description: ComplianceState shows the state of enforcement + description: ComplianceState reports the observed status from the + definitions of the policy. + 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 policy. properties: compliant: + description: Compliant represents whether the related object + is compliant with the definition of the policy. 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 diff: + description: |- + Diff stores the difference between the `objectDefinition` in the policy and the object on the + cluster. type: string 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 0be923b1..42e382bb 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. You can use the operator policy to + manage operators by providing automation for their management and reporting on the status across + the various operator objects. properties: apiVersion: description: |- @@ -37,11 +40,14 @@ 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 object definition + of the configuration policy. The supported options are `MustHave`, `MustOnlyHave`, or + `MustNotHave`. enum: - MustHave - Musthave @@ -55,13 +61,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 which `OperatorGroup` to inspect. Include the name, namespace, and any + `spec` fields for the operator group. For more info, see `kubectl explain operatorgroups.spec` + or view https://olm.operatorframework.io/docs/concepts/crds/operatorgroup/. type: object x-kubernetes-preserve-unknown-fields: true remediationAction: - description: 'RemediationAction : enforce or inform' + description: |- + RemediationAction is the remediation of the policy. The parameter values are `enforce` and + `inform`. enum: - Inform - inform @@ -71,47 +79,73 @@ spec: removalBehavior: default: {} description: |- - RemovalBehavior defines what resources will be removed by enforced mustnothave policies. - When in inform mode, any resources that would be deleted if the policy was enforced will - be causes for NonCompliance, but resources that would be kept will be considered Compliant. + Use RemovalBehavior to define what resources need to be removed when enforcing `mustnothave` + policies. When in `inform` mode, any resources that are deleted if the policy is set to + `enforce` makes the policy noncompliant, but resources that are kept are compliant. properties: clusterServiceVersions: + allOf: + - enum: + - Keep + - Delete + - DeleteIfUnused + - enum: + - Keep + - Delete default: Delete - description: Specifies whether to delete the ClusterServiceVersion; - defaults to 'Delete' - enum: - - Keep - - Delete + description: |- + Use the `clusterServiceVersions` parameter to specify whether to delete the + ClusterServiceVersion. The default value is `Delete`. type: string customResourceDefinitions: + allOf: + - enum: + - Keep + - Delete + - DeleteIfUnused + - enum: + - Keep + - Delete default: Keep description: |- - Specifies whether to delete any CustomResourceDefinitions associated with the operator; - defaults to 'Keep' because deleting them should be done deliberately - enum: - - Keep - - Delete + Use the customResourceDefinitions parameter to specify whether to delete any + CustomResourceDefinitions associated with the operator. The default value is `Keep`, because + deleting them should be done deliberately. type: string operatorGroups: + allOf: + - enum: + - Keep + - Delete + - DeleteIfUnused + - enum: + - Keep + - DeleteIfUnused default: DeleteIfUnused description: |- - Specifies whether to delete the OperatorGroup; defaults to 'DeleteIfUnused' which - will only delete the OperatorGroup if there is not another resource using it. - enum: - - Keep - - DeleteIfUnused + Use the `operatorGroups` parameter to specify whether to delete the OperatorGroup. The default + value is `DeleteIfUnused`, which only deletes the OperatorGroup if there is not another + resource using it. type: string subscriptions: + allOf: + - enum: + - Keep + - Delete + - DeleteIfUnused + - enum: + - Keep + - Delete default: Delete - description: Specifies whether to delete the Subscription; defaults - to 'Delete' - enum: - - Keep - - Delete + description: |- + Use the `subscriptions` parameter to specify whether to delete the Subscription. The default + value is `Delete`. type: string type: object severity: - description: 'Severity : low, medium, high, or critical' + description: |- + Severity is a user-defined severity for when an object is noncompliant with this configuration + policy. The supported options are `low`, `medium`, `high`, and `critical`. enum: - low - Low @@ -124,15 +158,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 - https://olm.operatorframework.io/docs/concepts/crds/subscription/ + Subscription specifies which operator `Subscription` resource to inspect. Include the + namespace, and any `spec` fields for the Subscription. For more info, see `kubectl explain + subscriptions.operators.coreos.com.spec` or view + https://olm.operatorframework.io/docs/concepts/crds/subscription/. 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 non-empty 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 @@ -142,13 +177,22 @@ spec: - subscription type: object status: - description: OperatorPolicyStatus defines the observed state of OperatorPolicy + description: |- + OperatorPolicyStatus is the observed state of the operators 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 includes 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 @@ -228,54 +272,61 @@ spec: type: string type: array 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 policy. properties: compliant: + description: Compliant represents whether the related object + is compliant with the definition of the policy. 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 diff: + description: |- + Diff stores the difference between the `objectDefinition` in the policy and the object on the + cluster. type: string 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 6f9a6761..326a10ce 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 definition of the configuration policy doesn't match the objects on the cluster, a + noncompliant status is displayed. Furthermore, if the RemediationAction is set to `enforce` and + the name of the object is available, the configuration policy controller creates or updates the + object to match in order to make the configuration policy compliant. properties: apiVersion: description: |- @@ -44,7 +49,9 @@ 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 controller should handle when the cluster doesn't match the configuration policy. oneOf: - required: - object-templates @@ -53,48 +60,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 might 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 - '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 + NamespaceSelector defines the list of namespaces to include or exclude for objects defined in + `spec["object-templates"]`. All selector rules are combined. 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 +134,27 @@ 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. + The `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` can 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 + description: ObjectTemplate describes the desired state of an object + on the cluster. properties: complianceType: - description: 'ComplianceType specifies whether it is: musthave, - mustnothave, mustonlyhave' + description: |- + ComplianceType describes how objects on the cluster should be compared with the object definition + of the configuration policy. The supported options are `MustHave`, `MustOnlyHave`, or + `MustNotHave`. enum: - MustHave - Musthave @@ -155,8 +167,11 @@ 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 and annotations of objects on the cluster should + be compared with the object definition of the configuration policy. The supported options are + `MustHave` or `MustOnlyHave`. The default value is the value defined in `complianceType` for the + object template. enum: - MustHave - Musthave @@ -166,15 +181,19 @@ spec: - mustonlyhave type: string objectDefinition: - description: ObjectDefinition defines required fields for the - object + description: ObjectDefinition defines required fields to be + compared with objects on the cluster. type: object x-kubernetes-preserve-unknown-fields: true recordDiff: description: |- - RecordDiff specifies whether (and where) to log the diff between the object on the - cluster and the objectDefinition in the policy. Defaults to "None" when the object kind is - ConfigMap, OAuthAccessToken, OAuthAuthorizeTokens, Route, or Secret. Defaults to "InStatus" otherwise. + RecordDiff specifies whether and where to log the difference between the object on the cluster + and the `objectDefinition` in the policy. The supported options are `InStatus` to record the + difference in the policy status field, `Log` to log the difference in the + config-policy-controller pod, and `None` to not log the diff. The default value is `None` for + object kinds that include sensitive data including `ConfigMap`, `OAuthAccessToken`, + `OAuthAuthorizeTokens`, `Route`, and `Secret`. For all other kinds, the default value is + `InStatus`. enum: - Log - InStatus @@ -187,24 +206,26 @@ 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. + The `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` can 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 either case: a + change to the policy that causes an object to no longer be managed by the policy, or the deletion + of the policy. enum: - DeleteAll - DeleteIfCreated - None type: string remediationAction: - description: 'RemediationAction : enforce or inform' + description: |- + RemediationAction is the remediation of the policy. The parameter values are `enforce` and + `inform`. enum: - Inform - inform @@ -212,7 +233,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 noncompliant with this configuration + policy. The supported options are `low`, `medium`, `high`, and `critical`. enum: - low - Low @@ -227,17 +250,29 @@ spec: - remediationAction type: object status: - description: ConfigurationPolicyStatus defines the observed state of ConfigurationPolicy + description: |- + ConfigurationPolicyStatus is the observed status of the configuration policy from its object + definitions. properties: compliancyDetails: + description: |- + CompliancyDetails is a list of statuses matching one-to-one with each of the items in the + `object-templates` array. items: - description: TemplateStatus hold the status result + description: TemplateStatus reports the compliance details from + the definitions in an `object-template`. properties: Compliant: - description: ComplianceState shows the state of enforcement + description: ComplianceState reports the observed status from + the definitions of the policy. + enum: + - Compliant + - Pending + - NonCompliant + - Terminating type: string Validity: - description: Validity describes if it is valid or not + description: Deprecated properties: reason: type: string @@ -245,28 +280,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 summary 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. The supported + options are `violation` or `notification`. type: string required: - type @@ -275,66 +313,81 @@ spec: type: object type: array compliant: - description: ComplianceState shows the state of enforcement + description: ComplianceState reports the observed status from the + definitions of the policy. + 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 policy. properties: compliant: + description: Compliant represents whether the related object + is compliant with the definition of the policy. 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 diff: + description: |- + Diff stores the difference between the `objectDefinition` in the policy and the object on the + cluster. type: string 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 06b24a61..a3f6fec7 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. You can use the operator policy to + manage operators by providing automation for their management and reporting on the status across + the various operator objects. properties: apiVersion: description: |- @@ -39,24 +42,29 @@ 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 object definition + of the configuration policy. The supported options are `MustHave`, `MustOnlyHave`, or + `MustNotHave`. enum: - musthave - mustnothave 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 which `OperatorGroup` to inspect. Include the name, namespace, and any + `spec` fields for the operator group. For more info, see `kubectl explain operatorgroups.spec` + or view https://olm.operatorframework.io/docs/concepts/crds/operatorgroup/. type: object x-kubernetes-preserve-unknown-fields: true remediationAction: - description: 'RemediationAction : enforce or inform' + description: |- + RemediationAction is the remediation of the policy. The parameter values are `enforce` and + `inform`. enum: - Inform - inform @@ -66,47 +74,73 @@ spec: removalBehavior: default: {} description: |- - RemovalBehavior defines what resources will be removed by enforced mustnothave policies. - When in inform mode, any resources that would be deleted if the policy was enforced will - be causes for NonCompliance, but resources that would be kept will be considered Compliant. + Use RemovalBehavior to define what resources need to be removed when enforcing `mustnothave` + policies. When in `inform` mode, any resources that are deleted if the policy is set to + `enforce` makes the policy noncompliant, but resources that are kept are compliant. properties: clusterServiceVersions: + allOf: + - enum: + - Keep + - Delete + - DeleteIfUnused + - enum: + - Keep + - Delete default: Delete - description: Specifies whether to delete the ClusterServiceVersion; - defaults to 'Delete' - enum: - - Keep - - Delete + description: |- + Use the `clusterServiceVersions` parameter to specify whether to delete the + ClusterServiceVersion. The default value is `Delete`. type: string customResourceDefinitions: + allOf: + - enum: + - Keep + - Delete + - DeleteIfUnused + - enum: + - Keep + - Delete default: Keep description: |- - Specifies whether to delete any CustomResourceDefinitions associated with the operator; - defaults to 'Keep' because deleting them should be done deliberately - enum: - - Keep - - Delete + Use the customResourceDefinitions parameter to specify whether to delete any + CustomResourceDefinitions associated with the operator. The default value is `Keep`, because + deleting them should be done deliberately. type: string operatorGroups: + allOf: + - enum: + - Keep + - Delete + - DeleteIfUnused + - enum: + - Keep + - DeleteIfUnused default: DeleteIfUnused description: |- - Specifies whether to delete the OperatorGroup; defaults to 'DeleteIfUnused' which - will only delete the OperatorGroup if there is not another resource using it. - enum: - - Keep - - DeleteIfUnused + Use the `operatorGroups` parameter to specify whether to delete the OperatorGroup. The default + value is `DeleteIfUnused`, which only deletes the OperatorGroup if there is not another + resource using it. type: string subscriptions: + allOf: + - enum: + - Keep + - Delete + - DeleteIfUnused + - enum: + - Keep + - Delete default: Delete - description: Specifies whether to delete the Subscription; defaults - to 'Delete' - enum: - - Keep - - Delete + description: |- + Use the `subscriptions` parameter to specify whether to delete the Subscription. The default + value is `Delete`. type: string type: object severity: - description: 'Severity : low, medium, high, or critical' + description: |- + Severity is a user-defined severity for when an object is noncompliant with this configuration + policy. The supported options are `low`, `medium`, `high`, and `critical`. enum: - low - Low @@ -119,15 +153,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 - https://olm.operatorframework.io/docs/concepts/crds/subscription/ + Subscription specifies which operator `Subscription` resource to inspect. Include the + namespace, and any `spec` fields for the Subscription. For more info, see `kubectl explain + subscriptions.operators.coreos.com.spec` or view + https://olm.operatorframework.io/docs/concepts/crds/subscription/. 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 non-empty 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 @@ -137,13 +172,22 @@ spec: - subscription type: object status: - description: OperatorPolicyStatus defines the observed state of OperatorPolicy + description: |- + OperatorPolicyStatus is the observed state of the operators 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 includes 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 @@ -223,52 +267,56 @@ spec: type: string type: array 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 policy. properties: compliant: + description: Compliant represents whether the related object + is compliant with the definition of the policy. 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