Track Kubernetes Channels for latest versions (#351)

Co-authored-by: Maria Reynoso <[email protected]>
Co-authored-by: maria-reynoso <[email protected]>
Co-authored-by: Maria Reynoso <[email protected]>

Author: davidcollom

README.md

@@ -6,20 +6,29 @@
 ![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/jetstack/version-checker)
 
 version-checker is a Kubernetes utility for observing the current versions of
-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.
+images running in the cluster, as well as the latest available upstream. Additionally,
+it monitors the Kubernetes cluster version against the latest available releases
+using official Kubernetes release channels. These checks get exposed as Prometheus
+metrics to be viewed on a dashboard, or _soft_ alert cluster operators.
+
+## Features
+
+- **Container Image Version Checking**: Monitor and compare container image versions running in the cluster against their latest upstream versions
+- **Kubernetes Version Monitoring**: Track your cluster's Kubernetes version against the latest available releases from official Kubernetes channels
+- **Prometheus Metrics Integration**: Export all version information as Prometheus metrics for monitoring and alerting
+- **Flexible Channel Selection**: Configure which Kubernetes release channel to track (stable, latest, etc.)
 
 ---
 
 ## 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.
+- **Improved Security**: Ensures images and Kubernetes clusters are up-to-date, reducing the risk of using vulnerable or compromised versions.
+- **Enhanced Visibility**: Provides a clear overview of all running container versions and cluster versions across clusters.
+- **Operational Efficiency**: Automates image and Kubernetes version tracking and reduces manual intervention in version management.
+- **Compliance and Policy Enforcement**: Helps maintain version consistency and adherence to organizational policies for both applications and infrastructure.
 - **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.
+- **Proactive Cluster Management**: Stay informed about Kubernetes security updates and new features through automated version monitoring.
 
 ---
 
@@ -45,6 +54,7 @@ These registries support authentication.
 
 - [Installation Guide](docs/installation.md)
 - [Metrics](docs/metrics.md)
+- [New Features](docs/new_features.md)
 
 ---
 

cmd/app/app.go

@@ -110,19 +110,36 @@ func NewCommand(ctx context.Context) *cobra.Command {
 				return fmt.Errorf("failed to setup image registry clients: %s", err)
 			}
 
-			c := controller.NewPodReconciler(opts.CacheTimeout,
+			_ = client
+
+			podController := controller.NewPodReconciler(opts.CacheTimeout,
 				metricsServer,
 				client,
 				mgr.GetClient(),
 				log,
 				opts.RequeueDuration,
 				opts.DefaultTestAll,
 			)
-
-			if err := c.SetupWithManager(mgr); err != nil {
+			if err := podController.SetupWithManager(mgr); err != nil {
 				return err
 			}
 
+			kubeController := controller.NewKubeReconciler(
+				log,
+				mgr.GetConfig(),
+				metricsServer,
+				opts.KubeInterval,
+				opts.KubeChannel,
+			)
+
+			// Only add to manager if controller was created (channel was specified)
+			if kubeController != nil {
+				if err := mgr.Add(kubeController); err != nil {
+					return err
+				}
+				log.WithField("channel", opts.KubeChannel).Info("Kubernetes version checking enabled")
+			}
+
 			// Start the manager and all controllers
 			log.Info("Starting controller manager")
 			if err := mgr.Start(ctx); err != nil {

cmd/app/options.go

@@ -75,6 +75,10 @@ type Options struct {
 	CacheSyncPeriod         time.Duration
 	RequeueDuration         time.Duration
 
+	KubeChannel  string
+	KubeInterval time.Duration
+
+	// kubeConfigFlags holds the flags for the kubernetes client
 	kubeConfigFlags *genericclioptions.ConfigFlags
 
 	selfhosted selfhosted.Options
@@ -141,7 +145,15 @@ func (o *Options) addAppFlags(fs *pflag.FlagSet) {
 
 	fs.DurationVarP(&o.CacheSyncPeriod,
 		"cache-sync-period", "", 5*time.Hour,
-		"The time in which all resources should be updated.")
+		"The duration in which all resources should be updated.")
+
+	fs.DurationVarP(&o.KubeInterval,
+		"kube-interval", "", o.CacheSyncPeriod,
+		"The time in which kubernetes channels updates are checked.")
+
+	fs.StringVarP(&o.KubeChannel,
+		"kube-channel", "", "stable",
+		"The Kubernetes channel to check against for cluster updates.")
 
 	fs.DurationVarP(&o.GracefulShutdownTimeout,
 		"graceful-shutdown-timeout", "", 10*time.Second,

docs/metrics.md

@@ -2,16 +2,32 @@
 
 By default, version-checker exposes the following Prometheus metrics on `0.0.0.0:8080/metrics`:
 
+## Container Image 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.
 
+## Kubernetes Version Metrics
+
+- `version_checker_is_latest_kube_version`: Indicates whether the cluster is running the latest version from the configured Kubernetes release channel.
+  - Labels: `current_version`, `latest_version`, `channel`
+  - Value `1`: Cluster is up-to-date
+  - Value `0`: Update available
+
 ---
 
-## Example Prometheus Query
+## Example Prometheus Queries
 
+### Check container image versions
 ```sh
 QUERY="version_checker_is_latest_version"
 curl -s --get --data-urlencode query=$QUERY <PROMETHEUS_URL>
-```
+```
+
+### Check Kubernetes cluster version
+```sh
+QUERY="version_checker_is_latest_kube_version"
+curl -s --get --data-urlencode query=$QUERY <PROMETHEUS_URL>
+```

docs/new_features.md

@@ -0,0 +1,62 @@
+# Kubernetes Version Monitoring
+
+version-checker now includes built-in Kubernetes cluster version monitoring capabilities. This feature automatically compares your cluster's current Kubernetes version against the latest available versions from official Kubernetes release channels.
+
+### How It Works
+
+The Kubernetes version checker:
+- Fetches the current cluster version using the Kubernetes Discovery API
+- Compares it against the latest version from the configured Kubernetes release channel (using official `https://dl.k8s.io/release/` endpoints)
+- Exposes the comparison as Prometheus metrics for monitoring and alerting
+- Strips metadata from versions for accurate semantic version comparison (e.g., `v1.28.2-gke.1` becomes `v1.28.2`)
+
+### Configuration
+
+You can configure the Kubernetes version checking behavior using the following CLI flags:
+
+- `--kube-channel`: Specifies which Kubernetes release channel to check against (default: `"stable"`)
+  - Examples: `stable`, `latest`, `stable-1.28`, `latest-1.29`
+- `--kube-interval`: How often to check for Kubernetes version updates (default: same as `--cache-sync-period`, 5 hours)
+
+### Metrics
+
+The Kubernetes version monitoring exposes the following Prometheus metric:
+
+```
+version_checker_is_latest_kube_version{current_version="1.28.2", latest_version="1.29.1", channel="stable"} 0
+```
+
+- Value `1`: Cluster is running the latest version from the specified channel
+- Value `0`: Cluster is not running the latest version (update available)
+
+### Supported Channels
+
+version-checker uses official Kubernetes release channels:
+
+- `stable` - Latest stable Kubernetes release (recommended)
+- `latest` - Latest Kubernetes release (including pre-releases)
+- `latest-1.28` - Latest patch for Kubernetes 1.28.x
+- `latest-1.27` - Latest patch for Kubernetes 1.27.x
+
+### Examples
+
+```bash
+# Check against latest stable Kubernetes
+version-checker --kube-version-channel=stable
+
+# Check against latest Kubernetes (including alpha/beta)
+version-checker --kube-version-channel=latest
+
+# Check against latest 1.28.x patch
+version-checker --kube-version-channel=latest-1.28
+
+# Monitor against a specific version channel with custom interval
+./version-checker --kube-channel=stable-1.28 --kube-interval=1h
+```
+
+### Managed Kubernetes Support
+
+Works with all managed Kubernetes services:
+- **Amazon EKS**: Compares `v1.28.2-eks-abc123` against upstream `v1.28.2`
+- **Google GKE**: Compares `v1.28.2-gke.1034000` against upstream `v1.28.2`  
+- **Azure AKS**: Compares `v1.28.2-aks-xyz789` against upstream `v1.28.2`

pkg/client/docker/docker.go

@@ -17,6 +17,7 @@ import (
 	retryablehttp "github.com/hashicorp/go-retryablehttp"
 	"github.com/jetstack/version-checker/pkg/api"
 	"github.com/jetstack/version-checker/pkg/client/util"
+	leveledlogger "github.com/jetstack/version-checker/pkg/leveledlogrus"
 )
 
 // Ensure that we are an ImageClient
@@ -69,7 +70,7 @@ func New(opts Options, log *logrus.Entry) (*Client, error) {
 	retryclient.RetryWaitMin = 1 * time.Second
 	// This custom backoff will fail requests that have a max wait of the RetryWaitMax
 	retryclient.Backoff = util.HTTPBackOff
-	retryclient.Logger = log.WithField("client", "docker")
+	retryclient.Logger = leveledlogger.Logger{Entry: log.WithField("client", "docker")}
 	client := retryclient.StandardClient()
 
 	// Setup Auth if username and password used.

pkg/client/fallback/fallback.go

@@ -56,9 +56,9 @@ func (c *Client) Tags(ctx context.Context, host, repo, image string) (tags []api
 
 		remaining := len(c.clients) - i - 1
 		if remaining == 0 {
-			c.log.Debugf("failed to lookup via %q, Giving up, no more clients", client.Name())
+			c.log.Infof("failed to lookup via %q, Giving up, no more clients", client.Name())
 		} else {
-			c.log.Debugf("failed to lookup via %q, continuing to search with %v clients remaining", client.Name(), remaining)
+			c.log.Infof("failed to lookup via %q, continuing to search with %v clients remaining", client.Name(), remaining)
 		}
 	}
 

pkg/client/quay/quay.go

@@ -12,6 +12,7 @@ import (
 
 	"github.com/jetstack/version-checker/pkg/api"
 	"github.com/jetstack/version-checker/pkg/client/util"
+	leveledlogger "github.com/jetstack/version-checker/pkg/leveledlogrus"
 )
 
 const (
@@ -39,6 +40,7 @@ func New(opts Options, log *logrus.Entry) *Client {
 	if opts.Transporter != nil {
 		client.HTTPClient.Transport = opts.Transporter
 	}
+	client.Logger = leveledlogger.Logger{Entry: log.WithField("client", "quay")}
 
 	return &Client{
 		Options: opts,