From c657e68ba1003dae248f8df7b4d568a3e1e3abd6 Mon Sep 17 00:00:00 2001 From: Hidde Beydals Date: Tue, 27 Oct 2020 22:43:04 +0100 Subject: [PATCH] Various API doc corrections Signed-off-by: Hidde Beydals --- api/v1beta1/artifact_types.go | 2 +- api/v1beta1/bucket_types.go | 5 +- api/v1beta1/gitrepository_types.go | 20 ++++---- api/v1beta1/helmrepository_types.go | 4 +- .../source.toolkit.fluxcd.io_buckets.yaml | 8 ++-- ...rce.toolkit.fluxcd.io_gitrepositories.yaml | 22 ++++----- .../source.toolkit.fluxcd.io_helmcharts.yaml | 2 +- ...ce.toolkit.fluxcd.io_helmrepositories.yaml | 6 +-- docs/api/source.md | 48 ++++++++++--------- docs/spec/v1beta1/buckets.md | 5 +- docs/spec/v1beta1/common.md | 6 +-- docs/spec/v1beta1/gitrepositories.md | 23 ++++----- docs/spec/v1beta1/helmcharts.md | 7 ++- docs/spec/v1beta1/helmrepositories.md | 9 +++- 14 files changed, 92 insertions(+), 75 deletions(-) diff --git a/api/v1beta1/artifact_types.go b/api/v1beta1/artifact_types.go index 26e29c13..c7ddffce 100644 --- a/api/v1beta1/artifact_types.go +++ b/api/v1beta1/artifact_types.go @@ -34,7 +34,7 @@ type Artifact struct { 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 + // system. It can be a Git commit SHA, Git tag, a Helm index timestamp, a Helm // chart version, etc. // +optional Revision string `json:"revision"` diff --git a/api/v1beta1/bucket_types.go b/api/v1beta1/bucket_types.go index f7917441..9405bc76 100644 --- a/api/v1beta1/bucket_types.go +++ b/api/v1beta1/bucket_types.go @@ -61,12 +61,13 @@ type BucketSpec struct { // +required Interval metav1.Duration `json:"interval"` - // The timeout for download operations, default ('20s'). + // The timeout for download operations, defaults to 20s. // +optional Timeout *metav1.Duration `json:"timeout,omitempty"` // Ignore overrides the set of excluded patterns in the .sourceignore format - // (which is the same as .gitignore). + // (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"` } diff --git a/api/v1beta1/gitrepository_types.go b/api/v1beta1/gitrepository_types.go index 12b288a8..f6632194 100644 --- a/api/v1beta1/gitrepository_types.go +++ b/api/v1beta1/gitrepository_types.go @@ -31,7 +31,7 @@ const ( // GitRepositorySpec defines the desired state of a Git repository. type GitRepositorySpec struct { - // The repository URL, can be a HTTP or SSH address. + // The repository URL, can be a HTTP/S or SSH address. // +kubebuilder:validation:Pattern="^(http|https|ssh)://" // +required URL string `json:"url"` @@ -48,16 +48,16 @@ type GitRepositorySpec struct { // +required Interval metav1.Duration `json:"interval"` - // The timeout for remote git operations like cloning, default to 20s. + // The timeout for remote Git operations like cloning, defaults to 20s. // +optional Timeout *metav1.Duration `json:"timeout,omitempty"` - // The git reference to checkout and monitor for changes, defaults to + // The Git reference to checkout and monitor for changes, defaults to // master branch. // +optional Reference *GitRepositoryRef `json:"ref,omitempty"` - // Verify OpenPGP signature for the commit that HEAD points to. + // Verify OpenPGP signature for the Git commit HEAD points to. // +optional Verification *GitRepositoryVerification `json:"verify,omitempty"` @@ -68,21 +68,21 @@ type GitRepositorySpec struct { Ignore *string `json:"ignore,omitempty"` } -// GitRepositoryRef defines the git ref used for pull and checkout operations. +// GitRepositoryRef defines the Git ref used for pull and checkout operations. type GitRepositoryRef struct { - // The git branch to checkout, defaults to master. + // The Git branch to checkout, defaults to master. // +optional Branch string `json:"branch,omitempty"` - // The git tag to checkout, takes precedence over branch. + // The Git tag to checkout, takes precedence over Branch. // +optional Tag string `json:"tag,omitempty"` - // The git tag semver expression, takes precedence over tag. + // The Git tag semver expression, takes precedence over Tag. // +optional SemVer string `json:"semver,omitempty"` - // The git commit sha to checkout, if specified tag filters will be ignored. + // The Git commit SHA to checkout, if specified Tag filters will be ignored. // +optional Commit string `json:"commit,omitempty"` } @@ -93,7 +93,7 @@ type GitRepositoryVerification struct { // +kubebuilder:validation:Enum=head Mode string `json:"mode"` - // The secret name containing the public keys of all trusted git authors. + // The secret name containing the public keys of all trusted Git authors. SecretRef corev1.LocalObjectReference `json:"secretRef,omitempty"` } diff --git a/api/v1beta1/helmrepository_types.go b/api/v1beta1/helmrepository_types.go index 9da8f395..5fe51f92 100644 --- a/api/v1beta1/helmrepository_types.go +++ b/api/v1beta1/helmrepository_types.go @@ -39,8 +39,8 @@ type HelmRepositorySpec struct { // repository. // For HTTP/S basic auth the secret must contain username and // password fields. - // For TLS the secret must contain caFile, keyFile and caCert - // fields. + // For TLS the secret must contain a certFile and keyFile, and/or + // caCert fields. // +optional SecretRef *corev1.LocalObjectReference `json:"secretRef,omitempty"` diff --git a/config/crd/bases/source.toolkit.fluxcd.io_buckets.yaml b/config/crd/bases/source.toolkit.fluxcd.io_buckets.yaml index f6244fbe..c97b3497 100644 --- a/config/crd/bases/source.toolkit.fluxcd.io_buckets.yaml +++ b/config/crd/bases/source.toolkit.fluxcd.io_buckets.yaml @@ -58,7 +58,9 @@ spec: type: string ignore: description: Ignore overrides the set of excluded patterns in the - .sourceignore format (which is the same as .gitignore). + .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. type: string insecure: description: Insecure allows connecting to a non-TLS S3 HTTP endpoint. @@ -85,7 +87,7 @@ spec: type: string type: object timeout: - description: The timeout for download operations, default ('20s'). + description: The timeout for download operations, defaults to 20s. type: string required: - bucketName @@ -112,7 +114,7 @@ spec: type: string revision: description: Revision is a human readable identifier traceable - in the origin source system. It can be a Git commit sha, Git + 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: diff --git a/config/crd/bases/source.toolkit.fluxcd.io_gitrepositories.yaml b/config/crd/bases/source.toolkit.fluxcd.io_gitrepositories.yaml index 59bd4bfb..f2f704f6 100644 --- a/config/crd/bases/source.toolkit.fluxcd.io_gitrepositories.yaml +++ b/config/crd/bases/source.toolkit.fluxcd.io_gitrepositories.yaml @@ -59,22 +59,22 @@ spec: description: The interval at which to check for repository updates. type: string ref: - description: The git reference to checkout and monitor for changes, + description: The Git reference to checkout and monitor for changes, defaults to master branch. properties: branch: - description: The git branch to checkout, defaults to master. + description: The Git branch to checkout, defaults to master. type: string commit: - description: The git commit sha to checkout, if specified tag + description: The Git commit SHA to checkout, if specified Tag filters will be ignored. type: string semver: - description: The git tag semver expression, takes precedence over - tag. + description: The Git tag semver expression, takes precedence over + Tag. type: string tag: - description: The git tag to checkout, takes precedence over branch. + description: The Git tag to checkout, takes precedence over Branch. type: string type: object secretRef: @@ -89,15 +89,15 @@ spec: type: string type: object timeout: - description: The timeout for remote git operations like cloning, default + description: The timeout for remote Git operations like cloning, defaults to 20s. type: string url: - description: The repository URL, can be a HTTP or SSH address. + description: The repository URL, can be a HTTP/S or SSH address. pattern: ^(http|https|ssh):// type: string verify: - description: Verify OpenPGP signature for the commit that HEAD points + description: Verify OpenPGP signature for the Git commit HEAD points to. properties: mode: @@ -108,7 +108,7 @@ spec: type: string secretRef: description: The secret name containing the public keys of all - trusted git authors. + trusted Git authors. properties: name: description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names @@ -142,7 +142,7 @@ spec: type: string revision: description: Revision is a human readable identifier traceable - in the origin source system. It can be a Git commit sha, Git + 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: diff --git a/config/crd/bases/source.toolkit.fluxcd.io_helmcharts.yaml b/config/crd/bases/source.toolkit.fluxcd.io_helmcharts.yaml index 7b1218c2..86667f84 100644 --- a/config/crd/bases/source.toolkit.fluxcd.io_helmcharts.yaml +++ b/config/crd/bases/source.toolkit.fluxcd.io_helmcharts.yaml @@ -119,7 +119,7 @@ spec: type: string revision: description: Revision is a human readable identifier traceable - in the origin source system. It can be a Git commit sha, Git + 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: diff --git a/config/crd/bases/source.toolkit.fluxcd.io_helmrepositories.yaml b/config/crd/bases/source.toolkit.fluxcd.io_helmrepositories.yaml index c2ee96ba..89dbfa60 100644 --- a/config/crd/bases/source.toolkit.fluxcd.io_helmrepositories.yaml +++ b/config/crd/bases/source.toolkit.fluxcd.io_helmrepositories.yaml @@ -55,8 +55,8 @@ spec: 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 caFile, - keyFile and caCert fields. + 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. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names @@ -94,7 +94,7 @@ spec: type: string revision: description: Revision is a human readable identifier traceable - in the origin source system. It can be a Git commit sha, Git + 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: diff --git a/docs/api/source.md b/docs/api/source.md index b32c4c6f..e0e864ee 100644 --- a/docs/api/source.md +++ b/docs/api/source.md @@ -171,7 +171,7 @@ Kubernetes meta/v1.Duration (Optional) -

The timeout for download operations, default (‘20s’).

+

The timeout for download operations, defaults to 20s.

@@ -184,7 +184,8 @@ string (Optional)

Ignore overrides the set of excluded patterns in the .sourceignore format -(which is the same as .gitignore).

+(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.

@@ -271,7 +272,7 @@ string -

The repository URL, can be a HTTP or SSH address.

+

The repository URL, can be a HTTP/S or SSH address.

@@ -316,7 +317,7 @@ Kubernetes meta/v1.Duration (Optional) -

The timeout for remote git operations like cloning, default to 20s.

+

The timeout for remote Git operations like cloning, defaults to 20s.

@@ -330,7 +331,7 @@ GitRepositoryRef (Optional) -

The git reference to checkout and monitor for changes, defaults to +

The Git reference to checkout and monitor for changes, defaults to master branch.

@@ -345,7 +346,7 @@ GitRepositoryVerification (Optional) -

Verify OpenPGP signature for the commit that HEAD points to.

+

Verify OpenPGP signature for the Git commit HEAD points to.

@@ -603,8 +604,8 @@ Kubernetes core/v1.LocalObjectReference repository. For HTTP/S basic auth the secret must contain username and password fields. -For TLS the secret must contain caFile, keyFile and caCert -fields.

+For TLS the secret must contain a certFile and keyFile, and/or +caCert fields.

@@ -705,7 +706,7 @@ string (Optional)

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 +system. It can be a Git commit SHA, Git tag, a Helm index timestamp, a Helm chart version, etc.

@@ -853,7 +854,7 @@ Kubernetes meta/v1.Duration (Optional) -

The timeout for download operations, default (‘20s’).

+

The timeout for download operations, defaults to 20s.

@@ -866,7 +867,8 @@ string (Optional)

Ignore overrides the set of excluded patterns in the .sourceignore format -(which is the same as .gitignore).

+(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.

@@ -952,7 +954,7 @@ Artifact (Appears on: GitRepositorySpec)

-

GitRepositoryRef defines the git ref used for pull and checkout operations.

+

GitRepositoryRef defines the Git ref used for pull and checkout operations.

@@ -972,7 +974,7 @@ string @@ -984,7 +986,7 @@ string @@ -996,7 +998,7 @@ string @@ -1008,7 +1010,7 @@ string @@ -1040,7 +1042,7 @@ string @@ -1085,7 +1087,7 @@ Kubernetes meta/v1.Duration @@ -1099,7 +1101,7 @@ GitRepositoryRef @@ -1114,7 +1116,7 @@ GitRepositoryVerification @@ -1247,7 +1249,7 @@ Kubernetes core/v1.LocalObjectReference @@ -1454,8 +1456,8 @@ Kubernetes core/v1.LocalObjectReference repository. For HTTP/S basic auth the secret must contain username and password fields. -For TLS the secret must contain caFile, keyFile and caCert -fields.

+For TLS the secret must contain a certFile and keyFile, and/or +caCert fields.

diff --git a/docs/spec/v1beta1/buckets.md b/docs/spec/v1beta1/buckets.md index 63c62267..928e4c97 100644 --- a/docs/spec/v1beta1/buckets.md +++ b/docs/spec/v1beta1/buckets.md @@ -40,12 +40,13 @@ type BucketSpec struct { // +required Interval metav1.Duration `json:"interval"` - // The timeout for download operations, default ('20s'). + // The timeout for download operations, defaults to 20s. // +optional Timeout *metav1.Duration `json:"timeout,omitempty"` // Ignore overrides the set of excluded patterns in the .sourceignore format - // (which is the same as .gitignore). + // (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"` } diff --git a/docs/spec/v1beta1/common.md b/docs/spec/v1beta1/common.md index ab35da57..ce05795b 100644 --- a/docs/spec/v1beta1/common.md +++ b/docs/spec/v1beta1/common.md @@ -54,9 +54,9 @@ type Artifact struct { // +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 index timestamp, a Helm + // chart version, etc. // +optional Revision string `json:"revision"` diff --git a/docs/spec/v1beta1/gitrepositories.md b/docs/spec/v1beta1/gitrepositories.md index 464a510f..2973efe2 100644 --- a/docs/spec/v1beta1/gitrepositories.md +++ b/docs/spec/v1beta1/gitrepositories.md @@ -11,7 +11,7 @@ Git repository: ```go // GitRepositorySpec defines the desired state of a Git repository. type GitRepositorySpec struct { - // The repository URL, can be a HTTP or SSH address. + // The repository URL, can be a HTTP/S or SSH address. // +kubebuilder:validation:Pattern="^(http|https|ssh)://" // +required URL string `json:"url"` @@ -28,16 +28,16 @@ type GitRepositorySpec struct { // +required Interval metav1.Duration `json:"interval"` - // The timeout for remote git operations like cloning, default to 20s. + // The timeout for remote Git operations like cloning, defaults to 20s. // +optional Timeout *metav1.Duration `json:"timeout,omitempty"` - // The git reference to checkout and monitor for changes, defaults to + // The Git reference to checkout and monitor for changes, defaults to // master branch. // +optional Reference *GitRepositoryRef `json:"ref,omitempty"` - // Verify OpenPGP signature for the commit that HEAD points to. + // Verify OpenPGP signature for the Git commit HEAD points to. // +optional Verification *GitRepositoryVerification `json:"verify,omitempty"` @@ -52,21 +52,21 @@ type GitRepositorySpec struct { Git repository reference: ```go -// GitRepositoryRef defines the git ref used for pull and checkout operations. +// GitRepositoryRef defines the Git ref used for pull and checkout operations. type GitRepositoryRef struct { - // The git branch to checkout, defaults to master. + // The Git branch to checkout, defaults to master. // +optional Branch string `json:"branch,omitempty"` - // The git tag to checkout, takes precedence over branch. + // The Git tag to checkout, takes precedence over Branch. // +optional Tag string `json:"tag,omitempty"` - // The git tag semver expression, takes precedence over tag. + // The Git tag semver expression, takes precedence over Tag. // +optional SemVer string `json:"semver,omitempty"` - // The git commit sha to checkout, if specified tag filters will be ignored. + // The Git commit SHA to checkout, if specified Tag filters will be ignored. // +optional Commit string `json:"commit,omitempty"` } @@ -81,8 +81,8 @@ type GitRepositoryVerification struct { // +kubebuilder:validation:Enum=head Mode string `json:"mode"` - // The secret name containing the public keys of all trusted git authors. - SecretRef corev1.LocalObjectReference `json:"secretRef"` + // The secret name containing the public keys of all trusted Git authors. + SecretRef corev1.LocalObjectReference `json:"secretRef,omitempty"` } ``` @@ -91,6 +91,7 @@ type GitRepositoryVerification struct { ```go // GitRepositoryStatus defines the observed state of the GitRepository. type GitRepositoryStatus struct { + // Conditions holds the conditions for the GitRepository. // +optional Conditions []meta.Condition `json:"conditions,omitempty"` diff --git a/docs/spec/v1beta1/helmcharts.md b/docs/spec/v1beta1/helmcharts.md index 22572d3b..d93d75d3 100644 --- a/docs/spec/v1beta1/helmcharts.md +++ b/docs/spec/v1beta1/helmcharts.md @@ -62,10 +62,15 @@ type LocalHelmChartSourceReference struct { ```go // HelmChartStatus defines the observed state of the HelmChart. type HelmChartStatus struct { + // ObservedGeneration is the last observed generation. + // +optional + ObservedGeneration int64 `json:"observedGeneration,omitempty"` + + // Conditions holds the conditions for the HelmChart. // +optional Conditions []meta.Condition `json:"conditions,omitempty"` - // URL is the download link for the last chart fetched. + // URL is the download link for the last chart pulled. // +optional URL string `json:"url,omitempty"` diff --git a/docs/spec/v1beta1/helmrepositories.md b/docs/spec/v1beta1/helmrepositories.md index 52d7eeef..ac68f446 100644 --- a/docs/spec/v1beta1/helmrepositories.md +++ b/docs/spec/v1beta1/helmrepositories.md @@ -19,8 +19,8 @@ type HelmRepositorySpec struct { // repository. // For HTTP/S basic auth the secret must contain username and // password fields. - // For TLS the secret must contain caFile, keyFile and caCert - // fields. + // For TLS the secret must contain a certFile and keyFile, and/or + // caCert fields. // +optional SecretRef *corev1.LocalObjectReference `json:"secretRef,omitempty"` @@ -39,6 +39,11 @@ type HelmRepositorySpec struct { ```go // HelmRepositoryStatus defines the observed state of the HelmRepository. type HelmRepositoryStatus struct { + // ObservedGeneration is the last observed generation. + // +optional + ObservedGeneration int64 `json:"observedGeneration,omitempty"` + + // Conditions holds the conditions for the HelmRepository. // +optional Conditions []meta.Condition `json:"conditions,omitempty"`
(Optional) -

The git branch to checkout, defaults to master.

+

The Git branch to checkout, defaults to master.
(Optional) -

The git tag to checkout, takes precedence over branch.

+

The Git tag to checkout, takes precedence over Branch.
(Optional) -

The git tag semver expression, takes precedence over tag.

+

The Git tag semver expression, takes precedence over Tag.
(Optional) -

The git commit sha to checkout, if specified tag filters will be ignored.

+

The Git commit SHA to checkout, if specified Tag filters will be ignored.
-

The repository URL, can be a HTTP or SSH address.

+

The repository URL, can be a HTTP/S or SSH address.
(Optional) -

The timeout for remote git operations like cloning, default to 20s.

+

The timeout for remote Git operations like cloning, defaults to 20s.
(Optional) -

The git reference to checkout and monitor for changes, defaults to +

The Git reference to checkout and monitor for changes, defaults to master branch.
(Optional) -

Verify OpenPGP signature for the commit that HEAD points to.

+

Verify OpenPGP signature for the Git commit HEAD points to.
-

The secret name containing the public keys of all trusted git authors.

+

The secret name containing the public keys of all trusted Git authors.