Document HelmRepository API v1beta2 spec

Signed-off-by: Hidde Beydals <hello@hidde.co>

Author: hiddeco

api/v1beta2/helmrepository_types.go

@@ -28,82 +28,86 @@ import (
 const (
 	// HelmRepositoryKind is the string representation of a HelmRepository.
 	HelmRepositoryKind = "HelmRepository"
-	// HelmRepositoryURLIndexKey is the key to use for indexing HelmRepository
-	// resources by their HelmRepositorySpec.URL.
+	// HelmRepositoryURLIndexKey is the key used for indexing HelmRepository
+	// objects by their HelmRepositorySpec.URL.
 	HelmRepositoryURLIndexKey = ".metadata.helmRepositoryURL"
 )
 
-// HelmRepositorySpec defines the reference to a Helm repository.
+// HelmRepositorySpec specifies the required configuration to produce an
+// Artifact for a Helm repository index YAML.
 type HelmRepositorySpec struct {
-	// The Helm repository URL, a valid URL contains at least a protocol and host.
+	// URL of the Helm repository, a valid URL contains at least a protocol and
+	// host.
 	// +required
 	URL string `json:"url"`
 
-	// The name of the secret containing authentication credentials for the Helm
-	// repository.
-	// For HTTP/S basic auth the secret must contain username and
-	// password fields.
-	// For TLS the secret must contain a certFile and keyFile, and/or
-	// caCert fields.
+	// SecretRef specifies the Secret containing authentication credentials
+	// for the HelmRepository.
+	// For HTTP/S basic auth the secret must contain 'username' and 'password'
+	// fields.
+	// For TLS the secret must contain a 'certFile' and 'keyFile', and/or
+	// 'caCert' fields.
 	// +optional
 	SecretRef *meta.LocalObjectReference `json:"secretRef,omitempty"`
 
-	// PassCredentials allows the credentials from the SecretRef to be passed on to
-	// a host that does not match the host as defined in URL.
-	// This may be required if the host of the advertised chart URLs in the index
-	// differ from the defined URL.
-	// Enabling this should be done with caution, as it can potentially result in
-	// credentials getting stolen in a MITM-attack.
+	// PassCredentials allows the credentials from the SecretRef to be passed
+	// on to a host that does not match the host as defined in URL.
+	// This may be required if the host of the advertised chart URLs in the
+	// index differ from the defined URL.
+	// Enabling this should be done with caution, as it can potentially result
+	// in credentials getting stolen in a MITM-attack.
 	// +optional
 	PassCredentials bool `json:"passCredentials,omitempty"`
 
-	// The interval at which to check the upstream for updates.
+	// Interval at which to check the URL for updates.
 	// +required
 	Interval metav1.Duration `json:"interval"`
 
-	// The timeout of index fetching, defaults to 60s.
+	// Timeout of the index fetch operation, defaults to 60s.
 	// +kubebuilder:default:="60s"
 	// +optional
 	Timeout *metav1.Duration `json:"timeout,omitempty"`
 
-	// This flag tells the controller to suspend the reconciliation of this source.
+	// Suspend tells the controller to suspend the reconciliation of this
+	// HelmRepository.
 	// +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"`
 }
 
-// HelmRepositoryStatus defines the observed state of the HelmRepository.
+// HelmRepositoryStatus records the observed state of the HelmRepository.
 type HelmRepositoryStatus struct {
-	// ObservedGeneration is the last observed generation.
+	// ObservedGeneration is the last observed generation of the HelmRepository
+	// object.
 	// +optional
 	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
 
 	// Conditions holds the conditions for the HelmRepository.
 	// +optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	// URL is the fetch link for the last index fetched.
+	// URL is the dynamic fetch link for the latest Artifact.
+	// It is provided on a "best effort" basis, and using the precise
+	// HelmRepositoryStatus.Artifact data is recommended.
 	// +optional
 	URL string `json:"url,omitempty"`
 
-	// Artifact represents the output of the last successful repository sync.
+	// Artifact represents the last successful HelmRepository reconciliation.
 	// +optional
 	Artifact *Artifact `json:"artifact,omitempty"`
 
 	meta.ReconcileRequestStatus `json:",inline"`
 }
 
 const (
-	// IndexationFailedReason represents the fact that the indexation of the given
-	// Helm repository failed.
+	// IndexationFailedReason signals that the HelmRepository index fetch
+	// failed.
 	IndexationFailedReason string = "IndexationFailed"
-
-	// IndexationSucceededReason represents the fact that the indexation of the
-	// given Helm repository succeeded.
-	IndexationSucceededReason string = "IndexationSucceed"
 )
 
 // GetConditions returns the status conditions of the object.
@@ -116,28 +120,18 @@ func (in *HelmRepository) SetConditions(conditions []metav1.Condition) {
 	in.Status.Conditions = conditions
 }
 
-// GetRequeueAfter returns the duration after which the source must be reconciled again.
+// GetRequeueAfter returns the duration after which the source must be
+// reconciled again.
 func (in HelmRepository) GetRequeueAfter() time.Duration {
 	return in.Spec.Interval.Duration
 }
 
-// GetInterval returns the interval at which the source is reconciled.
-// Deprecated: use GetRequeueAfter instead.
-func (in HelmRepository) GetInterval() metav1.Duration {
-	return in.Spec.Interval
-}
-
-// GetArtifact returns the latest artifact from the source if present in the status sub-resource.
+// GetArtifact returns the latest artifact from the source if present in the
+// status sub-resource.
 func (in *HelmRepository) GetArtifact() *Artifact {
 	return in.Status.Artifact
 }
 
-// GetStatusConditions returns a pointer to the Status.Conditions slice.
-// Deprecated: use GetConditions instead.
-func (in *HelmRepository) GetStatusConditions() *[]metav1.Condition {
-	return &in.Status.Conditions
-}
-
 // +genclient
 // +genclient:Namespaced
 // +kubebuilder:storageversion
@@ -149,7 +143,7 @@ func (in *HelmRepository) 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=""
 
-// HelmRepository is the Schema for the helmrepositories API
+// HelmRepository is the Schema for the helmrepositories API.
 type HelmRepository struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -159,7 +153,7 @@ type HelmRepository struct {
 	Status HelmRepositoryStatus `json:"status,omitempty"`
 }
 
-// HelmRepositoryList contains a list of HelmRepository
+// HelmRepositoryList contains a list of HelmRepository objects.
 // +kubebuilder:object:root=true
 type HelmRepositoryList struct {
 	metav1.TypeMeta `json:",inline"`

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

@@ -253,7 +253,7 @@ spec:
     name: v1beta2
     schema:
       openAPIV3Schema:
-        description: HelmRepository is the Schema for the helmrepositories API
+        description: HelmRepository is the Schema for the helmrepositories API.
         properties:
           apiVersion:
             description: 'APIVersion defines the versioned schema of this representation
@@ -268,11 +268,13 @@ spec:
           metadata:
             type: object
           spec:
-            description: HelmRepositorySpec defines the reference to a Helm repository.
+            description: HelmRepositorySpec specifies the required configuration to
+              produce an Artifact for a Helm repository index YAML.
             properties:
               accessFrom:
-                description: AccessFrom defines an Access Control List for allowing
-                  cross-namespace references to this object.
+                description: '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'
                 properties:
                   namespaceSelectors:
                     description: NamespaceSelectors is the list of namespace selectors
@@ -298,7 +300,7 @@ spec:
                 - namespaceSelectors
                 type: object
               interval:
-                description: The interval at which to check the upstream for updates.
+                description: Interval at which to check the URL for updates.
                 type: string
               passCredentials:
                 description: PassCredentials allows the credentials from the SecretRef
@@ -309,10 +311,10 @@ spec:
                   getting stolen in a MITM-attack.
                 type: boolean
               secretRef:
-                description: The name of the secret containing authentication credentials
-                  for the Helm repository. For HTTP/S basic auth the secret must contain
-                  username and password fields. For TLS the secret must contain a
-                  certFile and keyFile, and/or caCert fields.
+                description: SecretRef specifies the Secret containing authentication
+                  credentials for the HelmRepository. For HTTP/S basic auth the secret
+                  must contain 'username' and 'password' fields. For TLS the secret
+                  must contain a 'certFile' and 'keyFile', and/or 'caCert' fields.
                 properties:
                   name:
                     description: Name of the referent.
@@ -321,15 +323,15 @@ spec:
                 - name
                 type: object
               suspend:
-                description: This flag tells the controller to suspend the reconciliation
-                  of this source.
+                description: Suspend tells the controller to suspend the reconciliation
+                  of this HelmRepository.
                 type: boolean
               timeout:
                 default: 60s
-                description: The timeout of index fetching, defaults to 60s.
+                description: Timeout of the index fetch operation, defaults to 60s.
                 type: string
               url:
-                description: The Helm repository URL, a valid URL contains at least
+                description: URL of the Helm repository, a valid URL contains at least
                   a protocol and host.
                 type: string
             required:
@@ -339,11 +341,11 @@ spec:
           status:
             default:
               observedGeneration: -1
-            description: HelmRepositoryStatus defines the observed state of the HelmRepository.
+            description: HelmRepositoryStatus records the observed state of the HelmRepository.
             properties:
               artifact:
-                description: Artifact represents the output of the last successful
-                  repository sync.
+                description: Artifact represents the last successful HelmRepository
+                  reconciliation.
                 properties:
                   checksum:
                     description: Checksum is the SHA256 checksum of the Artifact file.
@@ -453,11 +455,14 @@ spec:
                   be detected.
                 type: string
               observedGeneration:
-                description: ObservedGeneration is the last observed generation.
+                description: ObservedGeneration is the last observed generation of
+                  the HelmRepository object.
                 format: int64
                 type: integer
               url:
-                description: URL is the fetch link for the last index fetched.
+                description: URL is the dynamic fetch link for the latest Artifact.
+                  It is provided on a "best effort" basis, and using the precise HelmRepositoryStatus.Artifact
+                  data is recommended.
                 type: string
             type: object
         type: object