From 2b35ef5845ea4861691c35ef5acf6beb33e27136 Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Fri, 4 Nov 2022 17:40:02 +0200 Subject: [PATCH] API: Consolidate the documentation style for v1beta2 Signed-off-by: Stefan Prodan --- api/v1beta2/alert_types.go | 29 ++-- api/v1beta2/doc.go | 2 +- api/v1beta2/groupversion_info.go | 4 +- api/v1beta2/provider_types.go | 125 ++++++++-------- api/v1beta2/receiver_types.go | 29 ++-- api/v1beta2/reference_types.go | 8 +- ...notification.toolkit.fluxcd.io_alerts.yaml | 34 +++-- ...ification.toolkit.fluxcd.io_providers.yaml | 33 +++-- ...ification.toolkit.fluxcd.io_receivers.yaml | 33 +++-- docs/api/notification.md | 133 +++++++++--------- 10 files changed, 216 insertions(+), 214 deletions(-) diff --git a/api/v1beta2/alert_types.go b/api/v1beta2/alert_types.go index 9c367b1..88a0083 100644 --- a/api/v1beta2/alert_types.go +++ b/api/v1beta2/alert_types.go @@ -25,42 +25,45 @@ const ( AlertKind string = "Alert" ) -// AlertSpec defines an alerting rule for events involving a list of objects +// AlertSpec defines an alerting rule for events involving a list of objects. type AlertSpec struct { - // Send events using this provider. + // ProviderRef specifies which Provider this Alert should use. // +required ProviderRef meta.LocalObjectReference `json:"providerRef"` - // Filter events based on severity, defaults to ('info'). + // EventSeverity specifies how to filter events based on severity. // If set to 'info' no events will be filtered. // +kubebuilder:validation:Enum=info;error // +kubebuilder:default:=info // +optional EventSeverity string `json:"eventSeverity,omitempty"` - // Filter events based on the involved objects. + // EventSources specifies how to filter events based + // on the involved object kind, name and namespace. // +required EventSources []CrossNamespaceObjectReference `json:"eventSources"` - // A list of Golang regular expressions to be used for excluding messages. + // ExclusionList specifies a list of Golang regular expressions + // to be used for excluding messages. // +optional ExclusionList []string `json:"exclusionList,omitempty"` - // Short description of the impact and affected cluster. + // Summary holds a short description of the impact and affected cluster. // +kubebuilder:validation:MaxLength:=255 // +optional Summary string `json:"summary,omitempty"` - // This flag tells the controller to suspend subsequent events dispatching. - // Defaults to false. + // Suspend tells the controller to suspend subsequent + // events handling for this Alert. // +optional Suspend bool `json:"suspend,omitempty"` } -// AlertStatus defines the observed state of Alert +// AlertStatus defines the observed state of the Alert. type AlertStatus struct { meta.ReconcileRequestStatus `json:",inline"` + // Conditions holds the conditions for the Alert. // +optional Conditions []metav1.Condition `json:"conditions,omitempty"` @@ -88,12 +91,6 @@ type Alert struct { Status AlertStatus `json:"status,omitempty"` } -// GetStatusConditions returns a pointer to the Status.Conditions slice -// Deprecated: use GetConditions instead. -func (in *Alert) GetStatusConditions() *[]metav1.Condition { - return &in.Status.Conditions -} - // GetConditions returns the status conditions of the object. func (in *Alert) GetConditions() []metav1.Condition { return in.Status.Conditions @@ -106,7 +103,7 @@ func (in *Alert) SetConditions(conditions []metav1.Condition) { // +kubebuilder:object:root=true -// AlertList contains a list of Alert +// AlertList contains a list of Alerts. type AlertList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata,omitempty"` diff --git a/api/v1beta2/doc.go b/api/v1beta2/doc.go index 6b18367..c1a08a3 100644 --- a/api/v1beta2/doc.go +++ b/api/v1beta2/doc.go @@ -14,7 +14,7 @@ See the License for the specific language governing permissions and limitations under the License. */ -// Package v1beta2 contains API Schema definitions for the notification v1beta2 API group +// Package v1beta2 contains API Schema definitions for the notification v1beta2 API group. // +kubebuilder:object:generate=true // +groupName=notification.toolkit.fluxcd.io package v1beta2 diff --git a/api/v1beta2/groupversion_info.go b/api/v1beta2/groupversion_info.go index 8cdf68d..35598eb 100644 --- a/api/v1beta2/groupversion_info.go +++ b/api/v1beta2/groupversion_info.go @@ -22,10 +22,10 @@ import ( ) var ( - // GroupVersion is group version used to register these objects + // GroupVersion is group version used to register these objects. GroupVersion = schema.GroupVersion{Group: "notification.toolkit.fluxcd.io", Version: "v1beta2"} - // SchemeBuilder is used to add go types to the GroupVersionKind scheme + // SchemeBuilder is used to add go types to the GroupVersionKind scheme. SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion} // AddToScheme adds the types in this group-version to the given scheme. diff --git a/api/v1beta2/provider_types.go b/api/v1beta2/provider_types.go index 90c9b27..b2cc29a 100644 --- a/api/v1beta2/provider_types.go +++ b/api/v1beta2/provider_types.go @@ -24,63 +24,7 @@ import ( ) const ( - ProviderKind string = "Provider" -) - -// ProviderSpec defines the desired state of Provider -type ProviderSpec struct { - // Type of provider - // +kubebuilder:validation:Enum=slack;discord;msteams;rocket;generic;generic-hmac;github;gitlab;bitbucket;azuredevops;googlechat;webex;sentry;azureeventhub;telegram;lark;matrix;opsgenie;alertmanager;grafana;githubdispatch; - // +required - Type string `json:"type"` - - // Alert channel for this provider - // +kubebuilder:validation:MaxLength:=2048 - // +optional - Channel string `json:"channel,omitempty"` - - // Bot username for this provider - // +kubebuilder:validation:MaxLength:=2048 - // +optional - Username string `json:"username,omitempty"` - - // HTTP/S webhook address of this provider - // +kubebuilder:validation:Pattern="^(http|https)://" - // +kubebuilder:validation:MaxLength:=2048 - // +kubebuilder:validation:Optional - // +optional - Address string `json:"address,omitempty"` - - // Timeout for sending alerts to the provider. - // +kubebuilder:validation:Type=string - // +kubebuilder:validation:Pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m))+$" - // +optional - Timeout *metav1.Duration `json:"timeout,omitempty"` - - // HTTP/S address of the proxy - // +kubebuilder:validation:Pattern="^(http|https)://" - // +kubebuilder:validation:MaxLength:=2048 - // +kubebuilder:validation:Optional - // +optional - Proxy string `json:"proxy,omitempty"` - - // Secret reference containing the provider webhook URL - // using "address" as data key - // +optional - SecretRef *meta.LocalObjectReference `json:"secretRef,omitempty"` - - // CertSecretRef can be given the name of a secret containing - // a PEM-encoded CA certificate (`caFile`) - // +optional - CertSecretRef *meta.LocalObjectReference `json:"certSecretRef,omitempty"` - - // This flag tells the controller to suspend subsequent events handling. - // Defaults to false. - // +optional - Suspend bool `json:"suspend,omitempty"` -} - -const ( + ProviderKind string = "Provider" GenericProvider string = "generic" GenericHMACProvider string = "generic-hmac" SlackProvider string = "slack" @@ -104,10 +48,64 @@ const ( AlertManagerProvider string = "alertmanager" ) -// ProviderStatus defines the observed state of Provider +// ProviderSpec defines the desired state of the Provider. +type ProviderSpec struct { + // Type specifies which Provider implementation to use. + // +kubebuilder:validation:Enum=slack;discord;msteams;rocket;generic;generic-hmac;github;gitlab;bitbucket;azuredevops;googlechat;webex;sentry;azureeventhub;telegram;lark;matrix;opsgenie;alertmanager;grafana;githubdispatch; + // +required + Type string `json:"type"` + + // Channel specifies the destination channel where events should be posted. + // +kubebuilder:validation:MaxLength:=2048 + // +optional + Channel string `json:"channel,omitempty"` + + // Username specifies the name under which events are posted. + // +kubebuilder:validation:MaxLength:=2048 + // +optional + Username string `json:"username,omitempty"` + + // Address specifies the HTTP/S incoming webhook address of this Provider. + // +kubebuilder:validation:Pattern="^(http|https)://" + // +kubebuilder:validation:MaxLength:=2048 + // +kubebuilder:validation:Optional + // +optional + Address string `json:"address,omitempty"` + + // Timeout for sending alerts to the Provider. + // +kubebuilder:validation:Type=string + // +kubebuilder:validation:Pattern="^([0-9]+(\\.[0-9]+)?(ms|s|m))+$" + // +optional + Timeout *metav1.Duration `json:"timeout,omitempty"` + + // Proxy the HTTP/S address of the proxy server. + // +kubebuilder:validation:Pattern="^(http|https)://" + // +kubebuilder:validation:MaxLength:=2048 + // +kubebuilder:validation:Optional + // +optional + Proxy string `json:"proxy,omitempty"` + + // SecretRef specifies the Secret containing the authentication + // credentials for this Provider. + // +optional + SecretRef *meta.LocalObjectReference `json:"secretRef,omitempty"` + + // CertSecretRef specifies the Secret containing + // a PEM-encoded CA certificate (`caFile`). + // +optional + CertSecretRef *meta.LocalObjectReference `json:"certSecretRef,omitempty"` + + // Suspend tells the controller to suspend subsequent + // events handling for this Provider. + // +optional + Suspend bool `json:"suspend,omitempty"` +} + +// ProviderStatus defines the observed state of the Provider. type ProviderStatus struct { meta.ReconcileRequestStatus `json:",inline"` + // Conditions holds the conditions for the Provider. // +optional Conditions []metav1.Condition `json:"conditions,omitempty"` @@ -125,7 +123,7 @@ type ProviderStatus struct { // +kubebuilder:printcolumn:name="Ready",type="string",JSONPath=".status.conditions[?(@.type==\"Ready\")].status",description="" // +kubebuilder:printcolumn:name="Status",type="string",JSONPath=".status.conditions[?(@.type==\"Ready\")].message",description="" -// Provider is the Schema for the providers API +// Provider is the Schema for the providers API. type Provider struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` @@ -135,12 +133,6 @@ type Provider struct { Status ProviderStatus `json:"status,omitempty"` } -// GetStatusConditions returns a pointer to the Status.Conditions slice -// Deprecated: use GetConditions instead. -func (in *Provider) GetStatusConditions() *[]metav1.Condition { - return &in.Status.Conditions -} - // GetConditions returns the status conditions of the object. func (in *Provider) GetConditions() []metav1.Condition { return in.Status.Conditions @@ -153,7 +145,7 @@ func (in *Provider) SetConditions(conditions []metav1.Condition) { // +kubebuilder:object:root=true -// ProviderList contains a list of Provider +// ProviderList contains a list of Providers. type ProviderList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata,omitempty"` @@ -164,6 +156,7 @@ func init() { SchemeBuilder.Register(&Provider{}, &ProviderList{}) } +// GetTimeout returns the timeout value with a default of 15s for this Provider. func (in *Provider) GetTimeout() time.Duration { duration := 15 * time.Second if in.Spec.Timeout != nil { diff --git a/api/v1beta2/receiver_types.go b/api/v1beta2/receiver_types.go index 3082ea6..7465d48 100644 --- a/api/v1beta2/receiver_types.go +++ b/api/v1beta2/receiver_types.go @@ -41,7 +41,7 @@ const ( ACRReceiver string = "acr" ) -// ReceiverSpec defines the desired state of Receiver +// ReceiverSpec defines the desired state of the Receiver. type ReceiverSpec struct { // Type of webhook sender, used to determine // the validation procedure and payload deserialization. @@ -49,7 +49,7 @@ type ReceiverSpec struct { // +required Type string `json:"type"` - // A list of events to handle, + // Events specifies the list of event types to handle, // e.g. 'push' for GitHub or 'Push Hook' for GitLab. // +optional Events []string `json:"events"` @@ -58,40 +58,35 @@ type ReceiverSpec struct { // +required Resources []CrossNamespaceObjectReference `json:"resources"` - // Secret reference containing the token used - // to validate the payload authenticity + // SecretRef specifies the Secret containing the token used + // to validate the payload authenticity. // +required SecretRef meta.LocalObjectReference `json:"secretRef,omitempty"` - // This flag tells the controller to suspend subsequent events handling. - // Defaults to false. + // Suspend tells the controller to suspend subsequent + // events handling for this receiver. // +optional Suspend bool `json:"suspend,omitempty"` } -// ReceiverStatus defines the observed state of Receiver +// ReceiverStatus defines the observed state of the Receiver. type ReceiverStatus struct { meta.ReconcileRequestStatus `json:",inline"` + // Conditions holds the conditions for the Receiver. // +optional Conditions []metav1.Condition `json:"conditions,omitempty"` - // Generated webhook URL in the format + // URL is the generated incoming webhook address in the format // of '/hook/sha256sum(token+name+namespace)'. // +optional URL string `json:"url,omitempty"` - // ObservedGeneration is the last observed generation. + // ObservedGeneration is the last observed generation of the Receiver object. // +optional ObservedGeneration int64 `json:"observedGeneration,omitempty"` } -// GetStatusConditions returns a pointer to the Status.Conditions slice -// Deprecated: use GetConditions instead. -func (in *Receiver) GetStatusConditions() *[]metav1.Condition { - return &in.Status.Conditions -} - // GetConditions returns the status conditions of the object. func (in *Receiver) GetConditions() []metav1.Condition { return in.Status.Conditions @@ -117,7 +112,7 @@ func (in *Receiver) GetWebhookURL(token string) string { // +kubebuilder:printcolumn:name="Ready",type="string",JSONPath=".status.conditions[?(@.type==\"Ready\")].status",description="" // +kubebuilder:printcolumn:name="Status",type="string",JSONPath=".status.conditions[?(@.type==\"Ready\")].message",description="" -// Receiver is the Schema for the receivers API +// Receiver is the Schema for the receivers API. type Receiver struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` @@ -129,7 +124,7 @@ type Receiver struct { // +kubebuilder:object:root=true -// ReceiverList contains a list of Receiver +// ReceiverList contains a list of Receivers. type ReceiverList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata,omitempty"` diff --git a/api/v1beta2/reference_types.go b/api/v1beta2/reference_types.go index b051890..50594f3 100644 --- a/api/v1beta2/reference_types.go +++ b/api/v1beta2/reference_types.go @@ -19,22 +19,22 @@ package v1beta2 // CrossNamespaceObjectReference contains enough information to let you locate the // typed referenced object at cluster level type CrossNamespaceObjectReference struct { - // API version of the referent + // API version of the referent. // +optional APIVersion string `json:"apiVersion,omitempty"` - // Kind of the referent + // Kind of the referent. // +kubebuilder:validation:Enum=Bucket;GitRepository;Kustomization;HelmRelease;HelmChart;HelmRepository;ImageRepository;ImagePolicy;ImageUpdateAutomation;OCIRepository // +required Kind string `json:"kind,omitempty"` - // Name of the referent + // Name of the referent. // +kubebuilder:validation:MinLength=1 // +kubebuilder:validation:MaxLength=53 // +required Name string `json:"name"` - // Namespace of the referent + // Namespace of the referent. // +kubebuilder:validation:MinLength=1 // +kubebuilder:validation:MaxLength=53 // +kubebuilder:validation:Optional diff --git a/config/crd/bases/notification.toolkit.fluxcd.io_alerts.yaml b/config/crd/bases/notification.toolkit.fluxcd.io_alerts.yaml index 57983be..a9d7465 100644 --- a/config/crd/bases/notification.toolkit.fluxcd.io_alerts.yaml +++ b/config/crd/bases/notification.toolkit.fluxcd.io_alerts.yaml @@ -238,27 +238,28 @@ spec: type: object spec: description: AlertSpec defines an alerting rule for events involving a - list of objects + list of objects. properties: eventSeverity: default: info - description: Filter events based on severity, defaults to ('info'). - If set to 'info' no events will be filtered. + description: EventSeverity specifies how to filter events based on + severity. If set to 'info' no events will be filtered. enum: - info - error type: string eventSources: - description: Filter events based on the involved objects. + description: EventSources specifies how to filter events based on + the involved object kind, name and namespace. items: description: CrossNamespaceObjectReference contains enough information to let you locate the typed referenced object at cluster level properties: apiVersion: - description: API version of the referent + description: API version of the referent. type: string kind: - description: Kind of the referent + description: Kind of the referent. enum: - Bucket - GitRepository @@ -281,12 +282,12 @@ spec: are ANDed. type: object name: - description: Name of the referent + description: Name of the referent. maxLength: 53 minLength: 1 type: string namespace: - description: Namespace of the referent + description: Namespace of the referent. maxLength: 53 minLength: 1 type: string @@ -295,13 +296,14 @@ spec: type: object type: array exclusionList: - description: A list of Golang regular expressions to be used for excluding - messages. + description: ExclusionList specifies a list of Golang regular expressions + to be used for excluding messages. items: type: string type: array providerRef: - description: Send events using this provider. + description: ProviderRef specifies which Provider this Alert should + use. properties: name: description: Name of the referent. @@ -310,12 +312,13 @@ spec: - name type: object summary: - description: Short description of the impact and affected cluster. + description: Summary holds a short description of the impact and affected + cluster. maxLength: 255 type: string suspend: - description: This flag tells the controller to suspend subsequent - events dispatching. Defaults to false. + description: Suspend tells the controller to suspend subsequent events + handling for this Alert. type: boolean required: - eventSources @@ -324,9 +327,10 @@ spec: status: default: observedGeneration: -1 - description: AlertStatus defines the observed state of Alert + description: AlertStatus defines the observed state of the Alert. properties: conditions: + description: Conditions holds the conditions for the Alert. items: description: "Condition contains details for one aspect of the current state of this API Resource. --- This struct is intended for direct diff --git a/config/crd/bases/notification.toolkit.fluxcd.io_providers.yaml b/config/crd/bases/notification.toolkit.fluxcd.io_providers.yaml index f7a04d2..7ce1517 100644 --- a/config/crd/bases/notification.toolkit.fluxcd.io_providers.yaml +++ b/config/crd/bases/notification.toolkit.fluxcd.io_providers.yaml @@ -211,7 +211,7 @@ spec: name: v1beta2 schema: openAPIV3Schema: - description: Provider is the Schema for the providers API + description: Provider is the Schema for the providers API. properties: apiVersion: description: 'APIVersion defines the versioned schema of this representation @@ -226,16 +226,17 @@ spec: metadata: type: object spec: - description: ProviderSpec defines the desired state of Provider + description: ProviderSpec defines the desired state of the Provider. properties: address: - description: HTTP/S webhook address of this provider + description: Address specifies the HTTP/S incoming webhook address + of this Provider. maxLength: 2048 pattern: ^(http|https):// type: string certSecretRef: - description: CertSecretRef can be given the name of a secret containing - a PEM-encoded CA certificate (`caFile`) + description: CertSecretRef specifies the Secret containing a PEM-encoded + CA certificate (`caFile`). properties: name: description: Name of the referent. @@ -244,17 +245,18 @@ spec: - name type: object channel: - description: Alert channel for this provider + description: Channel specifies the destination channel where events + should be posted. maxLength: 2048 type: string proxy: - description: HTTP/S address of the proxy + description: Proxy the HTTP/S address of the proxy server. maxLength: 2048 pattern: ^(http|https):// type: string secretRef: - description: Secret reference containing the provider webhook URL - using "address" as data key + description: SecretRef specifies the Secret containing the authentication + credentials for this Provider. properties: name: description: Name of the referent. @@ -263,15 +265,15 @@ spec: - name type: object suspend: - description: This flag tells the controller to suspend subsequent - events handling. Defaults to false. + description: Suspend tells the controller to suspend subsequent events + handling for this Provider. type: boolean timeout: - description: Timeout for sending alerts to the provider. + description: Timeout for sending alerts to the Provider. pattern: ^([0-9]+(\.[0-9]+)?(ms|s|m))+$ type: string type: - description: Type of provider + description: Type specifies which Provider implementation to use. enum: - slack - discord @@ -296,7 +298,7 @@ spec: - githubdispatch type: string username: - description: Bot username for this provider + description: Username specifies the name under which events are posted. maxLength: 2048 type: string required: @@ -305,9 +307,10 @@ spec: status: default: observedGeneration: -1 - description: ProviderStatus defines the observed state of Provider + description: ProviderStatus defines the observed state of the Provider. properties: conditions: + description: Conditions holds the conditions for the Provider. items: description: "Condition contains details for one aspect of the current state of this API Resource. --- This struct is intended for direct diff --git a/config/crd/bases/notification.toolkit.fluxcd.io_receivers.yaml b/config/crd/bases/notification.toolkit.fluxcd.io_receivers.yaml index 590d26c..d723f6e 100644 --- a/config/crd/bases/notification.toolkit.fluxcd.io_receivers.yaml +++ b/config/crd/bases/notification.toolkit.fluxcd.io_receivers.yaml @@ -230,7 +230,7 @@ spec: name: v1beta2 schema: openAPIV3Schema: - description: Receiver is the Schema for the receivers API + description: Receiver is the Schema for the receivers API. properties: apiVersion: description: 'APIVersion defines the versioned schema of this representation @@ -245,11 +245,11 @@ spec: metadata: type: object spec: - description: ReceiverSpec defines the desired state of Receiver + description: ReceiverSpec defines the desired state of the Receiver. properties: events: - description: A list of events to handle, e.g. 'push' for GitHub or - 'Push Hook' for GitLab. + description: Events specifies the list of event types to handle, e.g. + 'push' for GitHub or 'Push Hook' for GitLab. items: type: string type: array @@ -260,10 +260,10 @@ spec: to let you locate the typed referenced object at cluster level properties: apiVersion: - description: API version of the referent + description: API version of the referent. type: string kind: - description: Kind of the referent + description: Kind of the referent. enum: - Bucket - GitRepository @@ -286,12 +286,12 @@ spec: are ANDed. type: object name: - description: Name of the referent + description: Name of the referent. maxLength: 53 minLength: 1 type: string namespace: - description: Namespace of the referent + description: Namespace of the referent. maxLength: 53 minLength: 1 type: string @@ -300,8 +300,8 @@ spec: type: object type: array secretRef: - description: Secret reference containing the token used to validate - the payload authenticity + description: SecretRef specifies the Secret containing the token used + to validate the payload authenticity. properties: name: description: Name of the referent. @@ -310,8 +310,8 @@ spec: - name type: object suspend: - description: This flag tells the controller to suspend subsequent - events handling. Defaults to false. + description: Suspend tells the controller to suspend subsequent events + handling for this receiver. type: boolean type: description: Type of webhook sender, used to determine the validation @@ -336,9 +336,10 @@ spec: status: default: observedGeneration: -1 - description: ReceiverStatus defines the observed state of Receiver + description: ReceiverStatus defines the observed state of the Receiver. properties: conditions: + description: Conditions holds the conditions for the Receiver. items: description: "Condition contains details for one aspect of the current state of this API Resource. --- This struct is intended for direct @@ -412,11 +413,13 @@ spec: be detected. type: string observedGeneration: - description: ObservedGeneration is the last observed generation. + description: ObservedGeneration is the last observed generation of + the Receiver object. format: int64 type: integer url: - description: Generated webhook URL in the format of '/hook/sha256sum(token+name+namespace)'. + description: URL is the generated incoming webhook address in the + format of '/hook/sha256sum(token+name+namespace)'. type: string type: object type: object diff --git a/docs/api/notification.md b/docs/api/notification.md index 7df6e60..d7b81e8 100644 --- a/docs/api/notification.md +++ b/docs/api/notification.md @@ -6,7 +6,7 @@

notification.toolkit.fluxcd.io/v1beta2

-

Package v1beta2 contains API Schema definitions for the notification v1beta2 API group

+

Package v1beta2 contains API Schema definitions for the notification v1beta2 API group.

Resource Types: