Document GitRepository API v1beta2 spec

Signed-off-by: Hidde Beydals <[email protected]>

Author: hiddeco

api/v1beta2/gitrepository_types.go

@@ -29,165 +29,198 @@ const (
 	// GitRepositoryKind is the string representation of a GitRepository.
 	GitRepositoryKind = "GitRepository"
 
-	// GoGitImplementation represents the go-git Git implementation kind.
+	// GoGitImplementation for performing Git operations using go-git.
 	GoGitImplementation = "go-git"
-	// LibGit2Implementation represents the git2go Git implementation kind.
+	// LibGit2Implementation for performing Git operations using libgit2.
 	LibGit2Implementation = "libgit2"
 )
 
 const (
-	// IncludeUnavailableCondition indicates one of the includes is not available. For example, because it does not
-	// exist, or does not have an Artifact.
-	// This is a "negative polarity" or "abnormal-true" type, and is only present on the resource if it is True.
+	// IncludeUnavailableCondition indicates one of the includes is not
+	// available. For example, because it does not exist, or does not have an
+	// Artifact.
+	// This is a "negative polarity" or "abnormal-true" type, and is only
+	// present on the resource if it is True.
 	IncludeUnavailableCondition string = "IncludeUnavailable"
 )
 
-// GitRepositorySpec defines the desired state of a Git repository.
+// GitRepositorySpec specifies the required configuration to produce an
+// Artifact for a Git repository.
 type GitRepositorySpec struct {
-	// The repository URL, can be a HTTP/S or SSH address.
+	// URL specifies the Git repository URL, it can be an HTTP/S or SSH address.
 	// +kubebuilder:validation:Pattern="^(http|https|ssh)://"
 	// +required
 	URL string `json:"url"`
 
-	// The secret name containing the Git credentials.
-	// For HTTPS repositories the secret must contain username and password fields.
-	// For SSH repositories the secret must contain 'identity', 'identity.pub' and 'known_hosts' fields.
+	// SecretRef specifies the Secret containing authentication credentials for
+	// the GitRepository.
+	// For HTTPS repositories the Secret must contain 'username' and 'password'
+	// fields.
+	// For SSH repositories the Secret must contain 'identity', 'identity.pub'
+	// and 'known_hosts' fields.
 	// +optional
 	SecretRef *meta.LocalObjectReference `json:"secretRef,omitempty"`
 
-	// The interval at which to check for repository updates.
+	// Interval at which to check the GitRepository for updates.
 	// +required
 	Interval metav1.Duration `json:"interval"`
 
-	// The timeout for remote Git operations like cloning, defaults to 60s.
+	// Timeout for Git operations like cloning, defaults to 60s.
 	// +kubebuilder:default="60s"
 	// +optional
 	Timeout *metav1.Duration `json:"timeout,omitempty"`
 
-	// The Git reference to checkout and monitor for changes, defaults to
-	// master branch.
+	// Reference specifies the Git reference to resolve and monitor for
+	// changes, defaults to the 'master' branch.
 	// +optional
 	Reference *GitRepositoryRef `json:"ref,omitempty"`
 
-	// Verification defines the configuration to verify the OpenPGP signature for the Git commit HEAD points to.
+	// Verification specifies the configuration to verify the Git commit
+	// signature(s).
 	// +optional
 	Verification *GitRepositoryVerification `json:"verify,omitempty"`
 
-	// Ignore overrides the set of excluded patterns in the .sourceignore format (which is the same as .gitignore).
-	// If not provided, a default will be used, consult the documentation for your version to find out what those are.
+	// Ignore overrides the set of excluded patterns in the .sourceignore format
+	// (which is the same as .gitignore). If not provided, a default will be used,
+	// consult the documentation for your version to find out what those are.
 	// +optional
 	Ignore *string `json:"ignore,omitempty"`
 
-	// Suspend tells the controller to suspend the reconciliation of this source.
-	// This flag tells the controller to suspend the reconciliation of this source.
+	// Suspend tells the controller to suspend the reconciliation of this
+	// GitRepository.
 	// +optional
 	Suspend bool `json:"suspend,omitempty"`
 
-	// Determines which git client library to use.
-	// Defaults to go-git, valid values are ('go-git', 'libgit2').
+	// GitImplementation specifies which Git client library implementation to
+	// use. Defaults to 'go-git', valid values are ('go-git', 'libgit2').
 	// +kubebuilder:validation:Enum=go-git;libgit2
 	// +kubebuilder:default:=go-git
 	// +optional
 	GitImplementation string `json:"gitImplementation,omitempty"`
 
-	// When enabled, after the clone is created, initializes all submodules within, using their default settings.
+	// RecurseSubmodules enables the initialization of all submodules within
+	// the GitRepository as cloned from the URL, using their default settings.
 	// This option is available only when using the 'go-git' GitImplementation.
 	// +optional
 	RecurseSubmodules bool `json:"recurseSubmodules,omitempty"`
 
-	// Include defines a list of GitRepository resources which artifacts should be included in the artifact produced for
-	// this resource.
+	// Include specifies a list of GitRepository resources which Artifacts
+	// should be included in the Artifact produced for this GitRepository.
 	Include []GitRepositoryInclude `json:"include,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"`
 }
 
