diff --git a/README.md b/README.md index 981a74eb..48216780 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. @@ -64,61 +59,9 @@ 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`. +See [known-configurations.md](../known-configurations.md) for more details. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..42b91e81 --- /dev/null +++ b/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". 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