Document supported timestamp image labels
@@ -27,9 +27,11 @@ menu_order: 40
* [Recording user and message with the triggered action](#recording-user-and-message-with-the-triggered-action)
- [Image Tag Filtering](#image-tag-filtering)
* [Filter pattern types](#filter-pattern-types)
- * [Glob](#glob)
- * [Semver](#semver)
- * [Regexp](#regexp)
+ + [Glob](#glob)
+ + [Semver](#semver)
+ + [Regexp](#regexp)
+ * [Controlling image timestamps with labels](#controlling-image-timestamps-with-labels)
+ + [Supported label formats](#supported-label-formats)
- [Actions triggered through `fluxctl`](#actions-triggered-through-fluxctl)
* [Errors due to author customization](#errors-due-to-author-customization)
- [Using Annotations](#using-annotations)
@@ -497,11 +499,11 @@ fluxctl release --workload=default:deployment/helloworld --update-all-images --f
Please note that automation might immediately undo this.
-# Filter pattern types
+## Filter pattern types
Flux currently offers support for `glob`, `semver` and `regexp` based filtering.
-## Glob
+### Glob
The glob (`*`) filter is the simplest filter Flux supports, a filter can contain
multiple globs:
@@ -510,7 +512,7 @@ multiple globs:
fluxctl policy --workload=default:deployment/helloworld --tag-all='glob:master-v1.*.*'
```
-## Semver
+### Semver
If your images use [semantic versioning](https://semver.org) you can filter by image tags
that adhere to certain constraints:
@@ -528,7 +530,7 @@ fluxctl policy --workload=default:deployment/helloworld --tag-all='semver:*'
Using a semver filter will also affect how Flux sorts images, so
that the higher versions will be considered newer.
-## Regexp
+### Regexp
If your images have complex tags you can filter by regular expression:
@@ -540,6 +542,23 @@ Instead of `regexp` it is also possible to use its alias `regex`.
Please bear in mind that if you want to match the whole tag,
you must bookend your pattern with `^` and `$`.
+## Controlling image timestamps with labels
+
+Some image registries do not expose a reliable creation timestamp for
+image tags, which could pose a problem for the automated roll-out of
+images.
+
+To overcome this problem you can define one of the supported labels in
+your `Dockerfile`. Flux will prioritize labels over the timestamp it
+retrieves from the registry.
+
+### Supported label formats
+
+- [`org.opencontainers.image.created`](https://github.com/opencontainers/image-spec/blob/master/annotations.md#pre-defined-annotation-keys)
+ date and time on which the image was built (string, date-time as defined by RFC 3339).
+- [`org.label-schema.build-date`](http://label-schema.org/rc1/#build-time-labels)
+ date and time on which the image was built (string, date-time as defined by RFC 3339).
+
# Actions triggered through `fluxctl`
`fluxctl` provides the following flags for the message and author customization:
