Document supported timestamp image labels

site/fluxctl.md

@@ -15,7 +15,7 @@ menu_order: 40
     + [2. Specify a key to use](#2-specify-a-key-to-use)
 - [Workloads](#workloads)
   * [What is a Workload?](#what-is-a-workload)
-  *  [Viewing Workloads](#viewing-workloads)
+  * [Viewing Workloads](#viewing-workloads)
   * [Inspecting the Version of a Container](#inspecting-the-version-of-a-container)
   * [Releasing a Workload](#releasing-a-workload)
   * [Turning on Automation](#turning-on-automation)
@@ -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,21 @@ 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` date and time on which the image was built (string, date-time as defined by RFC 3339).
+- `org.label-schema.build-date` 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: