KubernetesClient.Fluent
1.0.5
dotnet add package KubernetesClient.Fluent --version 1.0.5
NuGet\Install-Package KubernetesClient.Fluent -Version 1.0.5
<PackageReference Include="KubernetesClient.Fluent" Version="1.0.5" />
paket add KubernetesClient.Fluent --version 1.0.5
#r "nuget: KubernetesClient.Fluent, 1.0.5"
// Install KubernetesClient.Fluent as a Cake Addin #addin nuget:?package=KubernetesClient.Fluent&version=1.0.5 // Install KubernetesClient.Fluent as a Cake Tool #tool nuget:?package=KubernetesClient.Fluent&version=1.0.5
KubernetesClient.Fluent
This library extends the C# Kubernetes client with a fluent interface, convenient model extensions, improved watches, and improved exec support. It is available as Nuget package KubernetesClient.Fluent.
Fluent Interface
The library adds a fluent API that is concise, flexible, and works well with custom resources and custom actions. The basic flow is that
from the Kubernetes client, you can create a request, and given a request you can modify or execute it. If c
is a Kubernetes client,
then these expressions create different types of requests:
c.Request<V1Pod>() // list all pods in all namespaces
c.Request<V1Pod>("ns") // list all pods in a namespace
c.Request<V1Pod>("ns", "name") // get a single pod
c.Request<V1Pod>("ns", "name").Delete() // delete a pod by name
c.Request(pod).Post() // create a pod
c.Request(pod, setBody: false).Delete() // delete a pod if you have the object already
c.Request<V1Pod>("ns").LabelSelector("X").FieldSelector("Y") // list pods with label and field selectors
c.Request(pod).Status().Put() // update a pod's status
c.Request(pod).Subresource("log") // read a pod's logs
c.Request(pod).Put().DryRun(true) // simulate replacing a resource
c.Request().RawUri("/apis/...") // specify a raw URL
etc...
It works with both built-in and custom resource types. For advanced operations, you can:
- Use custom resource types and HTTP verbs
- Modify request and content headers
- Modify the query string
- Access subresources
- Stream the request or upgrade it for web socket or SPDY connections
- Stream the response and access the raw network connection
- Specify group, version, and kind manually, or specify the entire raw URL
- Configure watches
To execute any request so constructed, it's simply: req.ExecuteAsync()
. This returns a response object that gives you full access to the
status code, response headers, and response stream. (It does not throw an exception if an HTTP error response is returned, unless you want
it to.) It also has convenience methods for reading and deserializing the response in various ways.
A request can be executed multiple times, including in parallel. (I.e. a request is not modified or consumed by executing it.) You can clone a request if you want to write a method that takes a request and executes a modified version of it without mutating the original.
If you want to execute a request, check the status (including throwing exceptions for errors), and deserialize the body all in one go,
it's simply req.ExecuteAsync<T>()
.
To assist with modifying resources, it supports an atomic get-modify-update operation via req.ReplaceAsync<T>(...)
.
Convenient Model Extensions
The library adds many useful model extension methods that make the Kubernetes client smoother and more concise to use. (Most of these were merged into the official client, but I'll leave these examples here.)
Metadata is inlined, so instead of o.Metadata.X, you can use o.X(). Examples:
o.Metadata?.Name -> o.Name() o.Metadata?.NamespaceProperty -> o.Namespace() ... etc ...
Managing labels and annotations. Examples for labels:
string value = null; if(o.Metadata.Labels != null) o.Metadata.Labels.TryGetValue(key, out value)
becomes
o.GetLabel(key)
Similarly,
if(o.Metadata == null) o.Metadata = new V1ObjectMeta(); if(o.Metadata.Labels == null) o.Metadata.Labels = new Dictionary<string,string>(); o.Metadata.Labels[key] = value;
becomes
o.SetLabel(key, value)
Managing owner and object references
- o.AddOwnerReference(ownerRef) // adds an owner reference
- o.CreateObjectReference() // creates an object reference to o
- o.CreateOwnerReference(...) // create an owner reference to o
- o.FindOwnerReference(owner) // finds and returns the reference to 'owner', if any
- o.GetController() // gets the reference to the owner that controls the resource
- ownerRef.Matches(o) // does ownerRef refer to o?
- objRef.Matches(o) // does objRef refer to o?
- ...
And some other small things.
Improved Watches
The library adds improved watch support. Aside from various internal problems, the KubernetesClient watch offers only the lowest level support -- reporting a stream of watch events from a single watch request. In practice, watches time out and need to be reopened, and when you reopen them you need to resume where you left off, which requires tracking the latest version, but if you're watching a list of items as opposed to a single item you can't easily do that because the correct version to resume at is not marked in the watch stream itself and must be retrieved from a list request. Support for resuming and for watching multiple items must be built on top, but the KubernetesClient Watcher object doesn't have a good interface for building on top of.
To address these problems, this library provides two watch interfaces.
WatchReader<T> -- This class provides the events from a single watch request. It uses a pull-based interface.
// x can be a Stream, HttpResponseMessage, or KubernetesResponse using(var wr = new WatchReader<V1Pod>(x)) { WatchEvent<V1Pod> e; while((e = await wr.ReadAsync(cancelToken)) != null) /* handle event */ }
Watch<T> -- This class implements a high-level watch that tracks versions, resumes after disconnection, supports watch bookmarks, and can watch both lists and single items. It uses an event-based approach like the KubernetesClient Watcher<T>, but has more events:
- Closed
- EventReceived - Only raised for Added, Modified, and Removed events
- Error
- InitialListSent - Raised after the initial list of items was sent from opening the watch. This can be used to let a watch-based cache know when it has reached a synchronized state, for example.
- Opened
- Reset - Raised when the watch is opened without successfully resuming, i.e. when events may have been lost. This can be used to clear caches based on the watch, for example.
// request is a KubernetesRequest var w = new Watch<V1Pod>(request); // or use request.ToWatch<T>() w.EventReceived += ...; w.Run(); ... w.Dispose(); // or, give it a cancellation token and cancel it // if you need to know exactly when it stops you can await the task returned from Run()
Improved Exec Support
The library adds improved exec support. The KubernetesClient exec support uses web sockets, which
has a flawed protocol leading to some commands running forever.
You can simply use request.ExecuteCommandAsync
to execute a command on a resource -- usually but not necessarily a pod.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 is compatible. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 is compatible. |
.NET Framework | net452 is compatible. net46 was computed. net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETCoreApp 2.1
- KubernetesClient (>= 2.0.26)
- SPDY.net (>= 1.0.3)
-
.NETFramework 4.5.2
- KubernetesClient (>= 2.0.26)
- SPDY.net (>= 1.0.3)
-
.NETStandard 2.0
- KubernetesClient (>= 2.0.26)
- SPDY.net (>= 1.0.3)
-
.NETStandard 2.1
- KubernetesClient (>= 2.0.26)
- SPDY.net (>= 1.0.3)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.