New documentation structure

README.md

@@ -10,7 +10,20 @@ images running in the cluster, as well as the latest available upstream. These
 checks get exposed as Prometheus metrics to be viewed on a dashboard, or _soft_
 alert cluster operators.
 
-## Registries
+---
+
+## Why Use version-checker?
+
+- **Improved Security**: Ensures images are up-to-date, reducing the risk of using vulnerable or compromised versions.
+- **Enhanced Visibility**: Provides a clear overview of all running container versions across clusters.
+- **Operational Efficiency**: Automates image tracking and reduces manual intervention in version management.
+- **Compliance and Policy**: Enforcement: Helps maintain version consistency and adherence to organizational policies.
+- **Incremental Upgrades**: Facilitates frequent, incremental updates to reduce the risk of large, disruptive upgrades.
+- **Add-On Compatibility**: Ensures compatibility with the latest versions of Kubernetes add-ons and dependencies.
+
+---
+
+## Registries Supported
 
 version-checker supports the following registries:
 
@@ -28,32 +41,14 @@ These registries support authentication.
 
 ---
 
-## Installation
-
-version-checker can be installed as either static manifests;
+## Documentation
 
-```sh
-$ kubectl apply -k ./deploy/yaml
-```
+- [Installation Guide](docs/installation.md)
+- [Metrics](docs/metrics.md)
 
-Or through helm;
-
-```sh
-$ helm repo add jetstack https://charts.jetstack.io
-"jetstack" has been added to your repositories
-$ helm install version-checker jetstack/version-checker
-NAME: version-checker
-LAST DEPLOYED: Wed Jul 12 17:47:41 2023
-NAMESPACE: default
-STATUS: deployed
-REVISION: 1
-TEST SUITE: None
-```
-
-The helm chart supports creating a Prometheus/ServiceMonitor to expose the
-version-checker metrics.
+---
 
