Merge pull request #599 from fluxcd/spec-docs-v1beta2

Author: hiddeco

api/v1beta2/artifact_types.go

@@ -23,32 +23,31 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// Artifact represents the output of a Source synchronisation.
+// Artifact represents the output of a Source reconciliation.
 type Artifact struct {
-	// Path is the relative file path of this Artifact.
-	// It can be used to locate the Artifact file in the root of the Artifact
-	// storage on the local file system of the controller managing the Source.
+	// Path is the relative file path of the Artifact. It can be used to locate
+	// the file in the root of the Artifact storage on the local file system of
+	// the controller managing the Source.
 	// +required
 	Path string `json:"path"`
 
-	// URL is the HTTP address of this artifact.
-	// It is used by the consumers of the artifacts to fetch and use the
-	// artifacts. It is expected to be resolvable from within the cluster.
+	// URL is the HTTP address of the Artifact as exposed by the controller
+	// managing the Source. It can be used to retrieve the Artifact for
+	// consumption, e.g. by another controller applying the Artifact contents.
 	// +required
 	URL string `json:"url"`
 
-	// Revision is a human readable identifier traceable in the origin source
-	// system. It can be a Git commit SHA, Git tag, a Helm index timestamp, a Helm
-	// chart version, etc.
+	// Revision is a human-readable identifier traceable in the origin source
+	// system. It can be a Git commit SHA, Git tag, a Helm chart version, etc.
 	// +optional
 	Revision string `json:"revision"`
 
-	// Checksum is the SHA256 checksum of the artifact.
+	// Checksum is the SHA256 checksum of the Artifact file.
 	// +optional
 	Checksum string `json:"checksum"`
 
-	// LastUpdateTime is the timestamp corresponding to the last update of this
-	// artifact.
+	// LastUpdateTime is the timestamp corresponding to the last update of the
+	// Artifact.
 	// +required
 	LastUpdateTime metav1.Time `json:"lastUpdateTime,omitempty"`
 
@@ -67,14 +66,14 @@ func (in *Artifact) HasRevision(revision string) bool {
 }
 
 // ArtifactDir returns the artifact dir path in the form of
-// <source-kind>/<source-namespace>/<source-name>.
+// '<kind>/<namespace>/<name>'.
 func ArtifactDir(kind, namespace, name string) string {
 	kind = strings.ToLower(kind)
 	return path.Join(kind, namespace, name)
 }
 
 // ArtifactPath returns the artifact path in the form of
-// <source-kind>/<source-namespace>/<source-name>/<artifact-filename>.
+// '<kind>/<namespace>/name>/<filename>'.
 func ArtifactPath(kind, namespace, name, filename string) string {
 	return path.Join(ArtifactDir(kind, namespace, name), filename)
 }

api/v1beta2/bucket_types.go

@@ -31,46 +31,57 @@ const (
 )
 
 const (
+	// GenericBucketProvider for any S3 API compatible storage Bucket.
 	GenericBucketProvider string = "generic"
-	AmazonBucketProvider  string = "aws"
-	GoogleBucketProvider  string = "gcp"
-	AzureBucketProvider   string = "azure"
+	// AmazonBucketProvider for an AWS S3 object storage Bucket.
+	// Provides support for retrieving credentials from the AWS EC2 service.
+	AmazonBucketProvider string = "aws"
+	// GoogleBucketProvider for a Google Cloud Storage Bucket.
+	// Provides support for authentication using a workload identity.
+	GoogleBucketProvider string = "gcp"
+	// AzureBucketProvider for an Azure Blob Storage Bucket.
+	// Provides support for authentication using a Service Principal,
+	// Managed Identity or Shared Key.
+	AzureBucketProvider string = "azure"
 )
 
-// BucketSpec defines the desired state of an S3 compatible bucket
+// BucketSpec specifies the required configuration to produce an Artifact for
+// an object storage bucket.
 type BucketSpec struct {
-	// The S3 compatible storage provider name, default ('generic').
+	// Provider of the object storage bucket.
+	// Defaults to 'generic', which expects an S3 (API) compatible object
+	// storage.
 	// +kubebuilder:validation:Enum=generic;aws;gcp;azure
 	// +kubebuilder:default:=generic
 	// +optional
 	Provider string `json:"provider,omitempty"`
 
-	// The bucket name.
+	// BucketName is the name of the object storage bucket.
 	// +required
 	BucketName string `json:"bucketName"`
 
-	// The bucket endpoint address.
+	// Endpoint is the object storage address the BucketName is located at.
 	// +required
 	Endpoint string `json:"endpoint"`
 
-	// Insecure allows connecting to a non-TLS S3 HTTP endpoint.
+	// Insecure allows connecting to a non-TLS HTTP Endpoint.
 	// +optional
 	Insecure bool `json:"insecure,omitempty"`
 
-	// The bucket region.
+	// Region of the Endpoint where the BucketName is located in.
 	// +optional
 	Region string `json:"region,omitempty"`
 
-	// The name of the secret containing authentication credentials
+	// SecretRef specifies the Secret containing authentication credentials
 	// for the Bucket.
 	// +optional
 	SecretRef *meta.LocalObjectReference `json:"secretRef,omitempty"`
 
-	// The interval at which to check for bucket updates.
+	// Interval at which to check the Endpoint for updates.
 	// +required
 	Interval metav1.Duration `json:"interval"`
 
-	// The timeout for fetch operations, defaults to 60s.
+	// Timeout for fetch operations, defaults to 60s.
 	// +kubebuilder:default="60s"
 	// +optional
 	Timeout *metav1.Duration `json:"timeout,omitempty"`
@@ -81,43 +92,48 @@ type BucketSpec struct {
 	// +optional
 	Ignore *string `json:"ignore,omitempty"`
 
-	// This flag tells the controller to suspend the reconciliation of this source.
+	// Suspend tells the controller to suspend the reconciliation of this
+	// Bucket.
 	// +optional
 	Suspend bool `json:"suspend,omitempty"`
 
-	// AccessFrom defines an Access Control List for allowing cross-namespace references to this object.
+	// AccessFrom specifies an Access Control List for allowing cross-namespace
+	// references to this object.
+	// NOTE: Not implemented, provisional as of https://github.com/fluxcd/flux2/pull/2092
 	// +optional
 	AccessFrom *acl.AccessFrom `json:"accessFrom,omitempty"`
 }
 
-// BucketStatus defines the observed state of a bucket
+// BucketStatus records the observed state of a Bucket.
 type BucketStatus struct {
-	// ObservedGeneration is the last observed generation.
+	// ObservedGeneration is the last observed generation of the Bucket object.
 	// +optional
 	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
 
 	// Conditions holds the conditions for the Bucket.
 	// +optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	// URL is the fetch link for the artifact output of the last Bucket sync.
+	// URL is the dynamic fetch link for the latest Artifact.
+	// It is provided on a "best effort" basis, and using the precise
+	// BucketStatus.Artifact data is recommended.
 	// +optional
 	URL string `json:"url,omitempty"`
 
-	// Artifact represents the output of the last successful Bucket sync.
+	// Artifact represents the last successful Bucket reconciliation.
 	// +optional
 	Artifact *Artifact `json:"artifact,omitempty"`
 
 	meta.ReconcileRequestStatus `json:",inline"`
 }
 
 const (
-	// BucketOperationSucceededReason represents the fact that the bucket listing and
-	// fetch operations succeeded.
+	// BucketOperationSucceededReason signals that the Bucket listing and fetch
+	// operations succeeded.
 	BucketOperationSucceededReason string = "BucketOperationSucceeded"
 
-	// BucketOperationFailedReason represents the fact that the bucket listing or
-	// fetch operations failed.
+	// BucketOperationFailedReason signals that the Bucket listing or fetch
+	// operations failed.
 	BucketOperationFailedReason string = "BucketOperationFailed"
 )
 
@@ -136,23 +152,11 @@ func (in Bucket) GetRequeueAfter() time.Duration {
 	return in.Spec.Interval.Duration
 }
 
-// GetInterval returns the interval at which the source is reconciled.
-// Deprecated: use GetRequeueAfter instead.
-func (in Bucket) GetInterval() metav1.Duration {
-	return in.Spec.Interval
-}
-
 // GetArtifact returns the latest artifact from the source if present in the status sub-resource.
 func (in *Bucket) GetArtifact() *Artifact {
 	return in.Status.Artifact
 }
 
-// GetStatusConditions returns a pointer to the Status.Conditions slice.
-// Deprecated: use GetConditions instead.
-func (in *Bucket) GetStatusConditions() *[]metav1.Condition {
-	return &in.Status.Conditions
-}
-
 // +genclient
 // +genclient:Namespaced
 // +kubebuilder:storageversion
@@ -163,7 +167,7 @@ func (in *Bucket) GetStatusConditions() *[]metav1.Condition {
 // +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=""
 
-// Bucket is the Schema for the buckets API
+// Bucket is the Schema for the buckets API.
 type Bucket struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -173,9 +177,8 @@ type Bucket struct {
 	Status BucketStatus `json:"status,omitempty"`
 }
 
+// BucketList contains a list of Bucket objects.
 // +kubebuilder:object:root=true
-
-// BucketList contains a list of Bucket
 type BucketList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`

api/v1beta2/condition_types.go

@@ -19,33 +19,41 @@ package v1beta2
 const SourceFinalizer = "finalizers.fluxcd.io"
 
 const (
-	// ArtifactOutdatedCondition indicates the current Artifact of the Source is outdated.
-	// This is a "negative polarity" or "abnormal-true" type, and is only present on the resource if it is True.
+	// ArtifactOutdatedCondition indicates the current Artifact of the Source
+	// is outdated.
+	// This is a "negative polarity" or "abnormal-true" type, and is only
+	// present on the resource if it is True.
 	ArtifactOutdatedCondition string = "ArtifactOutdated"
 
-	// SourceVerifiedCondition indicates the integrity of the Source has been verified. If True, the integrity check
-	// succeeded. If False, it failed. The Condition is only present on the resource if the integrity has been verified.
+	// SourceVerifiedCondition indicates the integrity of the Source has been
+	// verified. If True, the integrity check succeeded. If False, it failed.
+	// The Condition is only present on the resource if the integrity has been
+	// verified.
 	SourceVerifiedCondition string = "SourceVerified"
 
-	// FetchFailedCondition indicates a transient or persistent fetch failure of an upstream Source.
-	// If True, observations on the upstream Source revision may be impossible, and the Artifact available for the
-	// Source may be outdated.
-	// This is a "negative polarity" or "abnormal-true" type, and is only present on the resource if it is True.
+	// FetchFailedCondition indicates a transient or persistent fetch failure
+	// of an upstream Source.
+	// If True, observations on the upstream Source revision may be impossible,
+	// and the Artifact available for the Source may be outdated.
+	// This is a "negative polarity" or "abnormal-true" type, and is only
+	// present on the resource if it is True.
 	FetchFailedCondition string = "FetchFailed"
 
-	// BuildFailedCondition indicates a transient or persistent build failure of a Source's Artifact.
-	// If True, the Source can be in an ArtifactOutdatedCondition
+	// BuildFailedCondition indicates a transient or persistent build failure
+	// of a Source's Artifact.
+	// If True, the Source can be in an ArtifactOutdatedCondition.
 	BuildFailedCondition string = "BuildFailed"
 )
 
 const (
-	// URLInvalidReason represents the fact that a given source has an invalid URL.
+	// URLInvalidReason signals that a given Source has an invalid URL.
 	URLInvalidReason string = "URLInvalid"
 
-	// StorageOperationFailedReason signals a failure caused by a storage operation.
+	// StorageOperationFailedReason signals a failure caused by a storage
+	// operation.
 	StorageOperationFailedReason string = "StorageOperationFailed"
 
-	// AuthenticationFailedReason represents the fact that a given secret does not
-	// have the required fields or the provided credentials do not match.
+	// AuthenticationFailedReason signals that a Secret does not have the
+	// required fields, or the provided credentials do not match.
 	AuthenticationFailedReason string = "AuthenticationFailed"
 )