Skip to content

Commit 2ab5c71

Browse files
maria-reynosodavidcollom
maria-reynoso
and
davidcollom
authored
New documentation structure (#375)
Co-authored-by: David Collom <[email protected]>
1 parent 27598f9 commit 2ab5c71

File tree

3 files changed

+122
-77
lines changed

3 files changed

+122
-77
lines changed

‎README.md

Lines changed: 20 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,20 @@ images running in the cluster, as well as the latest available upstream. These
1010
checks get exposed as Prometheus metrics to be viewed on a dashboard, or _soft_
1111
alert cluster operators.
1212

13-
## Registries
13+
---
14+
15+
## Why Use version-checker?
16+
17+
- **Improved Security**: Ensures images are up-to-date, reducing the risk of using vulnerable or compromised versions.
18+
- **Enhanced Visibility**: Provides a clear overview of all running container versions across clusters.
19+
- **Operational Efficiency**: Automates image tracking and reduces manual intervention in version management.
20+
- **Compliance and Policy**: Enforcement: Helps maintain version consistency and adherence to organizational policies.
21+
- **Incremental Upgrades**: Facilitates frequent, incremental updates to reduce the risk of large, disruptive upgrades.
22+
- **Add-On Compatibility**: Ensures compatibility with the latest versions of Kubernetes add-ons and dependencies.
23+
24+
---
25+
26+
## Registries Supported
1427

1528
version-checker supports the following registries:
1629

@@ -28,32 +41,14 @@ These registries support authentication.
2841

2942
---
3043

31-
## Installation
32-
33-
version-checker can be installed as either static manifests;
44+
## Documentation
3445

35-
```sh
36-
$ kubectl apply -k ./deploy/yaml
37-
```
46+
- [Installation Guide](docs/installation.md)
47+
- [Metrics](docs/metrics.md)
3848

39-
Or through helm;
40-
41-
```sh
42-
$ helm repo add jetstack https://charts.jetstack.io
43-
"jetstack" has been added to your repositories
44-
$ helm install version-checker jetstack/version-checker
45-
NAME: version-checker
46-
LAST DEPLOYED: Wed Jul 12 17:47:41 2023
47-
NAMESPACE: default
48-
STATUS: deployed
49-
REVISION: 1
50-
TEST SUITE: None
51-
```
52-
53-
The helm chart supports creating a Prometheus/ServiceMonitor to expose the
54-
version-checker metrics.
49+
---
5550

56-
#### Grafana Dashboard
51+
### Grafana Dashboard
5752

5853
A [grafana dashboard](https://grafana.com/grafana/dashboards/12833) is also
5954
available to view the image versions as a table.
@@ -64,61 +59,9 @@ available to view the image versions as a table.
6459
<b>Grafana Dashboard</b><br>
6560
</p>
6661

67-
---
68-
69-
## Options
70-
71-
By default, without the flag `-a, --test-all-containers`, version-checker will
72-
only test containers where the pod has the annotation
73-
`enable.version-checker.io/*my-container*`, where `*my-container*` is the `name`
74-
of the container in the pod.
75-
76-
version-checker supports the following annotations present on **other** pods to
77-
enrich version checking on image tags:
78-
79-
- `pin-major.version-checker.io/my-container: 4`: will pin the major version to
80-
check to 4 (`v4.0.0`).
81-
82-
- `pin-minor.version-checker.io/my-container: 3`: will pin the minor version to
83-
check to 3 (`v0.3.0`).
84-
85-
- `pin-patch.version-checker.io/my-container: 23`: will pin the patch version to
86-
check to 23 (`v0.0.23`).
87-
88-
- `use-metadata.version-checker.io/my-container: "true"`: will allow to search
89-
for image tags which contain information after the first part of the semver
90-
string. For example, this can be pre-releases or build metadata
91-
(`v1.2.4-alpha.0`, `v1.2.3-debian-r3`).
92-
93-
- `use-sha.version-checker.io/my-container: "true"`: will check against the latest
94-
SHA tag available. Essentially, the latest image by date. This is silently
95-
set to true if no image tag, or "latest" image tag is set. Cannot be used with
96-
any other options.
97-
98-
- `match-regex.version-checker.io/my-container: ^v\d+\.\d+\.\d+-debian-`: is
99-
used for only comparing against image tags which match the regex set. For
100-
example, the above annotation will only check against image tags which have
101-
the form of something like `v1.3.4-debian-r30`.
102-
`use-metadata.version-checker.io` is not required when this is set. All
103-
other options, apart from URL overrides, are ignored when this is set.
104-
105-
- `override-url.version-checker.io/my-container: docker.io/bitnami/etcd`: is
106-
used to change the URL for where to lookup where the latest image version
107-
is. In this example, the current version of `my-container` will be compared
108-
against the image versions in the `docker.io/bitnami/etcd` registry.
109-
110-
- `resolve-sha-to-tags.version-checker.io/my-container`: is used to
111-
resolve images specified using sha256 in kubernetes manifests to valid semver
112-
tags. To enable this the annotation value must be set to "true".
113-
11462
## Known configurations
11563

11664
From time to time, version-checker may need some of the above options applied to determine the latest version,
11765
depending on how the maintainers publish their images. We are making a conscious effort to collate some of these configurations.
11866

119-
See [known-configurations.md](known-configurations.md) for more details.
120-
121-
## Metrics
122-
123-
By default, version-checker will expose the version information as Prometheus
124-
metrics on `0.0.0.0:8080/metrics`.
67+
See [known-configurations.md](../known-configurations.md) for more details.

‎docs/installation.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Installation
2+
3+
`version-checker` can be installed using either static manifests or Helm.
4+
5+
---
6+
7+
## Install Using Static Manifests
8+
9+
To install using static manifests, run:
10+
11+
```sh
12+
kubectl apply -k ./deploy/yaml
13+
```
14+
15+
## Install Using Helm
16+
To install using Helm, add the Jetstack Helm repository and install the chart:
17+
18+
```sh
19+
helm repo add jetstack https://charts.jetstack.io
20+
"jetstack" has been added to your repositories
21+
22+
helm install version-checker jetstack/version-checker
23+
```
24+
25+
Output:
26+
27+
```sh
28+
NAME: version-checker
29+
LAST DEPLOYED: Wed Jul 12 17:47:41 2023
30+
NAMESPACE: default
31+
STATUS: deployed
32+
REVISION: 1
33+
TEST SUITE: None
34+
```
35+
36+
### Prometheus Operator Integration
37+
38+
The Helm chart supports creating a [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator) `ServiceMonitor` to expose version-checker's metrics.
39+
40+
## Options
41+
42+
By default, version-checker will only test containers where the pod has the annotation
43+
`enable.version-checker.io/*my-container*`, where `*my-container*` is the `name`
44+
of the container in the pod.
45+
46+
However, by passing the following flag,`-a, --test-all-containers` version-checker will test all containers within the cluster.
47+
48+
### Supported Annotations
49+
50+
`version-checker` supports the following annotations to enrich version checking on image tags:
51+
52+
- `pin-major.version-checker.io/my-container: 4`: will pin the major version to
53+
check to 4 (`v4.0.0`).
54+
55+
- `pin-minor.version-checker.io/my-container: 3`: will pin the minor version to
56+
check to 3 (`v0.3.0`).
57+
58+
- `pin-patch.version-checker.io/my-container: 23`: will pin the patch version to
59+
check to 23 (`v0.0.23`).
60+
61+
- `use-metadata.version-checker.io/my-container: "true"`: will allow to search
62+
for image tags which contain information after the first part of the semver
63+
string. For example, this can be pre-releases or build metadata
64+
(`v1.2.4-alpha.0`, `v1.2.3-debian-r3`).
65+
66+
- `use-sha.version-checker.io/my-container: "true"`: will check against the latest
67+
SHA tag available. Essentially, the latest image by date. This is silently
68+
set to true if no image tag, or "latest" image tag is set. Cannot be used with
69+
any other options.
70+
71+
- `match-regex.version-checker.io/my-container: ^v\d+\.\d+\.\d+-debian-`: is
72+
used for only comparing against image tags which match the regex set. For
73+
example, the above annotation will only check against image tags which have
74+
the form of something like `v1.3.4-debian-r30`.
75+
`use-metadata.version-checker.io` is not required when this is set. All
76+
other options, apart from URL overrides, are ignored when this is set.
77+
78+
- `override-url.version-checker.io/my-container: docker.io/bitnami/etcd`: is
79+
used to change the URL for where to lookup where the latest image version
80+
is. In this example, the current version of `my-container` will be compared
81+
against the image versions in the `docker.io/bitnami/etcd` registry.
82+
83+
- `resolve-sha-to-tags.version-checker.io/my-container`: is used to
84+
resolve images specified using sha256 in kubernetes manifests to valid semver
85+
tags. To enable this the annotation value must be set to "true".

‎docs/metrics.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Metrics
2+
3+
By default, version-checker exposes the following Prometheus metrics on `0.0.0.0:8080/metrics`:
4+
5+
- `version_checker_is_latest_version`: Indicates whether the container in use is using the latest upstream registry version.
6+
- `version_checker_last_checked`: Timestamp when the image was last checked.
7+
- `version_checker_image_lookup_duration`: Duration of the image version check.
8+
- `version_checker_image_failures_total`: Total of errors encountered during image version checks.
9+
10+
---
11+
12+
## Example Prometheus Query
13+
14+
```sh
15+
QUERY="version_checker_is_latest_version"
16+
curl -s --get --data-urlencode query=$QUERY <PROMETHEUS_URL>
17+
```

0 commit comments

Comments
 (0)