-#### Grafana Dashboard
+### Grafana Dashboard
 
 A [grafana dashboard](https://grafana.com/grafana/dashboards/12833) is also
 available to view the image versions as a table.
@@ -64,61 +59,9 @@ available to view the image versions as a table.
   <b>Grafana Dashboard</b><br>
 </p>
 
----
-
-## Options
-
-By default, without the flag `-a, --test-all-containers`, version-checker will
-only test containers where the pod has the annotation
-`enable.version-checker.io/*my-container*`, where `*my-container*` is the `name`
-of the container in the pod.
-
-version-checker supports the following annotations present on **other** pods to
-enrich version checking on image tags:
-
-- `pin-major.version-checker.io/my-container: 4`: will pin the major version to
-    check to 4 (`v4.0.0`).
-
-- `pin-minor.version-checker.io/my-container: 3`: will pin the minor version to
-    check to 3 (`v0.3.0`).
-
-- `pin-patch.version-checker.io/my-container: 23`: will pin the patch version to
-    check to 23 (`v0.0.23`).
-
-- `use-metadata.version-checker.io/my-container: "true"`: will allow to search
-    for image tags which contain information after the first part of the semver
-    string. For example, this can be pre-releases or build metadata
-    (`v1.2.4-alpha.0`, `v1.2.3-debian-r3`).
-
-- `use-sha.version-checker.io/my-container: "true"`: will check against the latest
-    SHA tag available. Essentially, the latest image by date. This is silently
-    set to true if no image tag, or "latest" image tag is set. Cannot be used with
-    any other options.
-
-- `match-regex.version-checker.io/my-container: ^v\d+\.\d+\.\d+-debian-`: is
-    used for only comparing against image tags which match the regex set. For
-    example, the above annotation will only check against image tags which have
-    the form of something like `v1.3.4-debian-r30`.
-    `use-metadata.version-checker.io` is not required when this is set. All
-    other options, apart from URL overrides, are ignored when this is set.
-
-- `override-url.version-checker.io/my-container: docker.io/bitnami/etcd`: is
-    used to change the URL for where to lookup where the latest image version
-    is. In this example, the current version of `my-container` will be compared
-    against the image versions in the `docker.io/bitnami/etcd` registry.
-
-- `resolve-sha-to-tags.version-checker.io/my-container`: is used to
-    resolve images specified using sha256 in kubernetes manifests to valid semver
-    tags. To enable this the annotation value must be set to "true".
-
 ## Known configurations
 
 From time to time, version-checker may need some of the above options applied to determine the latest version,
 depending on how the maintainers publish their images. We are making a conscious effort to collate some of these configurations.
 
-See [known-configurations.md](known-configurations.md) for more details.
-
-## Metrics
-
-By default, version-checker will expose the version information as Prometheus
-metrics on `0.0.0.0:8080/metrics`.
+See [known-configurations.md](../known-configurations.md) for more details.

docs/installation.md

@@ -0,0 +1,85 @@
+# Installation
+
+`version-checker` can be installed using either static manifests or Helm.
+
+---
+
+## Install Using Static Manifests
+
+To install using static manifests, run:
+
+```sh
+kubectl apply -k ./deploy/yaml
+```
+
+## Install Using Helm
+To install using Helm, add the Jetstack Helm repository and install the chart:
+
+```sh
+helm repo add jetstack https://charts.jetstack.io
+"jetstack" has been added to your repositories
+
+helm install version-checker jetstack/version-checker
+```
+
+Output:
+
+```sh
+NAME: version-checker
+LAST DEPLOYED: Wed Jul 12 17:47:41 2023
+NAMESPACE: default
+STATUS: deployed
+REVISION: 1
+TEST SUITE: None
+```
+
+### Prometheus Operator Integration
+
+The Helm chart supports creating a [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator) `ServiceMonitor` to expose version-checker's metrics.
+
+## Options
+
+By default, version-checker will only test containers where the pod has the annotation
+`enable.version-checker.io/*my-container*`, where `*my-container*` is the `name`
+of the container in the pod.
+
+However, by passing the following flag,`-a, --test-all-containers` version-checker will test all containers within the cluster.
+
+### Supported Annotations
+
+`version-checker` supports the following annotations to enrich version checking on image tags:
+
+- `pin-major.version-checker.io/my-container: 4`: will pin the major version to
+    check to 4 (`v4.0.0`).
+
+- `pin-minor.version-checker.io/my-container: 3`: will pin the minor version to
+    check to 3 (`v0.3.0`).
+
+- `pin-patch.version-checker.io/my-container: 23`: will pin the patch version to
+    check to 23 (`v0.0.23`).
+
+- `use-metadata.version-checker.io/my-container: "true"`: will allow to search
+    for image tags which contain information after the first part of the semver
+    string. For example, this can be pre-releases or build metadata
+    (`v1.2.4-alpha.0`, `v1.2.3-debian-r3`).
+
+- `use-sha.version-checker.io/my-container: "true"`: will check against the latest
+    SHA tag available. Essentially, the latest image by date. This is silently
+    set to true if no image tag, or "latest" image tag is set. Cannot be used with
+    any other options.
+
+- `match-regex.version-checker.io/my-container: ^v\d+\.\d+\.\d+-debian-`: is
+    used for only comparing against image tags which match the regex set. For
+    example, the above annotation will only check against image tags which have
+    the form of something like `v1.3.4-debian-r30`.
+    `use-metadata.version-checker.io` is not required when this is set. All
+    other options, apart from URL overrides, are ignored when this is set.
+
+- `override-url.version-checker.io/my-container: docker.io/bitnami/etcd`: is
+    used to change the URL for where to lookup where the latest image version
+    is. In this example, the current version of `my-container` will be compared
+    against the image versions in the `docker.io/bitnami/etcd` registry.
+
+- `resolve-sha-to-tags.version-checker.io/my-container`: is used to
+    resolve images specified using sha256 in kubernetes manifests to valid semver
+    tags. To enable this the annotation value must be set to "true".

docs/metrics.md

@@ -0,0 +1,17 @@
+# Metrics
+
+By default, version-checker exposes the following Prometheus metrics on `0.0.0.0:8080/metrics`:
+
+- `version_checker_is_latest_version`: Indicates whether the container in use is using the latest upstream registry version.
+- `version_checker_last_checked`: Timestamp when the image was last checked.
+- `version_checker_image_lookup_duration`: Duration of the image version check.
+- `version_checker_image_failures_total`: Total of errors encountered during image version checks.
+
+---
+
+## Example Prometheus Query
+
+```sh
+QUERY="version_checker_is_latest_version"
+curl -s --get --data-urlencode query=$QUERY <PROMETHEUS_URL>
+```