doriordan/skuber

Skuber is a Scala library that provides asynchronous, non-blocking clients for interacting with the Kubernetes API. It supports multiple reactive programming models, including Apache Pekko, Akka, Cats Effect, and ZIO, enabling features like resource management, streaming logs, and command execution. The system handles core Kubernetes object serialization, authentication, and configuration parsing to facilitate programmatic cluster operations.

11 changes.

The project migrated its core infrastructure to Scala 3 and replaced the Akka HTTP client with Apache Pekko, necessitating the removal of legacy V1 API model definitions. This foundational update was accompanied by a comprehensive overhaul of the example suite, which was refactored to utilize the new Pekko actors and streams for reactive Kubernetes operations.

15 changes.

This period focused on expanding the Skuber library's core Kubernetes model definitions to cover a wide range of resources and API features, including patching and security helpers. Concurrently, the project developed and refined a new non-blocking client implementation based on Apache Pekko, replacing older synchronous approaches with stream-based operations for logging, execution, and resource watching.

8 changes.

The project expanded its Kubernetes client capabilities by introducing native implementations for Cats Effect and ZIO, alongside an existing Akka/Pekko foundation. This period focused on building asynchronous, streaming-aware clients for these functional programming ecosystems, supported by comprehensive integration test suites and internal infrastructure for HTTP handling and authentication.

The Pekko client now supports executing commands inside Kubernetes pods via a new \PodExecImpl\ component. This implementation establishes WebSocket connections to the Kubernetes API to stream stdin, stdout, and stderr, handling SSL/TLS configuration and authentication headers to allow interactive command execution within containers.

pekko/src/main/scala/skuber/pekkoclient/exec · high confidence

A new example file (ExecExamples.scala) demonstrates how to execute commands inside a Kubernetes pod using the skuber client. The example creates a 'sleep' pod and simulates 'kubectl exec' behavior by streaming stdout to the console and sending stdin input via Pekko streams, including a TTY-based interactive shell session.

examples/src/main/scala/skuber/examples/exec · high confidence

The skuber library now includes an example demonstrating how to stream pod logs using Pekko Streams. This new example, located in examples/src/main/scala/skuber/examples/podlogs, shows how to initialize a Kubernetes client, create a multi-container pod, and retrieve logs for specific containers using the getPodLogSource method. The example utilizes Pekko's streaming capabilities to process log lines as they arrive, providing a practical reference for integrating real-time log streaming into applications.

examples/src/main/scala/skuber/examples/podlogs · high confidence

Users can now launch an interactive Ammonite REPL via the new \repl/amm\ script, which automatically initializes a Pekko-based Skuber Kubernetes client. The REPL preloads essential imports and provides a ready-to-use \k8s\ client instance, allowing immediate interaction with Kubernetes resources without manual setup.

repl · high confidence

The new DeploymentExamples.scala file provides a runnable demonstration of managing Kubernetes Deployments, specifically showing how to create a deployment, wait for it to stabilize, perform a rolling update to a new container image version, and finally delete the deployment with foreground propagation.

examples/src/main/scala/skuber/examples/deployment · high confidence

The skuber API module now includes core support for parsing kubeconfig files and applying resource patches. The new Configuration.scala file enables users to load and manage Kubernetes cluster, context, and user settings from standard kubeconfig files, including support for local proxies and various authentication methods like OIDC and GCP. Additionally, patch.scala introduces the ability to perform JSON Patch, JSON Merge Patch, and Strategic Merge Patch operations on Kubernetes resources, allowing for targeted updates to metadata and other fields.

core/src/main/scala/skuber/api · high confidence

A new example script, CreateNginxPod.scala, has been added to the examples directory. This script demonstrates how to initialize a Pekko-based Kubernetes client using Skuber, create an Nginx pod, and verify its status after creation.

examples/src/main/scala · high confidence

A new example file (WatchExamples.scala) demonstrates how to use the Skuber watch functionality with the new Pekko-based Kubernetes client. The example shows how to watch for changes in ReplicationController replica counts and Pod phases, utilizing Pekko Streams to process the watch events. It also illustrates proper resource cleanup by terminating the ActorSystem after a set duration.

