Update API descriptions and messages to be consistent

- 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 <darkowlzz@protonmail.com>

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"`
 

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
+	// BucketOperationSucceededReason represents the fact that the bucket listing and
-	// download operations succeeded.
+	// fetch operations succeeded.
-	BucketOperationSucceedReason string = "BucketOperationSucceed"
+	BucketOperationSucceededReason string = "BucketOperationSucceeded"
 
 	// BucketOperationFailedReason represents the fact that the bucket listing or
-	// download operations failed.
+	// fetch operations failed.
 	BucketOperationFailedReason string = "BucketOperationFailed"
 )
 

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"`
 

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"`
 

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"`
 

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,7 +381,10 @@ 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
@@ -389,7 +392,9 @@ spec:
                       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

config/crd/bases/source.toolkit.fluxcd.io_gitrepositories.yaml

@@ -549,7 +549,10 @@ 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
@@ -557,7 +560,9 @@ spec:
                       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,7 +653,10 @@ 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
@@ -656,7 +664,10 @@ spec:
                         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

config/crd/bases/source.toolkit.fluxcd.io_helmcharts.yaml

@@ -428,7 +428,10 @@ 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
@@ -436,7 +439,9 @@ spec:
                       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

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,7 +354,10 @@ 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
@@ -362,7 +365,9 @@ spec:
                       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

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,
+		r.eventLogf(ctx, obj, events.EventTypeTrace, sourcev1.BucketOperationSucceededReason,
-			"downloaded %d files with revision '%s' from '%s'", len(index), revision, obj.Spec.BucketName)
+			"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,
+		r.eventLogf(ctx, obj, events.EventTypeTrace, sourcev1.BucketOperationSucceededReason,
-			"downloaded %d files from bucket '%s'", len(index), obj.Spec.BucketName)
+			"fetched %d files from bucket '%s'", len(index), obj.Spec.BucketName)
 	}
 	conditions.Delete(obj, sourcev1.FetchFailedCondition)
 

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

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.

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)"),
 			},
 		},
 		{

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())

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)"),
 			},
 		},
 		{

docs/api/source.md

@@ -171,7 +171,7 @@ Kubernetes meta/v1.Duration
 </td>
 <td>
 <em>(Optional)</em>
-<p>The timeout for download operations, defaults to 60s.</p>
+<p>The timeout for fetch operations, defaults to 60s.</p>
 </td>
 </tr>
 <tr>
@@ -797,7 +797,7 @@ Kubernetes meta/v1.Duration
 </td>
 <td>
 <em>(Optional)</em>
-<p>The timeout of index downloading, defaults to 60s.</p>
+<p>The timeout of index fetching, defaults to 60s.</p>
 </td>
 </tr>
 <tr>
@@ -854,7 +854,7 @@ HelmRepositoryStatus
 <a href="#source.toolkit.fluxcd.io/v1beta2.HelmChartStatus">HelmChartStatus</a>, 
 <a href="#source.toolkit.fluxcd.io/v1beta2.HelmRepositoryStatus">HelmRepositoryStatus</a>)
 </p>
-<p>Artifact represents the output of a source synchronisation.</p>
+<p>Artifact represents the output of a Source synchronisation.</p>
 <div class="md-typeset__scrollwrap">
 <div class="md-typeset__table">
 <table>
@@ -873,7 +873,9 @@ string
 </em>
 </td>
 <td>
-<p>Path is the relative file path of this artifact.</p>
+<p>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.</p>
 </td>
 </tr>
 <tr>
@@ -884,7 +886,9 @@ string
 </em>
 </td>
 <td>
-<p>URL is the HTTP address of this artifact.</p>
+<p>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.</p>
 </td>
 </tr>
 <tr>
@@ -1045,7 +1049,7 @@ Kubernetes meta/v1.Duration
 </td>
 <td>
 <em>(Optional)</em>
-<p>The timeout for download operations, defaults to 60s.</p>
+<p>The timeout for fetch operations, defaults to 60s.</p>
 </td>
 </tr>
 <tr>
@@ -1144,7 +1148,7 @@ string
 </td>
 <td>
 <em>(Optional)</em>
-<p>URL is the download link for the artifact output of the last Bucket sync.</p>
+<p>URL is the fetch link for the artifact output of the last Bucket sync.</p>
 </td>
 </tr>
 <tr>
@@ -1543,7 +1547,7 @@ string
 </td>
 <td>
 <em>(Optional)</em>
-<p>URL is the download link for the artifact output of the last repository sync.</p>
+<p>URL is the fetch link for the artifact output of the last repository sync.</p>
 </td>
 </tr>
 <tr>
@@ -1811,6 +1815,32 @@ int64
 </tr>
 <tr>
 <td>
+<code>observedSourceArtifactRevision</code><br>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>ObservedSourceArtifactRevision is the last observed Artifact.Revision
+of the Source reference.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>observedChartName</code><br>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>ObservedChartName is the last observed chart name as defined by the
+resolved chart reference.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>conditions</code><br>
 <em>
 <a href="https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Condition">
@@ -1832,7 +1862,7 @@ string
 </td>
 <td>
 <em>(Optional)</em>
-<p>URL is the download link for the last chart pulled.</p>
+<p>URL is the fetch link for the last chart pulled.</p>
 </td>
 </tr>
 <tr>
@@ -1956,7 +1986,7 @@ Kubernetes meta/v1.Duration
 </td>
 <td>
 <em>(Optional)</em>
-<p>The timeout of index downloading, defaults to 60s.</p>
+<p>The timeout of index fetching, defaults to 60s.</p>
 </td>
 </tr>
 <tr>
@@ -2041,7 +2071,7 @@ string
 </td>
 <td>
 <em>(Optional)</em>
-<p>URL is the download link for the last index fetched.</p>
+<p>URL is the fetch link for the last index fetched.</p>
 </td>
 </tr>
 <tr>