Archetypical.Software.K8s.Utilities 2.0.0

Archetypical.Software.K8s.Utilities

Utilities extending the KubeOps and IKubernetes Client. This package provides:

• Safe, helper-oriented CRUD patterns for IKubernetesClient
• Pod exec helpers with timeout handling
• Lightweight port-forwarding utilities (raw socket + HttpClient)

Compatibility

This package multi-targets .NET 8, 9, and 10. Package dependencies are pinned per target framework to prevent cross-framework version mismatches.

Installation

dotnet add package Archetypical.Software.K8s.Utilities

Package contents

Extension methods for IKubernetesClient

DeleteProtected

Deletes a resource without throwing on 404. Returns a V1Status with the HTTP status code and message.

await client.DeleteProtected<MyCustomResource>("resource-name", "default");

UpdateStatusProtected

Updates the status subresource and optionally handles resource version conflicts by reloading the latest metadata.

await client.UpdateStatusProtected(resource, force: true);

Upsert

Creates or updates a resource depending on existence.

var saved = await client.Upsert(resource);

Pod execution

PodExecutor provides a serialized execution helper for NamespacedPodExecAsync with a configurable timeout.

var executor = new PodExecutor(configuration);
var output = await executor.ExecOnPod(client, pod, container, "ls", "-la");

Configuration key:

• POD_EXECUTION_TIMEOUT_OVERRIDE (seconds, default: 30)

Port forwarding (raw socket)

K8SPortForward.ConnectAsync creates a local TCP listener that forwards to a pod port. This is intentionally single-threaded and intended for lightweight tooling.

using var forward = await K8SPortForward.ConnectAsync(k8sClient, pod, portOnPod: 8080, portOnMachine: 18080);

Port forwarding for HttpClient

K8SPortForwardedHttpClient.Create builds a wrapper around an HttpClient that forwards traffic to a pod using the port-forwarding websocket. The returned object implements IDisposable and should be disposed when no longer needed.

using var httpClient = await K8SPortForwardedHttpClient.Create(k8sClient, pod, new[] { 8080 });
var response = await httpClient.GetAsync("http://localhost/");

Testing

This repository includes an xUnit test project targeting .NET 8.

dotnet test

Build and pack

The package is configured to generate a NuGet package on build.

dotnet build -c Release

Troubleshooting

• If port-forwarding appears to hang, ensure the pod and container are running and that network policies allow port-forwarding.
• If UpdateStatusProtected conflicts, set force: true to reload the latest resource version before retrying.

License

GPL-3.0-only. See LICENSE.