Merge pull request #31 from fluxcd/spec-sync

docs: Sync specification with API

Author: stefanprodan

api/v1alpha1/source.go

@@ -11,3 +11,8 @@ type Source interface {
 	// GetInterval returns the interval at which the source is updated.
 	GetInterval() metav1.Duration
 }
+
+const (
+	// SyncAtAnnotation is the timestamp corresponding to an on-demand source sync.
+	SyncAtAnnotation string = "source.fluxcd.io/syncAt"
+)

controllers/predicate.go

@@ -24,6 +24,8 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/client/apiutil"
 	"sigs.k8s.io/controller-runtime/pkg/event"
 	"sigs.k8s.io/controller-runtime/pkg/predicate"
+
+	sourcev1 "github.com/fluxcd/source-controller/api/v1alpha1"
 )
 
 type SourceChangePredicate struct {
@@ -43,8 +45,8 @@ func (SourceChangePredicate) Update(e event.UpdateEvent) bool {
 	}
 
 	// handle force sync
-	if val, ok := e.MetaNew.GetAnnotations()[ForceSyncAnnotation]; ok {
-		if valOld, okOld := e.MetaOld.GetAnnotations()[ForceSyncAnnotation]; okOld {
+	if val, ok := e.MetaNew.GetAnnotations()[sourcev1.SyncAtAnnotation]; ok {
+		if valOld, okOld := e.MetaOld.GetAnnotations()[sourcev1.SyncAtAnnotation]; okOld {
 			if val != valOld {
 				return true
 			}
@@ -56,10 +58,6 @@ func (SourceChangePredicate) Update(e event.UpdateEvent) bool {
 	return false
 }
 
-const (
-	ForceSyncAnnotation string = "source.fluxcd.io/syncAt"
-)
-
 type GarbageCollectPredicate struct {
 	predicate.Funcs
 	Scheme  *runtime.Scheme

docs/spec/v1alpha1/README.md

@@ -1,6 +1,6 @@
 # source.fluxcd.io/v1alpha1
 
-The is the v1alpha1 API specification for defining the desired state sources of Kubernetes clusters.
+This is the v1alpha1 API specification for defining the desired state sources of Kubernetes clusters.
 
 ## Specification
 
@@ -12,4 +12,8 @@ The is the v1alpha1 API specification for defining the desired state sources of
 
 ## Implementation
 
-* source-controller [v0.0.1-alpha.1](https://github.com/fluxcd/source-controller/releases)
+* [source-controller](https://github.com/fluxcd/source-controller/)
+
+## Consumers
+
+* [kustomize-controller](https://github.com/fluxcd/kustomize-controller/)

docs/spec/v1alpha1/common.md

@@ -37,12 +37,12 @@ The controller can be told to check for updates right away by setting an annotat
 
 ```go
 const (
-	// ForceSyncAnnotation is the timestamp corresponding to an on-demand source sync.
-	ForceSyncAnnotation string = "source.fluxcd.io/syncAt"
+	// SyncAtAnnotation is the timestamp corresponding to an on-demand source sync.
+	SyncAtAnnotation string = "source.fluxcd.io/syncAt"
 )
 ```
 
-Force sync example:
+Trigger source sync example:
 
 ```bash
 kubectl annotate --overwrite gitrepository/podinfo source.fluxcd.io/syncAt="$(date +%s)"
@@ -143,4 +143,4 @@ const (
 
 ## Examples
 
-See the [Git repository](gitrepositories.md) and [Helm chart](helmrepositories.md) APIs.
+See the [Git repository](gitrepositories.md) and [Helm chart](helmcharts.md) APIs.

docs/spec/v1alpha1/gitrepositories.md

@@ -297,17 +297,17 @@ Successful sync:
 status:
   artifact:
     lastUpdateTime: "2020-04-07T06:59:23Z"
-    path: /data/gitrepository/podinfo-default/363a6a8fe6a7f13e05d34c163b0ef02a777da20a.tar.gz
+    path: /data/gitrepository/default/podinfo/363a6a8fe6a7f13e05d34c163b0ef02a777da20a.tar.gz
     revision: master/363a6a8fe6a7f13e05d34c163b0ef02a777da20a
-    url: http://<host>/gitrepository/podinfo-default/363a6a8fe6a7f13e05d34c163b0ef02a777da20a.tar.gz
+    url: http://<host>/gitrepository/default/podinfo/363a6a8fe6a7f13e05d34c163b0ef02a777da20a.tar.gz
   conditions:
   - lastTransitionTime: "2020-04-07T06:59:23Z"
-    message: 'Fetched artifacts are available at
-      /data/gitrepository/podinfo-default/363a6a8fe6a7f13e05d34c163b0ef02a777da20a.tar.gz'
+    message: 'Git repoistory artifacts are available at:
+      /data/gitrepository/default/podinfo/363a6a8fe6a7f13e05d34c163b0ef02a777da20a.tar.gz'
     reason: GitOperationSucceed
     status: "True"
     type: Ready
-  url: http://<host>/gitrepository/podinfo-default/latest.tar.gz
+  url: http://<host>/gitrepository/default/podinfo/latest.tar.gz
 ```
 
 Failed authentication:
@@ -335,7 +335,7 @@ status:
     type: Ready
 ```
 
-Wait for condition:
+Wait for ready condition:
 
 ```bash
 kubectl wait gitrepository/podinfo --for=condition=ready --timeout=1m

docs/spec/v1alpha1/helmcharts.md

@@ -66,7 +66,7 @@ const (
 
 ## Spec examples
 
-Pinned version:
+Pull a specific chart version every five minutes:
 
 ```yaml
 apiVersion: source.fluxcd.io/v1alpha1
@@ -82,9 +82,10 @@ spec:
   version: 10.5.7
   helmRepositoryRef:
     name: stable
+  interval: 5m
 ```
 
-Semver range:
+Pull the latest chart version that matches the sermver range every ten minutes:
 
 ```yaml
 apiVersion: source.fluxcd.io/v1alpha1
@@ -97,22 +98,7 @@ spec:
   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
+  interval: 10m
 ```
 
 ## Status examples
@@ -121,10 +107,10 @@ Successful chart pull:
 
 ```yaml
 status:
-  url: http://<host>/helmcharts/redis-default/redis-10.5.7.tgz
+  url: http://<host>/helmchart/default/redis/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
+      message: Helm chart is available at /data/helmchart/default/redis/redis-10.5.7.tgz
       reason: ChartPullSucceeded
       status: "True"
       type: Ready
@@ -136,8 +122,14 @@ Failed chart pull:
 status:
   conditions:
     - lastTransitionTime: "2020-04-10T09:34:45Z"
-      message: ''
+      message: 'invalid chart URL format'
       reason: ChartPullFailed
       status: "False"
       type: Ready
 ```
+
+Wait for ready condition:
+
+```bash
+kubectl wait helmchart/redis --for=condition=ready --timeout=1m
+```

docs/spec/v1alpha1/helmrepositories.md

@@ -64,23 +64,20 @@ const (
 
 ## Spec examples
 
-Public Helm repository:
+Pull the index of a public Helm repository every ten minutes:
 
 ```yaml
 apiVersion: source.fluxcd.io/v1alpha1
 kind: HelmRepository
 metadata:
   name: stable
   namespace: default
-  annotations:
-    # force sync trigger
-    source.fluxcd.io/syncAt: "2020-04-06T15:39:52+03:00"
 spec:
   url: https://kubernetes-charts.storage.googleapis.com/
-  interval: 1m
+  interval: 10m
 ```
 
-Private Helm repository:
+Pull the index of a private Helm repository every minute:
 
 ```yaml
 apiVersion: source.fluxcd.io/v1alpha1
@@ -114,10 +111,10 @@ Successful indexation:
 
 ```yaml
 status:
-  url: http://<host>/helmrepository/podinfo-default/index.yaml
+  url: http://<host>/helmrepository/default/stable/index.yaml
   conditions:
     - lastTransitionTime: "2020-04-10T09:34:45Z"
-      message: Fetched artifact are available at /data/helmrepositories/podinfo-default/index-21c195d78e699e4b656e2885887d019627838993.yaml
+      message: Helm repository index is available at /data/helmrepository/default/stable/index-21c195d78e699e4b656e2885887d019627838993.yaml
       reason: IndexationSucceeded
       status: "True"
       type: Ready
@@ -146,3 +143,9 @@ status:
     status: "False"
     type: Ready
 ```
+
+Wait for ready condition:
+
+```bash
+kubectl wait helmrepository/stable --for=condition=ready --timeout=1m
+```