Merge pull request #90 from fluxcd/api-examples

Add examples to the API spec docs

Author: stefanprodan

docs/spec/v1alpha1/imagepolicies.md

@@ -3,7 +3,8 @@
 
 The `ImagePolicy` type gives rules for selecting a "latest" image from a scanned
 `ImageRepository`. This can be used to drive automation, as with the
-[image-automation-controller][]; or more generally, to inform other processes of the state of an
+[image-automation-controller][];
+or more generally, to inform other processes of the state of an
 image repository.
 
 ## Specification
@@ -31,7 +32,6 @@ type ImagePolicySpec struct {
 The field `ImageRepositoryRef` names an `ImageRepository` object in the same namespace. It is this
 object that provides the scanned image metadata for the policy to use in selecting an image.
 
-
 ### Policy
 
 The ImagePolicy field specifies how to choose a latest image given the image metadata. The choice is
@@ -94,8 +94,8 @@ type TagFilter struct {
 The `FilterTags` field gives you the opportunity to filter the image tags _before_ they are
 considered by the policy rule.
 
-The `Pattern` field takes a regular expression which can match anywhere in the tag string. Only tags
-that match the pattern are considered by the policy rule.
+The `Pattern` field takes a [regular expression][regex-go] which can match anywhere in the tag string.
+Only tags that match the pattern are considered by the policy rule.
 
 The optional `Extract` value will be expanded for each tag that matches the pattern. The resulting
 values will be supplied to the policy rule instead of the original tags. If `Extract` is empty, then
@@ -124,5 +124,77 @@ The `LatestImage` field contains the image selected by the policy rule, when it
 There is one condition that may be present: the GitOps toolkit-standard `ReadyCondition`. This will
 be marked as true when the policy rule has selected an image.
 
+## Examples
+
+Select the latest `dev` branch build tagged as `<BRANCH>-<BUILD-ID>` (alphabetical):
+
+```yaml
+kind: ImagePolicy
+spec:
+  filterTags:
+    pattern: '^dev-(?P<id>.*)'
+    extract: '$id'
+  policy:
+    alphabetical:
+      order: asc
+```
+
+Select the latest stable version (semver):
+
+```yaml
+kind: ImagePolicy
+spec:
+  policy:
+    semver:
+      range: '>=1.0.0'
+```
+
+Select the latest stable patch version in the 1.x range (semver):
+
+```yaml
+kind: ImagePolicy
+spec:
+  policy:
+    semver:
+      range: '>=1.0.0 <2.0.0'
+```
+
+Select the latest version including pre-releases (semver):
+
+```yaml
+kind: ImagePolicy
+spec:
+  policy:
+    semver:
+      range: '>=1.0.0-0'
+```
+
+Select the latest release candidate (semver):
+
+```yaml
+kind: ImagePolicy
+spec:
+  filterTags:
+   pattern: '.*-rc.*'
+  policy:
+    semver:
+      range: '^1.x-0'
+```
+
+Select the latest release tagged as `RELEASE.<RFC3339-TIMESTAMP>`
+e.g. [Minio](https://hub.docker.com/r/minio/minio) (alphabetical):
+
+```yaml
+kind: ImagePolicy
+spec:
+  filterTags:
+    pattern: '^RELEASE\.(?P<timestamp>.*)Z$'
+    extract: '$timestamp'
+  policy:
+    alphabetical:
+      order: asc
+```
+
 [image-automation-controller]: https://github.com/image-automation-controller
 [semver-range]: https://github.com/Masterminds/semver#checking-version-constraints
+[regex-go]: https://golang.org/pkg/regexp/syntax

docs/spec/v1alpha1/imagerepositories.md

@@ -98,5 +98,39 @@ type ScanResult struct {
 There is one condition used: the GitOps toolkit-standard `ReadyCondition`. This will be marked as
 true when a scan succeeds, and false when a scan fails.
 
+### Examples
+
+Fetch metadata for a public image every ten minutes:
+
+```yaml
+apiVersion: image.toolkit.fluxcd.io/v1alpha1
+kind: ImageRepository
+metadata:
+  name: podinfo
+  namespace: flux-system
+spec:
+  interval: 10m
+  image: ghcr.io/stefanprodan/podinfo
+```
+
+Fetch metadata for a private image every minute:
+
+```yaml
+apiVersion: image.toolkit.fluxcd.io/v1alpha1
+kind: ImageRepository
+metadata:
+  name: podinfo
+  namespace: flux-system
+spec:
+  interval: 1m0s
+  image: docker.io/org/image
+  secretRef:
+    name: regcred
+```
+
+For private images, you can create a Kubernetes secret in the same namespace
+as the `ImageRepository` with `kubectl create secret docker-registry`,
+and reference it under `secretRef`.
+
 [image-pull-secrets]: https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod
 [image-auto-provider-secrets]: https://toolkit.fluxcd.io/guides/image-update/#imagerepository-cloud-providers-authentication