From 5e3f2d1a0fa52e745a7d2652aeedbde3c23f05cc Mon Sep 17 00:00:00 2001 From: maria-reynoso Date: Wed, 30 Apr 2025 17:27:17 +0200 Subject: [PATCH 1/4] Update documentation --- README.md | 102 ++++++++----------------------------------- docs/installation.md | 91 ++++++++++++++++++++++++++++++++++++++ docs/metrics.md | 17 ++++++++ 3 files changed, 127 insertions(+), 83 deletions(-) create mode 100644 docs/installation.md create mode 100644 docs/metrics.md diff --git a/README.md b/README.md index 981a74eb..407e583b 100644 --- a/README.md +++ b/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. @@ -63,62 +58,3 @@ available to view the image versions as a table.

Grafana Dashboard

- ---- - -## 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`. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..b887f9f4 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,91 @@ +# 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 Integration + +The Helm chart supports creating a Prometheus ServiceMonitor to expose the version-checker metrics. + +## 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. + +### 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". + +## 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. diff --git a/docs/metrics.md b/docs/metrics.md new file mode 100644 index 00000000..8393f8b6 --- /dev/null +++ b/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 +``` \ No newline at end of file From 7d99f7e2d7b38c3b559f0c56da12b93193d3ba68 Mon Sep 17 00:00:00 2001 From: Maria Reynoso <62747554+maria-reynoso@users.noreply.github.com> Date: Thu, 1 May 2025 10:49:34 +0200 Subject: [PATCH 2/4] Update docs/installation.md Co-authored-by: David Collom --- docs/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index b887f9f4..b80d4fef 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -33,9 +33,9 @@ REVISION: 1 TEST SUITE: None ``` -### Prometheus Integration +### Prometheus Operator Integration -The Helm chart supports creating a Prometheus ServiceMonitor to expose the version-checker metrics. +The Helm chart supports creating a [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator) `ServiceMonitor` to expose version-checker's metrics. ## Options From 9efabe8c8d83b103479961d8bcc7db7064fe98f0 Mon Sep 17 00:00:00 2001 From: Maria Reynoso <62747554+maria-reynoso@users.noreply.github.com> Date: Thu, 1 May 2025 10:49:44 +0200 Subject: [PATCH 3/4] Update docs/installation.md Co-authored-by: David Collom --- docs/installation.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index b80d4fef..41e47ea3 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -39,11 +39,12 @@ The Helm chart supports creating a [Prometheus Operator](https://github.com/prom ## Options -By default, without the flag `-a, --test-all-containers`, version-checker will -only test containers where the pod has the annotation +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: From 4d26fff37dca246b93c432dff61b2c4a2f26d81e Mon Sep 17 00:00:00 2001 From: maria-reynoso Date: Thu, 1 May 2025 10:51:10 +0200 Subject: [PATCH 4/4] update readme --- README.md | 7 +++++++ docs/installation.md | 7 ------- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 407e583b..48216780 100644 --- a/README.md +++ b/README.md @@ -58,3 +58,10 @@ available to view the image versions as a table.

Grafana Dashboard

+ +## 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. diff --git a/docs/installation.md b/docs/installation.md index 41e47ea3..42b91e81 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -83,10 +83,3 @@ However, by passing the following flag,`-a, --test-all-containers` version-check - `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.