Skip to content

Commit 21670ae

Browse files
everettraveneverettraven
authored
📖 Update GoDoc comments for the ClusterExtension API (#1158)
* update API comments Signed-off-by: everettraven <everettraven@gmail.com> * regenerate CRD Signed-off-by: everettraven <everettraven@gmail.com> * fix misspellings caught by linter Signed-off-by: everettraven <everettraven@gmail.com> * regenerate CRDs after fixing misspelling Signed-off-by: everettraven <everettraven@gmail.com> * formatting Signed-off-by: everettraven <everettraven@gmail.com> --------- Signed-off-by: everettraven <everettraven@gmail.com>
1 parent 883f3dd commit 21670ae

File tree

2 files changed

+633
-54
lines changed

2 files changed

+633
-54
lines changed

‎api/v1alpha1/clusterextension_types.go

Lines changed: 295 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -46,59 +46,264 @@ const (
4646

4747
// ClusterExtensionSpec defines the desired state of ClusterExtension
4848
type ClusterExtensionSpec struct {
49+
// packageName is a reference to the name of the package to be installed
50+
// and is used to filter the content from catalogs.
51+
//
52+
// This field is required, immutable and follows the DNS label standard as defined in RFC
53+
// 1123, with a deviation in the maximum length being no more than 48
54+
// characters. This means that valid values:
55+
// - Contain no more than 48 characters
56+
// - Contain only lowercase alphanumeric characters or '-'
57+
// - Start with an alphanumeric character
58+
// - End with an alphanumeric character
59+
//
60+
// Some examples of valid values are:
61+
// - some-package
62+
// - 123-package
63+
// - 1-package-2
64+
// - somepackage
65+
//
66+
// Some examples of invalid values are:
67+
// - -some-package
68+
// - some-package-
69+
// - thisisareallylongpackagenamethatisgreaterthanthemaximumlength
70+
// - some.package
71+
//
4972
//+kubebuilder:validation:MaxLength:=48
5073
//+kubebuilder:validation:Pattern:=^[a-z0-9]+(-[a-z0-9]+)*$
5174
//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="packageName is immutable"
5275
PackageName string `json:"packageName"`
5376

54-
//+kubebuilder:validation:MaxLength:=64
55-
//+kubebuilder:validation:Pattern=`^(\s*(=||!=|>|<|>=|=>|<=|=<|~|~>|\^)\s*(v?(0|[1-9]\d*|[x|X|\*])(\.(0|[1-9]\d*|x|X|\*]))?(\.(0|[1-9]\d*|x|X|\*))?(-([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?(\+([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?)\s*)((?:\s+|,\s*|\s*\|\|\s*)(=||!=|>|<|>=|=>|<=|=<|~|~>|\^)\s*(v?(0|[1-9]\d*|x|X|\*])(\.(0|[1-9]\d*|x|X|\*))?(\.(0|[1-9]\d*|x|X|\*]))?(-([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?(\+([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?)\s*)*$`
56-
//+kubebuilder:Optional
57-
// Version is an optional semver constraint on the package version. If not specified, the latest version available of the package will be installed.
58-
// If specified, the specific version of the package will be installed so long as it is available in any of the content sources available.
59-
// Examples: 1.2.3, 1.0.0-alpha, 1.0.0-rc.1
77+
// version is an optional semver constraint (a specific version or range of versions). When unspecified, the latest version available will be installed.
78+
//
79+
// Acceptable version ranges are no longer than 64 characters.
80+
// Version ranges are composed of comma- or space-delimited values and one or
81+
// more comparison operators, known as comparison strings. Additional
82+
// comparison strings can be added using the OR operator (||).
83+
//
84+
// # Range Comparisons
85+
//
86+
// To specify a version range, you can use a comparison string like ">=3.0,
87+
// <3.6". When specifying a range, automatic updates will occur within that
88+
// range. The example comparison string means "install any version greater than
89+
// or equal to 3.0.0 but less than 3.6.0.". It also states intent that if any
90+
// upgrades are available within the version range after initial installation,
91+
// those upgrades should be automatically performed.
92+
//
93+
// # Pinned Versions
94+
//
95+
// To specify an exact version to install you can use a version range that
96+
// "pins" to a specific version. When pinning to a specific version, no
97+
// automatic updates will occur. An example of a pinned version range is
98+
// "0.6.0", which means "only install version 0.6.0 and never
99+
// upgrade from this version".
100+
//
101+
// # Basic Comparison Operators
102+
//
103+
// The basic comparison operators and their meanings are:
104+
// - "=", equal (not aliased to an operator)
105+
// - "!=", not equal
106+
// - "<", less than
107+
// - ">", greater than
108+
// - ">=", greater than OR equal to
109+
// - "<=", less than OR equal to
110+
//
111+
// # Wildcard Comparisons
112+
//
113+
// You can use the "x", "X", and "*" characters as wildcard characters in all
114+
// comparison operations. Some examples of using the wildcard characters:
115+
// - "1.2.x", "1.2.X", and "1.2.*" is equivalent to ">=1.2.0, < 1.3.0"
116+
// - ">= 1.2.x", ">= 1.2.X", and ">= 1.2.*" is equivalent to ">= 1.2.0"
117+
// - "<= 2.x", "<= 2.X", and "<= 2.*" is equivalent to "< 3"
118+
// - "x", "X", and "*" is equivalent to ">= 0.0.0"
119+
//
120+
// # Patch Release Comparisons
121+
//
122+
// When you want to specify a minor version up to the next major version you
123+
// can use the "~" character to perform patch comparisons. Some examples:
124+
// - "~1.2.3" is equivalent to ">=1.2.3, <1.3.0"
125+
// - "~1" and "~1.x" is equivalent to ">=1, <2"
126+
// - "~2.3" is equivalent to ">=2.3, <2.4"
127+
// - "~1.2.x" is equivalent to ">=1.2.0, <1.3.0"
128+
//
129+
// # Major Release Comparisons
130+
//
131+
// You can use the "^" character to make major release comparisons after a
132+
// stable 1.0.0 version is published. If there is no stable version published, // minor versions define the stability level. Some examples:
133+
// - "^1.2.3" is equivalent to ">=1.2.3, <2.0.0"
134+
// - "^1.2.x" is equivalent to ">=1.2.0, <2.0.0"
135+
// - "^2.3" is equivalent to ">=2.3, <3"
136+
// - "^2.x" is equivalent to ">=2.0.0, <3"
137+
// - "^0.2.3" is equivalent to ">=0.2.3, <0.3.0"
138+
// - "^0.2" is equivalent to ">=0.2.0, <0.3.0"
139+
// - "^0.0.3" is equvalent to ">=0.0.3, <0.0.4"
140+
// - "^0.0" is equivalent to ">=0.0.0, <0.1.0"
141+
// - "^0" is equivalent to ">=0.0.0, <1.0.0"
142+
//
143+
// # OR Comparisons
144+
// You can use the "||" character to represent an OR operation in the version
145+
// range. Some examples:
146+
// - ">=1.2.3, <2.0.0 || >3.0.0"
147+
// - "^0 || ^3 || ^5"
60148
//
61149
// For more information on semver, please see https://semver.org/
150+
//
151+
//+kubebuilder:validation:MaxLength:=64
152+
//+kubebuilder:validation:Pattern=`^(\s*(=||!=|>|<|>=|=>|<=|=<|~|~>|\^)\s*(v?(0|[1-9]\d*|[x|X|\*])(\.(0|[1-9]\d*|x|X|\*]))?(\.(0|[1-9]\d*|x|X|\*))?(-([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?(\+([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?)\s*)((?:\s+|,\s*|\s*\|\|\s*)(=||!=|>|<|>=|=>|<=|=<|~|~>|\^)\s*(v?(0|[1-9]\d*|x|X|\*])(\.(0|[1-9]\d*|x|X|\*))?(\.(0|[1-9]\d*|x|X|\*]))?(-([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?(\+([0-9A-Za-z\-]+(\.[0-9A-Za-z\-]+)*))?)\s*)*$`
153+
//+optional
62154
Version string `json:"version,omitempty"`
63155

156+
// channel is an optional reference to a channel belonging to
157+
// the package specified in the packageName field.
158+
//
159+
// A "channel" is a package author defined stream of updates for an extension.
160+
//
161+
// When specified, it is used to constrain the set of installable bundles and
162+
// the automated upgrade path. This constraint is an AND operation with the
163+
// version field. For example:
164+
// - Given channel is set to "foo"
165+
// - Given version is set to ">=1.0.0, <1.5.0"
166+
// - Only bundles that exist in channel "foo" AND satisfy the version range comparison will be considered installable
167+
// - Automatic upgrades will be constrained to upgrade edges defined by the selected channel
168+
//
169+
// When unspecified, upgrade edges across all channels will be used to identify valid automatic upgrade paths.
170+
//
171+
// This field follows the DNS subdomain name standard as defined in RFC
172+
// 1123, with a deviation in the maximum length being no more than 48
173+
// characters. This means that valid values:
174+
// - Contain no more than 48 characters
175+
// - Contain only lowercase alphanumeric characters, '-', or '.'
176+
// - Start with an alphanumeric character
177+
// - End with an alphanumeric character
178+
//
179+
// Some examples of valid values are:
180+
// - 1.1.x
181+
// - alpha
182+
// - stable
183+
// - stable-v1
184+
// - v1-stable
185+
// - dev-preview
186+
// - preview
187+
// - community
188+
//
189+
// Some examples of invalid values are:
190+
// - -some-channel
191+
// - some-channel-
192+
// - thisisareallylongchannelnamethatisgreaterthanthemaximumlength
193+
//
64194
//+kubebuilder:validation:MaxLength:=48
65195
//+kubebuilder:validation:Pattern:=^[a-z0-9]+([\.-][a-z0-9]+)*$
66-
// Channel constraint definition
196+
//+optional
67197
Channel string `json:"channel,omitempty"`
68198

69-
//+kubebuilder:optional
70-
// +optional
71-
// CatalogSelector by label
199+
// catalogSelector is an optional field that can be used
200+
// to filter the set of ClusterCatalogs used in the bundle
201+
// selection process.
202+
//
203+
// When unspecified, all ClusterCatalogs will be used in
204+
// the bundle selection process.
205+
//
206+
//+optional
72207
CatalogSelector metav1.LabelSelector `json:"catalogSelector,omitempty"`
73208

209+
// upgradeConstraintPolicy is an optional field that controls whether
210+
// the upgrade path(s) defined in the catalog are enforced for the package
211+
// referenced in the packageName field.
212+
//
213+
// Allowed values are: ["Enforce", "Ignore"].
214+
//
215+
// When this field is set to "Enforce", automatic upgrades will only occur
216+
// when upgrade constraints specified by the package author are met.
217+
//
218+
// When this field is set to "Ignore", the upgrade constraints specified by
219+
// the package author are ignored. This allows for upgrades and downgrades to
220+
// any version of the package. This is considered a dangerous operation as it
221+
// can lead to unknown and potentially disastrous outcomes, such as data
222+
// loss. It is assumed that users have independently verified changes when
223+
// using this option.
224+
//
225+
// If unspecified, the default value is "Enforce".
226+
//
74227
//+kubebuilder:validation:Enum:=Enforce;Ignore
75228
//+kubebuilder:default:=Enforce
76-
//+kubebuilder:Optional
77-
//
78-
// Defines the policy for how to handle upgrade constraints
229+
//+optional
79230
UpgradeConstraintPolicy UpgradeConstraintPolicy `json:"upgradeConstraintPolicy,omitempty"`
80231

232+
// installNamespace is a reference to the Namespace in which the bundle of
233+
// content for the package referenced in the packageName field will be applied.
234+
// The bundle may contain cluster-scoped resources or resources that are
235+
// applied to other Namespaces. This Namespace is expected to exist.
236+
//
237+
// installNamespace is required, immutable, and follows the DNS label standard
238+
// as defined in RFC 1123. This means that valid values:
239+
// - Contain no more than 63 characters
240+
// - Contain only lowercase alphanumeric characters or '-'
241+
// - Start with an alphanumeric character
242+
// - End with an alphanumeric character
243+
//
244+
// Some examples of valid values are:
245+
// - some-namespace
246+
// - 123-namespace
247+
// - 1-namespace-2
248+
// - somenamespace
249+
//
250+
// Some examples of invalid values are:
251+
// - -some-namespace
252+
// - some-namespace-
253+
// - thisisareallylongnamespacenamethatisgreaterthanthemaximumlength
254+
// - some.namespace
255+
//
81256
//+kubebuilder:validation:Pattern:=^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
82257
//+kubebuilder:validation:MaxLength:=63
83258
//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="installNamespace is immutable"
84-
//
85-
// installNamespace is the namespace where the bundle should be installed. However, note that
86-
// the bundle may contain resources that are cluster-scoped or that are
87-
// installed in a different namespace. This namespace is expected to exist.
88259
InstallNamespace string `json:"installNamespace"`
89260

90-
//+kubebuilder:Optional
91-
// Preflight defines the configuration of preflight checks.
261+
// preflight is an optional field that can be used to configure the preflight checks run before installation or upgrade of the content for the package specified in the packageName field.
262+
//
263+
// When specified, it overrides the default configuration of the preflight checks that are required to execute successfully during an install/upgrade operation.
264+
//
265+
// When not specified, the default configuration for each preflight check will be used.
266+
//
267+
//+optional
92268
Preflight *PreflightConfig `json:"preflight,omitempty"`
93269

94-
// ServiceAccount is used to install and manage resources.
95-
// The service account is expected to exist in the InstallNamespace.
270+
// serviceAccount is a required reference to a ServiceAccount that exists
271+
// in the installNamespace. The provided ServiceAccount is used to install and
272+
// manage the content for the package specified in the packageName field.
273+
//
274+
// In order to successfully install and manage the content for the package,
275+
// the ServiceAccount provided via this field should be configured with the
276+
// appropriate permissions to perform the necessary operations on all the
277+
// resources that are included in the bundle of content being applied.
96278
ServiceAccount ServiceAccountReference `json:"serviceAccount"`
97279
}
98280

99281
// ServiceAccountReference references a serviceAccount.
100282
type ServiceAccountReference struct {
101-
// name is the metadata.name of the referenced serviceAccount object.
283+
// name is a required, immutable reference to the name of the ServiceAccount
284+
// to be used for installation and management of the content for the package
285+
// specified in the packageName field.
286+
//
287+
// This ServiceAccount is expected to exist in the installNamespace.
288+
//
289+
// This field follows the DNS subdomain name standard as defined in RFC
290+
// 1123. This means that valid values:
291+
// - Contain no more than 253 characters
292+
// - Contain only lowercase alphanumeric characters, '-', or '.'
293+
// - Start with an alphanumeric character
294+
// - End with an alphanumeric character
295+
//
296+
// Some examples of valid values are:
297+
// - some-serviceaccount
298+
// - 123-serviceaccount
299+
// - 1-serviceaccount-2
300+
// - someserviceaccount
301+
// - some.serviceaccount
302+
//
303+
// Some examples of invalid values are:
304+
// - -some-serviceaccount
305+
// - some-serviceaccount-
306+
//
102307
//+kubebuilder:validation:MaxLength:=253
103308
//+kubebuilder:validation:Pattern:=^[a-z0-9]+([.|-][a-z0-9]+)*$
104309
//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="name is immutable"
@@ -107,17 +312,34 @@ type ServiceAccountReference struct {
107312

108313
// PreflightConfig holds the configuration for the preflight checks.
109314
type PreflightConfig struct {
110-
//+kubebuilder:Required
111-
// CRDUpgradeSafety holds necessary configuration for the CRD Upgrade Safety preflight checks.
315+
// crdUpgradeSafety is used to configure the CRD Upgrade Safety pre-flight
316+
// checks that run prior to upgrades of installed content.
317+
//
318+
// The CRD Upgrade Safety pre-flight check safeguards from unintended
319+
// consequences of upgrading a CRD, such as data loss.
320+
//
321+
// This field is required if the spec.preflight field is specified.
112322
CRDUpgradeSafety *CRDUpgradeSafetyPreflightConfig `json:"crdUpgradeSafety"`
113323
}
114324

115325
// CRDUpgradeSafetyPreflightConfig is the configuration for CRD upgrade safety preflight check.
116326
type CRDUpgradeSafetyPreflightConfig struct {
117-
//+kubebuilder:Required
327+
// policy is used to configure the state of the CRD Upgrade Safety pre-flight check.
328+
//
329+
// This field is required when the spec.preflight.crdUpgradeSafety field is
330+
// specified.
331+
//
332+
// Allowed values are ["Enabled", "Disabled"]. The default value is "Enabled".
333+
//
334+
// When set to "Disabled", the CRD Upgrade Safety pre-flight check will be skipped
335+
// when performing an upgrade operation. This should be used with caution as
336+
// unintended consequences such as data loss can occur.
337+
//
338+
// When set to "Enabled", the CRD Upgrade Safety pre-flight check will be run when
339+
// performing an upgrade operation.
340+
//
118341
//+kubebuilder:validation:Enum:="Enabled";"Disabled"
119342
//+kubebuilder:default:=Enabled
120-
// policy represents the state of the CRD upgrade safety preflight check. Allowed values are "Enabled", and Disabled".
121343
Policy CRDUpgradeSafetyPolicy `json:"policy"`
122344
}
123345

@@ -180,19 +402,60 @@ func init() {
180402
}
181403

182404
type BundleMetadata struct {
183-
Name string `json:"name"`
405+
// name is a required field and is a reference
406+
// to the name of a bundle
407+
Name string `json:"name"`
408+
// version is a required field and is a reference
409+
// to the version that this bundle represents
184410
Version string `json:"version"`
185411
}
186412

187413
// ClusterExtensionStatus defines the observed state of ClusterExtension.
188414
type ClusterExtensionStatus struct {
189-
// InstalledBundle should only be modified when a new bundle is successfully installed. This ensures that if there
190-
// is a previously successfully installed a bundle, and an upgrade fails, it is still communicated that there is
191-
// still a bundle that is currently installed and owned by the ClusterExtension.
192-
// +optional
415+
// installedBundle is a representation of the currently installed bundle.
416+
//
417+
// A "bundle" is a versioned set of content that represents the resources that
418+
// need to be applied to a cluster to install a package.
419+
//
420+
// This field is only updated once a bundle has been successfully installed and
421+
// once set will only be updated when a new version of the bundle has
422+
// successfully replaced the currently installed version.
423+
//
424+
//+optional
193425
InstalledBundle *BundleMetadata `json:"installedBundle,omitempty"`
194-
// +optional
426+
427+
// resolvedBundle is a representation of the bundle that was identified during
428+
// resolution to meet all installation/upgrade constraints and is slated to be
429+
// installed or upgraded to.
430+
//
431+
//+optional
195432
ResolvedBundle *BundleMetadata `json:"resolvedBundle,omitempty"`
433+
434+
// conditions is a representation of the current state for this ClusterExtension.
435+
// The status is represented by a set of "conditions".
436+
//
437+
// Each condition is generally structured in the following format:
438+
// - Type: a string representation of the condition type. More or less the condition "name".
439+
// - Status: a string representation of the state of the condition. Can be one of ["True", "False", "Unknown"].
440+
// - Reason: a string representation of the reason for the current state of the condition. Typically useful for building automation around particular Type+Reason combinations.
441+
// - Message: a human readable message that further elaborates on the state of the condition
442+
//
443+
// The current set of condition types are:
444+
// - "Installed", represents whether or not the package referenced in the spec.packageName field has been installed
445+
// - "Resolved", represents whether or not a bundle was found that satisfies the selection criteria outlined in the spec
446+
// - "Deprecated", represents an aggregation of the PackageDeprecated, ChannelDeprecated, and BundleDeprecated condition types.
447+
// - "PackageDeprecated", represents whether or not the package specified in the spec.packageName field has been deprecated
448+
// - "ChannelDeprecated", represents whether or not the channel specified in spec.channel has been deprecated
449+
// - "BundleDeprecated", represents whether or not the bundle installed is deprecated
450+
// - "Unpacked", represents whether or not the bundle contents have been successfully unpacked
451+
//
452+
// The current set of reasons are:
453+
// - "ResolutionFailed", this reason is set on the "Resolved" condition when an error has occurred during resolution.
454+
// - "InstallationFailed", this reason is set on the "Installed" condition when an error has occurred during installation
455+
// - "Success", this reason is set on the "Resolved" and "Installed" conditions when resolution and installation/upgrading is successful
456+
// - "UnpackSuccess", this reason is set on the "Unpacked" condition when unpacking a bundle's content is successful
457+
// - "UnpackFailed", this reason is set on the "Unpacked" condition when an error has been encountered while unpacking the contents of a bundle
458+
//
196459
// +patchMergeKey=type
197460
// +patchStrategy=merge
198461
// +listType=map

0 commit comments

Comments
 (0)