+// GitRepositoryInclude specifies a local reference to a GitRepository which
+// Artifact (sub-)contents must be included, and where they should be placed.
+type GitRepositoryInclude struct {
+	// GitRepositoryRef specifies the GitRepository which Artifact contents
+	// must be included.
+	GitRepositoryRef meta.LocalObjectReference `json:"repository"`
+
+	// FromPath specifies the path to copy contents from, defaults to the root
+	// of the Artifact.
+	// +optional
+	FromPath string `json:"fromPath"`
+
+	// ToPath specifies the path to copy contents to, defaults to the name of
+	// the GitRepositoryRef.
+	// +optional
+	ToPath string `json:"toPath"`
+}
+
+// GetFromPath returns the specified FromPath.
 func (in *GitRepositoryInclude) GetFromPath() string {
 	return in.FromPath
 }
 
+// GetToPath returns the specified ToPath, falling back to the name of the
+// GitRepositoryRef.
 func (in *GitRepositoryInclude) GetToPath() string {
 	if in.ToPath == "" {
 		return in.GitRepositoryRef.Name
 	}
 	return in.ToPath
 }
 
-// GitRepositoryInclude defines a source with a from and to path.
-type GitRepositoryInclude struct {
-	// Reference to a GitRepository to include.
-	GitRepositoryRef meta.LocalObjectReference `json:"repository"`
-
-	// The path to copy contents from, defaults to the root directory.
-	// +optional
-	FromPath string `json:"fromPath"`
-
-	// The path to copy contents to, defaults to the name of the source ref.
-	// +optional
-	ToPath string `json:"toPath"`
-}
-
-// GitRepositoryRef defines the Git ref used for pull and checkout operations.
+// GitRepositoryRef specifies the Git reference to resolve and checkout.
 type GitRepositoryRef struct {
-	// The Git branch to checkout, defaults to master.
+	// Branch to check out, defaults to 'master' if no other field is defined.
+	//
+	// When GitRepositorySpec.GitImplementation is set to 'go-git', a shallow
+	// clone of the specified branch is performed.
 	// +optional
 	Branch string `json:"branch,omitempty"`
 
-	// The Git tag to checkout, takes precedence over Branch.
+	// Tag to check out, takes precedence over Branch.
 	// +optional
 	Tag string `json:"tag,omitempty"`
 
-	// The Git tag semver expression, takes precedence over Tag.
+	// SemVer tag expression to check out, takes precedence over Tag.
 	// +optional
 	SemVer string `json:"semver,omitempty"`
 
-	// The Git commit SHA to checkout, if specified Tag filters will be ignored.
+	// Commit SHA to check out, takes precedence over all reference fields.
+	//
+	// When GitRepositorySpec.GitImplementation is set to 'go-git', this can be
+	// combined with Branch to shallow clone the branch, in which the commit is
+	// expected to exist.
 	// +optional
 	Commit string `json:"commit,omitempty"`
 }
 
