diff --git a/docs/spec/v1alpha1/common.md b/docs/spec/v1alpha1/common.md index 1a474fc6..3b80ccc5 100644 --- a/docs/spec/v1alpha1/common.md +++ b/docs/spec/v1alpha1/common.md @@ -4,6 +4,34 @@ Common defines resources used across types. ## Specification +### Source status + +Source objects should contain a status sub-resource that embeds an artifact object: + +```go +// Artifact represents the output of a source synchronisation +type Artifact struct { + // Path is the local file path of this artifact. + // +required + Path string `json:"path"` + + // URL is the HTTP address of this artifact. + // +required + URL string `json:"url"` + + // Revision is a human readable identifier traceable in the origin source system. + // It can be a commit sha, git tag, a helm index timestamp, + // a helm chart version, a checksum, etc. + // +optional + Revision string `json:"revision"` + + // LastUpdateTime is the timestamp corresponding to the last + // update of this artifact. + // +required + LastUpdateTime metav1.Time `json:"lastUpdateTime,omitempty"` +} +``` + ### Source condition > **Note:** to be replaced with @@ -52,7 +80,7 @@ const ( const ( // InitializingReason represents the fact that a given source is being initialized. InitializingReason string = "Initializing" - // URLInvalidReason represents the fact that a given source has an invalid URL. + // URLInvalidReason represents the fact that a given source has an invalid URL. URLInvalidReason string = "URLInvalid" // StorageOperationFailedReason signals a failure caused by a storage operation. StorageOperationFailedReason string = "StorageOperationFailed" diff --git a/docs/spec/v1alpha1/gitrepositories.md b/docs/spec/v1alpha1/gitrepositories.md index 35121192..ebc9293e 100644 --- a/docs/spec/v1alpha1/gitrepositories.md +++ b/docs/spec/v1alpha1/gitrepositories.md @@ -57,14 +57,13 @@ type GitRepositoryStatus struct { // +optional Conditions []SourceCondition `json:"conditions,omitempty"` - // LastUpdateTime is the timestamp corresponding to the last status - // change of this repository. + // URL is the download link for the artifact output of the last repository sync. // +optional - LastUpdateTime *metav1.Time `json:"lastUpdateTime,omitempty"` + URL string `json:"url,omitempty"` - // Path to the artifact output of the last repository sync. + // Artifact represents the output of the last successful repository sync. // +optional - Artifact string `json:"artifacts,omitempty"` + Artifact *Artifact `json:"artifact,omitempty"` } ``` @@ -83,7 +82,7 @@ const ( ## Spec examples -Public Git repository: +Pull the master of a public repository every minute: ```yaml apiVersion: source.fluxcd.io/v1alpha1 @@ -99,8 +98,52 @@ spec: url: https://github.com/stefanprodan/podinfo ref: branch: master - tag: "3.2.0" - semver: ">= 3.2.0 <3.3.0" +``` + +Checkout a specific commit from a branch: + +```yaml +apiVersion: source.fluxcd.io/v1alpha1 +kind: GitRepository +metadata: + name: podinfo + namespace: default +spec: + interval: 1m + url: https://github.com/stefanprodan/podinfo + ref: + branch: master + commit: 363a6a8fe6a7f13e05d34c163b0ef02a777da20a +``` + +Pull a specific tag: + +```yaml +apiVersion: source.fluxcd.io/v1alpha1 +kind: GitRepository +metadata: + name: podinfo + namespace: default +spec: + interval: 1m + url: https://github.com/stefanprodan/podinfo + ref: + tag: 3.2.0 +``` + +Pull tag based on semver expression: + +```yaml +apiVersion: source.fluxcd.io/v1alpha1 +kind: GitRepository +metadata: + name: podinfo + namespace: default +spec: + interval: 1m + url: https://github.com/stefanprodan/podinfo + ref: + semver: ">=3.1.0-rc.1 <3.2.0" ``` HTTPS authentication (requires a secret with `username` and `password` fields): @@ -136,7 +179,7 @@ metadata: name: podinfo namespace: default spec: - url: ssh://git@github.com:stefanprodan/podinfo + url: ssh://git@github.com/stefanprodan/podinfo secretRef: name: ssh-credentials --- @@ -170,15 +213,19 @@ Successful sync: ```yaml status: - artifacts: http://source-controller.source-system/repositories/podinfo-default/5e747d3e088cd7a34ace4abc8cf7f3c3696e402f.tar.gz + artifact: + lastUpdateTime: "2020-04-07T06:59:23Z" + path: /data/gitrepository/podinfo-default/363a6a8fe6a7f13e05d34c163b0ef02a777da20a.tar.gz + revision: master/363a6a8fe6a7f13e05d34c163b0ef02a777da20a + url: http:///gitrepository/podinfo-default/363a6a8fe6a7f13e05d34c163b0ef02a777da20a.tar.gz conditions: - lastTransitionTime: "2020-04-07T06:59:23Z" message: 'Fetched artifacts are available at - /data/repositories/podinfo-default/5e747d3e088cd7a34ace4abc8cf7f3c3696e402f.tar.gz' + /data/gitrepository/podinfo-default/363a6a8fe6a7f13e05d34c163b0ef02a777da20a.tar.gz' reason: GitOperationSucceed status: "True" type: Ready - lastUpdateTime: "2020-04-07T06:59:23Z" + url: http:///gitrepository/podinfo-default/latest.tar.gz ``` Failed sync: diff --git a/docs/spec/v1alpha1/helmrepositories.md b/docs/spec/v1alpha1/helmrepositories.md index 8d7e381e..9ab550fb 100644 --- a/docs/spec/v1alpha1/helmrepositories.md +++ b/docs/spec/v1alpha1/helmrepositories.md @@ -29,19 +29,18 @@ type HelmRepositorySpec struct { #### Helm repository status ```go -// HelmRepositoryStatus defines the observed state of the HelmRepository. +// HelmRepositoryStatus defines the observed state of HelmRepository type HelmRepositoryStatus struct { // +optional Conditions []SourceCondition `json:"conditions,omitempty"` - // LastUpdateTime is the timestamp corresponding to the last status - // change of this Helm repository. + // URL is the download link for the last index fetched. // +optional - LastUpdateTime *metav1.Time `json:"lastUpdateTime,omitempty"` + URL string `json:"url,omitempty"` - // URI for the artifact of the last successful repository index. + // Artifact represents the output of the last successful repository sync. // +optional - Artifact string `json:"artifact,omitempty"` + Artifact *Artifact `json:"artifact,omitempty"` } ``` @@ -88,18 +87,17 @@ type HelmChartSpec struct { ```go // HelmChartStatus defines the observed state of the HelmChart. -type HelmChartStatus struct { +type HelmRepositoryStatus struct { // +optional Conditions []SourceCondition `json:"conditions,omitempty"` - // LastUpdateTime is the timestamp corresponding to the last status - // change of this Helm chart. + // URL is the download link for the last chart fetched. // +optional - LastUpdateTime *metav1.Time `json:"lastUpdateTime,omitempty"` + URL string `json:"url,omitempty"` - // URI for the artifact of the latest successful Helm chart pull. + // Artifact represents the output of the last successful sync. // +optional - Artifact string `json:"artifact,omitempty"` + Artifact *Artifact `json:"artifact,omitempty"` } ``` @@ -224,14 +222,13 @@ Successful indexation: ```yaml status: - artifact: http:///helmrepositories/podinfo-default/index-21c195d78e699e4b656e2885887d019627838993.yaml + url: http:///helmrepository/podinfo-default/index.yaml conditions: - lastTransitionTime: "2020-04-10T09:34:45Z" message: Fetched artifact are available at /data/helmrepositories/podinfo-default/index-21c195d78e699e4b656e2885887d019627838993.yaml reason: IndexationSucceeded status: "True" type: Ready - lastUpdateTime: "2020-04-10T09:34:45Z" ``` Failed indexation: @@ -264,14 +261,13 @@ Successful chart pull: ```yaml status: - artifact: http:///helmcharts/redis-default/redis-10.5.7.tgz + 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 - lastUpdateTime: "2020-04-10T09:34:45Z" ``` Failed chart pull: