docs: Document latest features (#29)

* docs: Reflect latest changes in docs

* Updates

* Update docs

1 files changed, 150 insertions, 20 deletions

diff --git a/docs/configuration/images.md b/docs/configuration/images.md
index 8ceab3f..0b0a22c 100644
--- a/docs/configuration/images.md
+++ b/docs/configuration/images.md
@@ -7,17 +7,17 @@ considered for updates. To specify those images, the following annotation
 is used:
 
 ```yaml
-argocd-image-updater.argoproj.io/image-list: <image spec list>
+argocd-image-updater.argoproj.io/image-list: <image_spec_list>
 ```
 
-The `<image spec list>` is a comma separated list of image specifications. Each
+The `<image_spec_list>` is a comma separated list of image specifications. Each
 image specification is composed of mandatory and optional information, and is
 used to specify the image, its version constraint and a few meta data.
 
 An image specification could be formally described as:
 
 ```text
-[<image_name>=]<image_path>[:<version_constraint>][#<secret ref>]
+[<alias_name>=]<image_path>[:<version_constraint>]
 ```
 
 Specifying the fields denoted in square brackets is optional and can be left
@@ -52,9 +52,22 @@ in the
 [documentation](https://github.com/Masterminds/semver#checking-version-constraints)
 of the [Semver library](https://github.com/Masterminds/semver) we're using.
 
-## Naming images
+## Assigning aliases to images
 
-Giving a name to an image is necessary in these scenarios:
+It's possible (and sometimes necessary) to assign an alias name to any given
+image. Alias names should consist of alphanumerical characters only, and must
+be unique within the same application. Re-using an alias name across different
+applications is allowed.
+
+An alias name is assigned during image specification in the `image-list`
+annotation, for example the following would assign the alias `myalias` to the
+image `some/image`:
+
+```yaml
+argocd-image-updater.argproj.io/image-list: myalias=some/image
+```
+
+Assigning an alias name to an image is necessary in these scenarios:
 
 * If you want to use custom images with Kustomize. In this case, the name must
   match to what is defined in your Kustomize base.
@@ -63,7 +76,38 @@ Giving a name to an image is necessary in these scenarios:
   and version using Helm and the parameter names do not equal `image.name` and
   `image.tag`. In this case, the name is just symbolic.
 
-### Custom images with Kustomize
+* If you want to set custom options for a given image's update strategy, or
+  require referencing unique pull secrets for each image
+
+The alias you assign to any image will be reused as a key in the annotations
+used to define further options, so a little care should be taken when defining
+such a name. It's generally advised to use only alpha-numerical characters. The
+character `/` (forward-slash) can be used in the name, but must be referenced
+as `_` (underscore) in the annotation. This is a limit of Kubernetes. So for
+example, if you assign the alias `argoproj/argocd` to your image, the
+appropriate key in the annotation would be referenced as `argoproj_argocd`.
+
+## Update strategies
+
+Argo CD Image Updater can update images according to the following strategies:
+
+|Strategy|Description|
+|--------|-----------|
+|`semver`| Update to the tag with the highest allowed semantic version|
+|`latest`| Update to the tag with the most recent creation date|
+|`name`  | Update to the tag with the latest entry from an alphabetically sorted list|
+
+You can define the update strategy for each image independently by setting the
+following annotation to an appropriate value:
+
+```yaml
+argocd-image-updater.argoproj.io/<image_name>.update-strategy: <strategy>
+```
+
+If no update strategy is given, or an invalid value was used, the default
+strategy `semver` will be used.
+
+## Custom images with Kustomize
 
 In Kustomize, if you want to use an image from another registry or a completely
 different image than what is specified in the manifests, you can give the image
@@ -86,19 +130,13 @@ you could override the image specification in Kustomize as follows:
 argoproj/argocd=docker.pkg.github.com/argoproj/argo-cd/argocd:1.7.0-a6399e59
 ```
 
-### Specifying Helm parameter names
-
-!!!note
-    Image names should not be too complex. In case of Helm, they must only
-    consist of letters and numbers because the names will be reused in
-    Kubernetes annotation names, and thus, must fit in the overall naming
-    convention of Kubernetes annotation names.
+## Specifying Helm parameter names
 
 In case of Helm applications which contain more than one image in the manifests
 or use another set of parameters than `image.name` and `image.tag` to define
-which image to render in the manifests, you can use the `<name>` parameter in
-the image specification to define a (symbolic) name for that image. Then, you
-can use another set of annotations to specify the appropriate parameter names
+which image to render in the manifests, you need to set an `<image_alias>`
+in the image specification to define an alias for that image, and then
+use another set of annotations to specify the appropriate parameter names
 that should get set if an image gets updated.
 
 For example, if you have an image `quay.io/dexidp/dex` that is configured in
@@ -108,13 +146,105 @@ Argo CD Image Updater will know which Helm parameters to set:
 
 ```yaml
 argocd-image-updater.argoproj.io/image-list: dex=quay.io/dexidp/dex
-argocd-image-updater.argoproj.io/dex.image-name: dex.image.name
-argocd-image-updater.argoproj.io/dex.image-tag: dex.image.tag
+argocd-image-updater.argoproj.io/dex.helm.image-name: dex.image.name
+argocd-image-updater.argoproj.io/dex.helm.image-tag: dex.image.tag
 
 ```
 
 The general syntax for the two Helm specific annotations is:
 
 ```yaml
-argocd-image-updater.argoproj.io/<name>.image-name: <name of helm parameter to set>
-```
\ No newline at end of file
+argocd-image-updater.argoproj.io/<image_alias>.helm.image-name: <name of helm parameter to set for the image name>
+argocd-image-updater.argoproj.io/<image_alias>.helm.image-tag: <name of helm parameter to set for the image tag>
+```
+
+If the chart uses a parameter for the canonical name of the image (i.e. image
+name and tag combined), a third option can be used:
+
+```yaml
+argocd-image-updater.argoproj.io/<image_alias>.helm.image-spec: <name of helm parameter to set for canonical name of image>
+```
+
+If the `<image_alias>.helm.image-spec` annotation is set, the two other
+annotations `<image_alias>.helm.image-name` and `<image_alias>.helm.image-tag`
+will be ignored.
+
+## Examples
+
+### Following an image's patch branch
+
+*Scenario:* You have deployed image `nginx:1.19.1` and want to make sure it's
+always up-to-date to the latest patch level within the `1.19` branch.
+
+*Solution:* Use standard `semver` update strategy with a constraint on the
+patch level (`~`), i.e.
+
+```yaml
+argocd-image-updater.argoproj.io/image-list: nginx:~1.19
+```
+
+### Always deploy the latest build
+
+*Scenario:* Your CI regulary pushes images built from the latest source, using
+some identifier (i.e. the hash of the Git commit) in the tag.
+
+*Solution:*
+
+1. Make sure that the image tags follow semantic versioning and use the Git
+   commit hash as pre-release identifier, i.e. `v1.0.0-<githash>`
+
+2. Define an alias for your image when configuring it for update, and match
+   against pre-release in the version constraint by prepending `-0`.
+
+3. Use `latest` as update strategy
+
+Annotations might look like follows:
+
+```yaml
+argocd-image-updater.argoproj.io/image-list: yourtool=yourorg/yourimage:v1.0.0-0
+argocd-image-updater.argoproj.io/yourtool.update-strategy: latest
+```
+
+### Multiple images in the same Helm chart
+
+*Scenario:* You want to update multiple images within the same Helm chart to
+their latest available version according to semver. 
+
+The Helm parameters to set the image version
+are `foo.image` and `foo.tag` for the first image, and `bar.image` and
+`bar.tag` for the second image. The image names are `foo/bar` and `bar/foo`
+for simplicity.
+
+*Solution:*
+
+1. Define an alias for both images, i.e. `fooalias` and `baralias`
+
+2. Set `helm.image-name` and `helm.image-tag` for both aliases to their
+   appropriate values
+
+Annotations might look like follows:
+
+```yaml
+argocd-image-updater.argoproj.io/image-list: fooalias=foo/bar, baralias=bar/foo
+argocd-image-updater.argoproj.io/fooalias.helm.image-name: foo.image
+argocd-image-updater.argoproj.io/fooalias.helm.image-tag: foo.tag
+argocd-image-updater.argoproj.io/baralias.helm.image-name: bar.image
+argocd-image-updater.argoproj.io/baralias.helm.image-tag: bar.tag
+```
+
+## Appendix
+
+### Available annotations
+
+The following is a complete list of available annotations to control the
+update strategy and set options for images. Please note, all annotations
+must be prefixed with `argocd-image-updater.argoproj.io`.
+
+|Annotation name|Default value|Description|
+|---------------|-------|-----------|
+|`image-list`|*none*|Comma separated list of images to consider for update|
+|`<image_alias>.update-strategy`|`semver`|The update strategy to be used for the image|
+|`<image_alias>.helm.image-spec`|*none*|Name of the Helm parameter to specify the canonical name of the image, i.e. holds `image/name:1.0`. If this is set, other Helm parameter related options will be ignored.|
+|`<image_alias>.helm.image-name`|`image.name`|Name of the Helm parameter used for specifying the image name, i.e. holds `image/name`|
+|`<image_alias>.helm.image-tag`|`image.tag`|Name of the Helm parameter used for specifying the image tag, i.e. holds `1.0`|
+|`<image_alias>.kustomize.image-name`|*original name of image*|Name of Kustomize image parameter to set during updates|