examples/src/main/scala/skuber/examples/watch · high confidence

The core library now includes Scala model definitions for the Kubernetes apps/v1 API group, enabling users to interact with DaemonSet, Deployment, ReplicaSet, and StatefulSet resources. These new files provide case classes for the resource specifications and statuses, along with Play JSON formatters for serialization and deserialization, allowing these workload types to be created, updated, and queried via the client.

core/src/main/scala/skuber/model/apps/v1 · high confidence

The examples module now includes dedicated configuration files for logging: an Akka \application.conf\ that sets up SLF4J logging and silences default output, and a \logback.xml\ that configures console output with specific log levels for the Skuber API and Akka subsystems, allowing users to control log verbosity in example runs.

examples/src/main/resources · high confidence

The \PatchExamples.scala\ file was added to demonstrate how to perform JSON merge patches on Kubernetes resources using the Skuber client. The example specifically shows scaling a StatefulSet by updating its replica count via the \k8s.patch\ method, including the necessary JSON format definitions and patch object structure.

examples/src/main/scala/skuber/examples/patch · high confidence

This change introduces the foundational data models and JSON formatters for the Skuber client library, enabling users to interact with Kubernetes resources. It adds case classes and resource definitions for core objects including Pods, Nodes, Services, Namespaces, ConfigMaps, Events, and Endpoints, as well as extended resources like Ingress, PersistentVolumes, PersistentVolumeClaims, Jobs, and CronJobs. The update also includes JSON serialization logic for RBAC entities (Roles, ClusterRoles, Bindings) and provides a generic framework for Custom Resources. Users can now construct, serialize, and deserialize these standard Kubernetes API objects.

core/src/main/scala/skuber/model · high confidence

This change adds a new client implementation for Skuber that uses Apache Pekko (the successor to Akka) as the underlying HTTP and streaming engine. The diff introduces the core \PekkoKubernetesClient\ trait and its \PekkoKubernetesClientImpl\ class, which handle HTTP requests, authentication (including async auth providers), and watch streams using Pekko HTTP and Streams. It also includes \PlayJsonSupportForPekkoHttp\ to enable JSON marshalling/unmarshalling with Play JSON, and exposes \k8sInit\ factory methods in the \skuber.pekkoclient\ package to allow users to initialize the client with Pekko actors. This provides an alternative to the existing Akka-based client, leveraging Pekko's APIs for non-blocking I/O and reactive streams.

pekko/src/main/scala/skuber/pekkoclient/impl · high confidence

Adds a new \zio\ module providing a ZIO-native Kubernetes client (\ZKubernetesClient\) that wraps the existing skuber core. This client exposes standard resource operations (get, create, update, delete, patch, apply) as ZIO effects and introduces streaming capabilities for watching resources (\watch\), retrieving pod logs (\getPodLogStream\), and executing commands in pods (\exec\) via WebSocket. It includes internal implementations for HTTP backend abstraction, TLS configuration from kubeconfig, and JSON parsing, along with comprehensive tests for exception handling, JSON bridging, watch streams, and client operations.

zio · high confidence

