diff --git a/docs/spec/v1alpha1/README.md b/docs/spec/v1alpha1/README.md index eb9bf58b..7ecb44df 100644 --- a/docs/spec/v1alpha1/README.md +++ b/docs/spec/v1alpha1/README.md @@ -8,7 +8,7 @@ The is the v1alpha1 API specification for defining the desired state sources of * Source kinds: + [GitRepository](gitrepositories.md) + [HelmRepository](helmrepositories.md) - - [HelmChart](helmrepositories.md) + + [HelmChart](helmcharts.md) ## Implementation diff --git a/docs/spec/v1alpha1/gitrepositories.md b/docs/spec/v1alpha1/gitrepositories.md index 5c01a3a4..945fe6e8 100644 --- a/docs/spec/v1alpha1/gitrepositories.md +++ b/docs/spec/v1alpha1/gitrepositories.md @@ -1,13 +1,15 @@ # Git Repositories -The `GitReposiory` API defines a source for artifacts coming from Git. +The `GitReposiory` API defines a source for artifacts coming from Git. The +resource exposes the latest synchronized state from Git as an artifact in +an archive. ## Specification Git repository: ```go -// GitRepositorySpec defines the desired state of GitRepository +// GitRepositorySpec defines the desired state of GitRepository. type GitRepositorySpec struct { // The repository URL, can be a HTTP or SSH address. // +kubebuilder:validation:Pattern="^(http|https|ssh)://" @@ -17,7 +19,8 @@ type GitRepositorySpec struct { // +optional SecretRef *v1.LocalObjectReference `json:"secretRef,omitempty"` - // The git reference to checkout and monitor for changes, defaults to master branch. + // The git reference to checkout and monitor for changes, defaults to + // master branch. // +optional Reference *GitRepositoryRef `json:"ref,omitempty"` @@ -29,7 +32,7 @@ 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. // +optional @@ -43,21 +46,23 @@ type GitRepositoryRef struct { // +optional SemVer string `json:"semver"` - // The git commit sha to checkout, if specified branch and tag filters will be ignored. + // The git commit sha to checkout, if specified branch and tag filters will + // be ignored. // +optional Commit string `json:"commit"` } ``` -#### Status +### Status ```go -// GitRepositoryStatus defines the observed state of GitRepository +// GitRepositoryStatus defines the observed state of GitRepository. type GitRepositoryStatus struct { // +optional Conditions []SourceCondition `json:"conditions,omitempty"` - // URL is the download link for the artifact output of the last repository sync. + // URL is the download link for the artifact output of the last repository + // sync. // +optional URL string `json:"url,omitempty"` @@ -67,7 +72,7 @@ type GitRepositoryStatus struct { } ``` -#### Condition reasons +### Condition reasons ```go const ( diff --git a/docs/spec/v1alpha1/helmcharts.md b/docs/spec/v1alpha1/helmcharts.md new file mode 100644 index 00000000..2a27101a --- /dev/null +++ b/docs/spec/v1alpha1/helmcharts.md @@ -0,0 +1,142 @@ +# Helm Charts + +The `HelmChart` API defines a source for Helm chart artifacts coming +from [`HelmRepository` sources](helmrepositories.md). The resource +exposes the latest pulled chart for the defined version as an artifact. + +## Specification + +Helm chart: + +```go +// HelmChart defines the desired state of a Helm chart. +type HelmChartSpec struct { + // The name of the Helm chart, as made available by the referenced + // Helm repository. + // +required + Name string `json:"name"` + + // The chart version semver expression, defaults to latest when + // omitted. + // +optional + Version string `json:"version,omitempty"` + + // The name of the HelmRepository the chart is available at. + // +required + HelmRepositoryRef v1.LocalObjectReference `json:"helmRepositoryRef"` + + // The interval at which to check the Helm repository for updates. + // Defaults to the interval of the referenced HelmRepository. + // +optional + Interval metav1.Duration `json:"interval,omitempty"` +} +``` + +### Status + +```go +// HelmChartStatus defines the observed state of the HelmChart. +type HelmRepositoryStatus struct { + // +optional + Conditions []SourceCondition `json:"conditions,omitempty"` + + // URL is the download link for the last chart fetched. + // +optional + URL string `json:"url,omitempty"` + + // Artifact represents the output of the last successful chart sync. + // +optional + Artifact *Artifact `json:"artifact,omitempty"` +} +``` + +### Condition reasons + +```go +const ( + // ChartPullFailedReason represents the fact that the pull of the + // given Helm chart failed. + ChartPullFailedReason string = "ChartPullFailed" + // ChartPullSucceededReason represents the fact that the pull of + // the given Helm chart succeeded. + ChartPullSucceedReason string = "ChartPullSucceeded" +) +``` + +## Spec examples + +Pinned version: + +```yaml +apiVersion: source.fluxcd.io/v1alpha1 +kind: HelmChart +metadata: + name: redis + namespace: default + annotations: + # force sync trigger + source.fluxcd.io/syncAt: "2020-04-06T15:39:52+03:00" +spec: + name: redis + version: 10.5.7 + helmRepositoryRef: + name: stable +``` + +Semver range: + +```yaml +apiVersion: source.fluxcd.io/v1alpha1 +kind: HelmChart +metadata: + name: redis + namespace: default +spec: + name: redis + version: ^10.0.0 + helmRepositoryRef: + name: stable +``` + +Interval: + +```yaml +apiVersion: source.fluxcd.io/v1alpha1 +kind: HelmChart +metadata: + name: redis + namespace: default +spec: + name: redis + version: ^10.0.0 + helmRepositoryRef: + name: stable + interval: 30m +``` + +## Status examples + +Successful chart pull: + +```yaml +status: + url: http:///helmcharts/redis-default/redis-10.5.7.tgz + conditions: + - lastTransitionTime: "2020-04-10T09:34:45Z" + message: Fetched artifact are available at /data/helmcharts/redis-default/redis-10.5.7.tgz + reason: ChartPullSucceeded + status: "True" + type: Ready +``` + +Failed chart pull: + +```yaml +status: + conditions: + - lastTransitionTime: "2020-04-10T09:34:45Z" + message: '' + reason: ChartPullFailed + status: "False" + type: Ready +``` diff --git a/docs/spec/v1alpha1/helmrepositories.md b/docs/spec/v1alpha1/helmrepositories.md index a52b0265..851a3ac1 100644 --- a/docs/spec/v1alpha1/helmrepositories.md +++ b/docs/spec/v1alpha1/helmrepositories.md @@ -1,11 +1,12 @@ # Helm Repositories -The Helm source API defines two sources for artifact coming from Helm: -`HelmRepository` and `HelmChart`. +The `HelmRepository` API defines a source for Helm repositories. +The resource exposes the latest synchronized repository index as +an artifact. ## Specification -### Helm repository +Helm repository: ```go // HelmRepository defines the reference to a Helm repository. @@ -26,7 +27,7 @@ type HelmRepositorySpec struct { } ``` -#### Helm repository status +### Status ```go // HelmRepositoryStatus defines the observed state of HelmRepository @@ -44,7 +45,7 @@ type HelmRepositoryStatus struct { } ``` -#### Helm repository condition reasons +### Condition reasons ```go const ( @@ -57,67 +58,8 @@ const ( ) ``` -### Helm chart - -```go -// HelmChart defines the desired state of a Helm chart. -type HelmChartSpec struct { - // The name of the Helm chart, as made available by the referenced - // Helm repository. - // +required - Name string `json:"name"` - - // The chart version semver expression, defaults to latest when - // omitted. - // +optional - Version string `json:"version,omitempty"` - - // The name of the HelmRepository the chart is available at. - // +required - HelmRepositoryRef v1.LocalObjectReference `json:"helmRepositoryRef"` - - // The interval at which to check the Helm repository for updates. - // Defaults to the interval of the Helm repository. - // +optional - Interval metav1.Duration `json:"interval,omitempty"` -} -``` - -#### Helm chart status - -```go -// HelmChartStatus defines the observed state of the HelmChart. -type HelmRepositoryStatus struct { - // +optional - Conditions []SourceCondition `json:"conditions,omitempty"` - - // URL is the download link for the last chart fetched. - // +optional - URL string `json:"url,omitempty"` - - // Artifact represents the output of the last successful sync. - // +optional - Artifact *Artifact `json:"artifact,omitempty"` -} -``` - -#### Helm chart condition reasons - -```go -const ( - // ChartPullFailedReason represents the fact that the pull of the - // given Helm chart failed. - ChartPullFailedReason string = "ChartPullFailed" - // ChartPullSucceededReason represents the fact that the pull of - // the given Helm chart succeeded. - ChartPullSucceedReason string = "ChartPullSucceeded" -) -``` - ## Spec examples -### Helm repository - Public Helm repository: ```yaml @@ -155,68 +97,15 @@ metadata: namespace: default type: Opaque data: - username: - password: - certFile: - keyFile: - caFile: -``` - -### Helm chart - -Pinned version: - -```yaml -apiVersion: source.fluxcd.io/v1alpha1 -kind: HelmChart -metadata: - name: redis - namespace: default - annotations: - # force sync trigger - source.fluxcd.io/syncAt: "2020-04-06T15:39:52+03:00" -spec: - name: redis - version: 10.5.7 - helmRepositoryRef: - name: stable -``` - -Semver range: - -```yaml -apiVersion: source.fluxcd.io/v1alpha1 -kind: HelmChart -metadata: - name: redis - namespace: default -spec: - name: redis - version: ^10.0.0 - helmRepositoryRef: - name: stable -``` - -Interval: - -```yaml -apiVersion: source.fluxcd.io/v1alpha1 -kind: HelmChart -metadata: - name: redis - namespace: default -spec: - name: redis - version: ^10.0.0 - helmRepositoryRef: - name: stable - interval: 30m + username: + password: + certFile: + keyFile: + caFile: ``` ## Status examples -### Helm repository - Successful indexation: ```yaml @@ -253,30 +142,3 @@ status: status: "False" type: Ready ``` - -### Helm chart - -Successful chart pull: - -```yaml -status: - url: http:///helmcharts/redis-default/redis-10.5.7.tgz - conditions: - - lastTransitionTime: "2020-04-10T09:34:45Z" - message: Fetched artifact are available at /data/helmcharts/redis-default/redis-10.5.7.tgz - reason: ChartPullSucceeded - status: "True" - type: Ready -``` - -Failed chart pull: - -```yaml -status: - conditions: - - lastTransitionTime: "2020-04-10T09:34:45Z" - message: '' - reason: ChartPullFailed - status: "False" - type: Ready -```