Update API descriptions and messages to be consistent

darkowlzz · hiddeco · commit 45df2d76c829 · 2022-02-23T12:35:30.000+01:00
- Update v1beta2 API descriptions and reconciling messages to be
  consistent.
- Replace 'download' with 'fetch'. Since the status condition for
  download failure is called FetchFailed, using the term 'fetch' makes
  the messaging more consistent.
- Replace `BucketOperationSucceed` with `BucketOperationSucceeded` and
  generate api docs.

Signed-off-by: Sunny &lt;darkowlzz@protonmail.com&gt;
diff --git a/api/v1beta2/artifact_types.go b/api/v1beta2/artifact_types.go
@@ -23,13 +23,17 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// Artifact represents the output of a source synchronisation.
+// Artifact represents the output of a Source synchronisation.
 type Artifact struct {
-	// Path is the relative file path of this artifact.
+	// 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.
 	// +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.
 	// +required
 	URL string `json:"url"`
 
diff --git a/api/v1beta2/bucket_types.go b/api/v1beta2/bucket_types.go
@@ -69,7 +69,7 @@ type BucketSpec struct {
 	// +required
 	Interval metav1.Duration `json:"interval"`
 
-	// The timeout for download operations, defaults to 60s.
+	// The timeout for fetch operations, defaults to 60s.
 	// +kubebuilder:default="60s"
 	// +optional
 	Timeout *metav1.Duration `json:"timeout,omitempty"`
@@ -99,7 +99,7 @@ type BucketStatus struct {
 	// +optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	// URL is the download link for the artifact output of the last Bucket sync.
+	// URL is the fetch link for the artifact output of the last Bucket sync.
 	// +optional
 	URL string `json:"url,omitempty"`
 
@@ -111,12 +111,12 @@ type BucketStatus struct {
 }
 
 const (
-	// BucketOperationSucceedReason represents the fact that the bucket listing and
-	// download operations succeeded.
-	BucketOperationSucceedReason string = "BucketOperationSucceed"
+	// BucketOperationSucceededReason represents the fact that the bucket listing and
+	// fetch operations succeeded.
+	BucketOperationSucceededReason string = "BucketOperationSucceeded"
 
 	// BucketOperationFailedReason represents the fact that the bucket listing or
-	// download operations failed.
+	// fetch operations failed.
 	BucketOperationFailedReason string = "BucketOperationFailed"
 )
 
diff --git a/api/v1beta2/gitrepository_types.go b/api/v1beta2/gitrepository_types.go
@@ -168,7 +168,7 @@ type GitRepositoryStatus struct {
 	// +optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	// URL is the download link for the artifact output of the last repository sync.
+	// URL is the fetch link for the artifact output of the last repository sync.
 	// +optional
 	URL string `json:"url,omitempty"`
 
diff --git a/api/v1beta2/helmchart_types.go b/api/v1beta2/helmchart_types.go
@@ -127,7 +127,7 @@ type HelmChartStatus struct {
 	// +optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	// URL is the download link for the last chart pulled.
+	// URL is the fetch link for the last chart pulled.
 	// +optional
 	URL string `json:"url,omitempty"`
 
diff --git a/api/v1beta2/helmrepository_types.go b/api/v1beta2/helmrepository_types.go
@@ -61,7 +61,7 @@ type HelmRepositorySpec struct {
 	// +required
 	Interval metav1.Duration `json:"interval"`
 
-	// The timeout of index downloading, defaults to 60s.
+	// The timeout of index fetching, defaults to 60s.
 	// +kubebuilder:default:="60s"
 	// +optional
 	Timeout *metav1.Duration `json:"timeout,omitempty"`
@@ -85,7 +85,7 @@ type HelmRepositoryStatus struct {
 	// +optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	// URL is the download link for the last index fetched.
+	// URL is the fetch link for the last index fetched.
 	// +optional
 	URL string `json:"url,omitempty"`
 
diff --git a/config/crd/bases/source.toolkit.fluxcd.io_buckets.yaml b/config/crd/bases/source.toolkit.fluxcd.io_buckets.yaml
@@ -356,7 +356,7 @@ spec:
                 type: boolean
               timeout:
                 default: 60s
-                description: The timeout for download operations, defaults to 60s.
+                description: The timeout for fetch operations, defaults to 60s.
                 type: string
             required:
             - bucketName
@@ -381,15 +381,20 @@ spec:
                     format: date-time
                     type: string
                   path:
-                    description: Path is the relative file path of this artifact.
+                    description: 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.
                     type: string
                   revision:
                     description: 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.
                     type: string
                   url:
-                    description: URL is the HTTP address of this artifact.
+                    description: 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.
                     type: string
                 required:
                 - path
@@ -475,7 +480,7 @@ spec:
                 format: int64
                 type: integer
               url:
-                description: URL is the download link for the artifact output of the
+                description: URL is the fetch link for the artifact output of the
                   last Bucket sync.
                 type: string
             type: object
diff --git a/config/crd/bases/source.toolkit.fluxcd.io_gitrepositories.yaml b/config/crd/bases/source.toolkit.fluxcd.io_gitrepositories.yaml
@@ -549,15 +549,20 @@ spec:
                     format: date-time
                     type: string
                   path:
-                    description: Path is the relative file path of this artifact.
+                    description: 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.
                     type: string
                   revision:
                     description: 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.
                     type: string
                   url:
-                    description: URL is the HTTP address of this artifact.
+                    description: 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.
                     type: string
                 required:
                 - path
@@ -637,7 +642,7 @@ spec:
                 description: IncludedArtifacts represents the included artifacts from
                   the last successful repository sync.
                 items:
-                  description: Artifact represents the output of a source synchronisation.
+                  description: Artifact represents the output of a Source synchronisation.
                   properties:
                     checksum:
                       description: Checksum is the SHA256 checksum of the artifact.
@@ -648,15 +653,21 @@ spec:
                       format: date-time
                       type: string
                     path:
-                      description: Path is the relative file path of this artifact.
+                      description: 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.
                       type: string
                     revision:
                       description: 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.
                       type: string
                     url:
-                      description: URL is the HTTP address of this artifact.
+                      description: 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.
                       type: string
                   required:
                   - path
@@ -673,7 +684,7 @@ spec:
                 format: int64
                 type: integer
               url:
-                description: URL is the download link for the artifact output of the
+                description: URL is the fetch link for the artifact output of the
                   last repository sync.
                 type: string
             type: object
diff --git a/config/crd/bases/source.toolkit.fluxcd.io_helmcharts.yaml b/config/crd/bases/source.toolkit.fluxcd.io_helmcharts.yaml
@@ -428,15 +428,20 @@ spec:
                     format: date-time
                     type: string
                   path:
-                    description: Path is the relative file path of this artifact.
+                    description: 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.
                     type: string
                   revision:
                     description: 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.
                     type: string
                   url:
-                    description: URL is the HTTP address of this artifact.
+                    description: 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.
                     type: string
                 required:
                 - path
@@ -530,7 +535,7 @@ spec:
                   of the Source reference.
                 type: string
               url:
-                description: URL is the download link for the last chart pulled.
+                description: URL is the fetch link for the last chart pulled.
                 type: string
             type: object
         type: object
diff --git a/config/crd/bases/source.toolkit.fluxcd.io_helmrepositories.yaml b/config/crd/bases/source.toolkit.fluxcd.io_helmrepositories.yaml
@@ -326,7 +326,7 @@ spec:
                 type: boolean
               timeout:
                 default: 60s
-                description: The timeout of index downloading, defaults to 60s.
+                description: The timeout of index fetching, defaults to 60s.
                 type: string
               url:
                 description: The Helm repository URL, a valid URL contains at least
@@ -354,15 +354,20 @@ spec:
                     format: date-time
                     type: string
                   path:
-                    description: Path is the relative file path of this artifact.
+                    description: 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.
                     type: string
                   revision:
                     description: 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.
                     type: string
                   url:
-                    description: URL is the HTTP address of this artifact.
+                    description: 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.
                     type: string
                 required:
                 - path
@@ -448,7 +453,7 @@ spec:
                 format: int64
                 type: integer
               url:
-                description: URL is the download link for the last index fetched.
+                description: URL is the fetch link for the last index fetched.
                 type: string
             type: object
         type: object
diff --git a/controllers/bucket_controller.go b/controllers/bucket_controller.go
@@ -196,7 +196,7 @@ func (r *BucketReconciler) Reconcile(ctx context.Context, req ctrl.Request) (res
 // error.
 func (r *BucketReconciler) reconcile(ctx context.Context, obj *sourcev1.Bucket, reconcilers []bucketReconcilerFunc) (sreconcile.Result, error) {
 	if obj.Generation != obj.Status.ObservedGeneration {
-		conditions.MarkReconciling(obj, "NewGeneration", "reconciling new generation %d", obj.Generation)
+		conditions.MarkReconciling(obj, "NewGeneration", "reconciling new object generation (%d)", obj.Generation)
 	}
 
 	var artifact sourcev1.Artifact
@@ -432,14 +432,14 @@ func (r *BucketReconciler) reconcileMinioSource(ctx context.Context, obj *source
 		})
 		if err = group.Wait(); err != nil {
 			e := &serror.Event{
-				Err:    fmt.Errorf("download from bucket '%s' failed: %w", obj.Spec.BucketName, err),
+				Err:    fmt.Errorf("fetch from bucket '%s' failed: %w", obj.Spec.BucketName, err),
 				Reason: sourcev1.BucketOperationFailedReason,
 			}
 			conditions.MarkTrue(obj, sourcev1.FetchFailedCondition, sourcev1.BucketOperationFailedReason, e.Err.Error())
 			return sreconcile.ResultEmpty, e
 		}
-		r.eventLogf(ctx, obj, events.EventTypeTrace, sourcev1.BucketOperationSucceedReason,
-			"downloaded %d files with revision '%s' from '%s'", len(index), revision, obj.Spec.BucketName)
+		r.eventLogf(ctx, obj, events.EventTypeTrace, sourcev1.BucketOperationSucceededReason,
+			"fetched %d files with revision '%s' from '%s'", len(index), revision, obj.Spec.BucketName)
 	}
 	conditions.Delete(obj, sourcev1.FetchFailedCondition)
 
@@ -587,14 +587,14 @@ func (r *BucketReconciler) reconcileGCPSource(ctx context.Context, obj *sourcev1
 		})
 		if err = group.Wait(); err != nil {
 			e := &serror.Event{
-				Err:    fmt.Errorf("download from bucket '%s' failed: %w", obj.Spec.BucketName, err),
+				Err:    fmt.Errorf("fetch from bucket '%s' failed: %w", obj.Spec.BucketName, err),
 				Reason: sourcev1.BucketOperationFailedReason,
 			}
 			conditions.MarkTrue(obj, sourcev1.FetchFailedCondition, sourcev1.BucketOperationFailedReason, e.Err.Error())
 			return sreconcile.ResultEmpty, e
 		}
-		r.eventLogf(ctx, obj, events.EventTypeTrace, sourcev1.BucketOperationSucceedReason,
-			"downloaded %d files from bucket '%s'", len(index), obj.Spec.BucketName)
+		r.eventLogf(ctx, obj, events.EventTypeTrace, sourcev1.BucketOperationSucceededReason,
+			"fetched %d files from bucket '%s'", len(index), obj.Spec.BucketName)
 	}
 	conditions.Delete(obj, sourcev1.FetchFailedCondition)
 
diff --git a/controllers/gitrepository_controller.go b/controllers/gitrepository_controller.go
@@ -204,7 +204,7 @@ func (r *GitRepositoryReconciler) Reconcile(ctx context.Context, req ctrl.Reques
 // error.
 func (r *GitRepositoryReconciler) reconcile(ctx context.Context, obj *sourcev1.GitRepository, reconcilers []gitRepoReconcilerFunc) (sreconcile.Result, error) {
 	if obj.Generation != obj.Status.ObservedGeneration {
-		conditions.MarkReconciling(obj, "NewGeneration", "reconciling new generation %d", obj.Generation)
+		conditions.MarkReconciling(obj, "NewGeneration", "reconciling new object generation (%d)", obj.Generation)
 	}
 
 	var artifact sourcev1.Artifact
diff --git a/controllers/helmchart_controller.go b/controllers/helmchart_controller.go
@@ -227,7 +227,7 @@ func (r *HelmChartReconciler) Reconcile(ctx context.Context, req ctrl.Request) (
 // produces an error.
 func (r *HelmChartReconciler) reconcile(ctx context.Context, obj *sourcev1.HelmChart, reconcilers []helmChartReconcilerFunc) (sreconcile.Result, error) {
 	if obj.Generation != obj.Status.ObservedGeneration {
-		conditions.MarkReconciling(obj, "NewGeneration", "reconciling new generation %d", obj.Generation)
+		conditions.MarkReconciling(obj, "NewGeneration", "reconciling new object generation (%d)", obj.Generation)
 	}
 
 	// Run the sub-reconcilers and build the result of reconciliation.
diff --git a/controllers/helmchart_controller_test.go b/controllers/helmchart_controller_test.go
@@ -1376,7 +1376,7 @@ func TestHelmChartReconciler_reconcileSubRecs(t *testing.T) {
 			wantResult: sreconcile.ResultSuccess,
 			wantErr:    false,
 			assertConditions: []metav1.Condition{
-				*conditions.TrueCondition(meta.ReconcilingCondition, "NewGeneration", "reconciling new generation 3"),
+				*conditions.TrueCondition(meta.ReconcilingCondition, "NewGeneration", "reconciling new object generation (3)"),
 			},
 		},
 		{
diff --git a/controllers/helmrepository_controller.go b/controllers/helmrepository_controller.go
@@ -192,7 +192,7 @@ func (r *HelmRepositoryReconciler) Reconcile(ctx context.Context, req ctrl.Reque
 // result with the shortest requeue period.
 func (r *HelmRepositoryReconciler) reconcile(ctx context.Context, obj *sourcev1.HelmRepository, reconcilers []helmRepoReconcilerFunc) (sreconcile.Result, error) {
 	if obj.Generation != obj.Status.ObservedGeneration {
-		conditions.MarkReconciling(obj, "NewGeneration", "reconciling new generation %d", obj.Generation)
+		conditions.MarkReconciling(obj, "NewGeneration", "reconciling new object generation (%d)", obj.Generation)
 	}
 
 	var chartRepo repository.ChartRepository
@@ -328,7 +328,7 @@ func (r *HelmRepositoryReconciler) reconcileSource(ctx context.Context, obj *sou
 	checksum, err := newChartRepo.CacheIndex()
 	if err != nil {
 		e := &serror.Event{
-			Err:    fmt.Errorf("failed to download Helm repository index: %w", err),
+			Err:    fmt.Errorf("failed to fetch Helm repository index: %w", err),
 			Reason: meta.FailedReason,
 		}
 		conditions.MarkTrue(obj, sourcev1.FetchFailedCondition, meta.FailedReason, e.Err.Error())
diff --git a/controllers/helmrepository_controller_test.go b/controllers/helmrepository_controller_test.go
@@ -660,7 +660,7 @@ func TestHelmRepositoryReconciler_reconcileSubRecs(t *testing.T) {
 			wantResult: sreconcile.ResultSuccess,
 			wantErr:    false,
 			assertConditions: []metav1.Condition{
-				*conditions.TrueCondition(meta.ReconcilingCondition, "NewGeneration", "reconciling new generation 3"),
+				*conditions.TrueCondition(meta.ReconcilingCondition, "NewGeneration", "reconciling new object generation (3)"),
 			},
 		},
 		{
diff --git a/docs/api/source.md b/docs/api/source.md