This change adds the \SecurityHelper\ and \TLS\ objects to the core module to handle Kubernetes client certificate loading, private key parsing (supporting PKCS\#1, PKCS\#8, and EC formats), and SSL context establishment, including support for the \insecureSkipTLSVerify\ flag. It also adds a \reference.conf\ file for the Pekko module, defining default configuration values for dispatchers and idle/request timeouts for watch and pod-log operations.

core/src/main/scala/skuber/api/security, pekko/src/main/resources · high confidence

Skuber now provides a new client implementation built on Akka HTTP and Akka Streams, available via the \skuber.akkaclient\ package. This addition introduces \AkkaKubernetesClient\ and \AkkaWatcher\ traits that replace the previous synchronous/blocking I/O with non-blocking, stream-based operations for standard API calls, pod log streaming, and resource watching. The implementation includes specific support for executing commands in pods via WebSocket (\PodExecImpl\), handling asynchronous authentication providers, and configuring connection timeouts through a new \reference.conf\ file. Users can initialize this backend using the existing \k8sInit\ methods by providing an implicit \ActorSystem\.

akka/src/main · high confidence

Skuber now provides a new \CatsKubernetesClient\ in the \skuber.catseffect\ package, offering a fully asynchronous Kubernetes API client built on Cats Effect and fs2. This implementation supports standard resource operations (get, create, update, delete, list), subresources (status, scale), patching, and Server-Side Apply. It also introduces streaming capabilities for watching resource changes, retrieving pod logs, and executing commands in pods via WebSocket. The client is constructed as a \Resource\ and uses http4s for HTTP requests and the JDK HTTP client for WebSocket connections, allowing users to integrate Skuber into Cats Effect-based applications.

cats · high confidence

Added a new example script (NginxIngress.scala) that demonstrates how to create and test an Nginx-based Ingress controller using a ReplicaSet and NodePort services, including a default backend and echoheaders services for validation.

examples/src/main/scala/skuber/examples/ingress · high confidence

Added a new example file (ScaleExamples.scala) that demonstrates how to programmatically scale Kubernetes Deployments and StatefulSets using the extensions API, as well as how to configure a HorizontalPodAutoscaler (HPA) to manage replica counts based on CPU utilization.

examples/src/main/scala/skuber/examples/scale · high confidence

Added two new example programs to demonstrate specific Skuber capabilities: PrintPiJob shows how to create and run a Kubernetes Job that computes pi, while ListExamples demonstrates listing Pod resources within the current namespace, a specific namespace (kube-system), and across all namespaces in the cluster.

examples/src/main/scala/skuber/examples/list · high confidence

Added a new example file demonstrating how to use the Skuber fluent interface to build and manage Kubernetes resources. The example shows creating replication controllers and services for nginx across different environments (dev, test, production) and zones, utilizing labels, selectors, node selectors, and resource limits. It also includes helper methods to retrieve existing resources or initialize new ones, and demonstrates exposing services on node ports.

examples/src/main/scala/skuber/examples/fluent · high confidence

The core Kubernetes V1 API model definitions and associated JSON parsing logic have been removed from the \skuber\ library. This change deletes the \KubernetesJson\ object (which handled RFC3339 date parsing and JSON reads for resources) and removes the source files defining the fundamental resource models, including \Pod\, \Container\, \Volume\, \Namespace\, \ReplicationController\, \Event\, \EnvVar\, and \Security\. Users relying on these classes for constructing or deserializing Kubernetes resources will lose access to these core types.

src/main · high confidence

The examples directory now includes an application.conf file that configures Akka to use SLF4J for logging and enables remote message logging, alongside a logback.xml file that sets up a console appender and configures log levels (INFO for skuber.api, ERROR for akka and root). This change standardizes how logging is handled in the example applications, making it more configurable and consistent as intended by the refactoring.

examples · high confidence

The library has added a new set of internal components in \skuber.internal\ to support the migration to a ZIO-based client. This includes \K8sRequest\ and \K8sResponse\ data structures to represent HTTP interactions, an \AuthInterceptor\ to handle authentication headers (Basic, Bearer, and async token auth), a \UrlBuilder\ to construct Kubernetes API URLs for resources, logs, and exec commands, a \PlayJsonBridge\ for JSON serialization/deserialization, and a \TlsHelper\ for SSL context management. These changes provide the foundational networking and request-handling layer required for the new client implementation.

core/src/main/scala/skuber/internal · high confidence

The library introduces a new watch implementation for the Pekko HTTP client, replacing the previous Akka-based approach. This change adds new components in the \pekko\ module (\BytesToWatchEventSource\, \LongPollingPool\, \PekkoWatcherImpl\, \Watch\, and \WatchSource\) to handle long-polling watch requests, parse streaming JSON events, and manage connection pools with specific settings (single connection, no retries) suitable for watch streams. Users relying on the Pekko backend will now use this new implementation for resource watching capabilities.

pekko/src/main/scala/skuber/pekkoclient/watch · high confidence

This change introduces new core client components in the \skuber.api.client\ package. It adds \Cluster\ and \Context\ case classes to define API server connection details and request contexts, and a \LoggingConfig\ case class that allows users to enable or disable specific log outputs (such as request/response bodies and metadata) via system properties. The \Watcher\ trait is updated to support Kubernetes 1.27+ features, including \sendInitialEvents\ (streaming list) and \allowWatchBookmarks\, while the \package.scala\ file introduces \AsyncAccessTokenAuth\ for asynchronous token reloading and \ApplyOptions\ for Server-Side Apply operations.

core/src/main/scala/skuber/api/client · high confidence

The Guestbook example in the examples module has been rewritten to use an actor-based architecture (Apache Pekko) for orchestrating Kubernetes deployments. The new implementation introduces a set of actors—GuestbookActor, KubernetesProxyActor, ServiceActor, and ScalerActor—to manage the lifecycle of the application's services (Redis master, Redis slave, and frontend). This change enables reactive scaling and deployment validation by using Kubernetes watch APIs to monitor replica status, ensuring that deployment steps only proceed when the required number of pods are running. The example now handles stopping, housekeeping, recreating, and validating services through a structured, asynchronous workflow.

examples/src/main/scala/skuber/examples/guestbook · high confidence

Added Akka and Pekko integration test suites; Added ZIO-based integration tests for Kubernetes client operations; Added test coverage for Kubernetes resource serialization and configuration parsing; Added test fixtures for ReplicationController watch events; Added tests for Pekko-based Kubernetes watch source and connection pooling; Integration tests for Cats Effect client.

The build manifest has been updated to target Scala 3.3.7 (with cross-compilation support for 2.13.18), replacing the previous Scala 2.11 base. The default HTTP client implementation has shifted from Play/Akka to Apache Pekko (version 1.6.0), with the Akka BSL client retained as a separate module. Additionally, core dependencies have been upgraded, including SnakeYAML to 2.6, Logback to 1.5.34, and various test libraries like Mockito and Specs2.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 57.

• Code Health 96
• Architecture 91
• Maturity 54
• Readiness 46
• Security 70

• 300 commits — 264 feature/other, 36 fixes

• (root) — 130 commits
• client/src — 98 commits
• akka/project — 12 commits
• docs/GUIDE.md — 11 commits
• core/src — 9 commits
• akka/src — 7 commits
• integration/src — 7 commits
• .github/workflows — 5 commits
• examples/src — 4 commits
• project/plugins.sbt — 4 commits
• docs/Configuration.md — 3 commits
• (repo) — 2 commits
• cats-it/src — 1 commit
• cats/src — 1 commit
• docs/GUIDE_CATS.md — 1 commit
• docs/MIGRATION2to3.md — 1 commit
• docs/MIGRATION_1-to-2.md — 1 commit
• pekko/src — 1 commit
• zio-it/src — 1 commit
• zio/src — 1 commit

• fix: Fix issue #159 (#161)
• fix: Add startupProbe support (fixes #304) (#310)
• fix: Bugfix: conditions of job's status absent (#250)
• fix: Fix #202 (#203)
• fix: Fix CatsExecSpec integration test failures on CI (#505)
• fix: Fix ClassCastException when parsing GCP auth provider expiry dates (#268)
• fix: Fix akka version compatibility issue in connection settings (#165)
• fix: Fix auth header (#219)
• fix: Fix custom resource spec integration tests
• fix: Fix issue #132 (#136)
• fix: Fix issue #150 (watchAll sinceResourceVersion bug) (#153)
• fix: Fix issue #303 and move ingress test to networking package (#309)
• fix: Fix tests, move client to core directory
• fix: Fix unmarshalling errors when no apiVersion or kind in object (#152)
• fix: Fix various compile warnings
• fix: Fixed error on missing config references (#425)
• fix: Fixed optional fields in Endpoints (#177)
• fix: Fixes #271 (#272)
• fix: Fixes for pod toleration, scale subresouce and minor typo issues (#157)
• fix: Fixes issue #225 (getPodLogSource returning 400 when >1 containers) (#226)
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

doriordan/skuber was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.