-// GitRepositoryVerification defines the OpenPGP signature verification process.
+// GitRepositoryVerification specifies the Git commit signature verification
+// strategy.
 type GitRepositoryVerification struct {
-	// Mode describes what Git object should be verified, currently ('head').
+	// Mode specifies what Git object should be verified, currently ('head').
 	// +kubebuilder:validation:Enum=head
 	Mode string `json:"mode"`
 
-	// SecretRef containing the public keys of all trusted Git authors.
+	// SecretRef specifies the Secret containing the public keys of trusted Git
+	// authors.
 	SecretRef meta.LocalObjectReference `json:"secretRef,omitempty"`
 }
 
-// GitRepositoryStatus defines the observed state of a Git repository.
+// GitRepositoryStatus records the observed state of a Git repository.
 type GitRepositoryStatus struct {
-	// ObservedGeneration is the last observed generation.
+	// ObservedGeneration is the last observed generation of the GitRepository
+	// object.
 	// +optional
 	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
 
 	// Conditions holds the conditions for the GitRepository.
 	// +optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	// URL is the fetch link for the artifact output of the last repository sync.
+	// URL is the dynamic fetch link for the latest Artifact.
+	// It is provided on a "best effort" basis, and using the precise
+	// GitRepositoryStatus.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 GitRepository reconciliation.
 	// +optional
 	Artifact *Artifact `json:"artifact,omitempty"`
 
-	// IncludedArtifacts represents the included artifacts from the last successful repository sync.
+	// IncludedArtifacts contains a list of the last successfully included
+	// Artifacts as instructed by GitRepositorySpec.Include.
 	// +optional
 	IncludedArtifacts []*Artifact `json:"includedArtifacts,omitempty"`
 
 	meta.ReconcileRequestStatus `json:",inline"`
 }
 
 const (
-	// GitOperationSucceedReason represents the fact that the git clone, pull and checkout operations succeeded.
-	GitOperationSucceedReason string = "GitOperationSucceed"
+	// GitOperationSucceedReason signals that a Git operation (e.g. clone,
+	// checkout, etc.) succeeded.
+	GitOperationSucceedReason string = "GitOperationSucceeded"
 
-	// GitOperationFailedReason represents the fact that the git clone, pull or checkout operations failed.
+	// GitOperationFailedReason signals that a Git operation (e.g. clone,
+	// checkout, etc.) failed.
 	GitOperationFailedReason string = "GitOperationFailed"
 )
 
@@ -201,28 +234,18 @@ func (in *GitRepository) 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 GitRepository must be
+// reconciled again.
 func (in GitRepository) GetRequeueAfter() time.Duration {
 	return in.Spec.Interval.Duration
 }
 
-// GetInterval returns the interval at which the source is reconciled.
-// Deprecated: use GetRequeueAfter instead.
-func (in GitRepository) 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 GitRepository if present in
+// the status sub-resource.
 func (in *GitRepository) GetArtifact() *Artifact {
 	return in.Status.Artifact
 }
 
-// GetStatusConditions returns a pointer to the Status.Conditions slice.
-// Deprecated: use GetConditions instead.
-func (in *GitRepository) GetStatusConditions() *[]metav1.Condition {
-	return &in.Status.Conditions
-}
-
 // +genclient
 // +genclient:Namespaced
 // +kubebuilder:storageversion
@@ -234,7 +257,7 @@ func (in *GitRepository) 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=""
 
-// GitRepository is the Schema for the gitrepositories API
+// GitRepository is the Schema for the gitrepositories API.
 type GitRepository struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -244,7 +267,7 @@ type GitRepository struct {
 	Status GitRepositoryStatus `json:"status,omitempty"`
 }
 
-// GitRepositoryList contains a list of GitRepository
+// GitRepositoryList contains a list of GitRepository objects.
 // +kubebuilder:object:root=true
 type GitRepositoryList struct {
 	metav1.TypeMeta `json:",inline"`