Swiftkube Client

The client supports CRDs natively. You can manage custom resources in two ways:

1. Unstructured: Use UnstructuredResource with a specific GroupVersionResource.
2. Typed (Marker Protocols): Define custom Swift structs that implement specific marker protocols to enable full DSL support (get, list, watch, create, etc.).

Supported Marker Protocols

• KubernetesAPIResource: Marks the object as a Kubernetes resource.
• NamespacedResource / ClusterScopedResource: Defines scope.
• ReadableResource: Enables get, list, and watch.
• CreatableResource: Enables create.
• ReplaceableResource: Enables update.
• DeletableResource: Enables delete.
• MetadataHavingResource: Indicates presence of metadata: ObjectMeta?.
• StatusHavingResource: Indicates presence of a state field.

// Example of a typed Custom Resource
struct CronTab: KubernetesAPIResource, NamespacedResource, MetadataHavingResource, 
        ReadableResource, CreatableResource, ListableResource {
  typealias List = CronTabList
  var apiVersion = "example.com/v1"
  var kind = "CronTab"
  var metadata: meta.v1.ObjectMeta?
  var spec: CronTabSpec
}

// Using the typed client
let gvr = GroupVersionResource(group: "example.com", version: "v1", resource: "crontabs")
let cronTabClient = client.for(CronTab.self, gvr: gvr)

let newCron = try await cronTabClient.create(in: .default, myCronTabInstance)

Watching resources

watch opens a persistent connection to the API server. It returns a SwiftkubeClientTask which must be explicitly started via .start() to receive an AsyncThrowingStream of events.

• Reconnection: The client automatically reconnects on non-recoverable errors using a RetryStrategy. The default is 10 attempts with a 5s fixed delay (initial 1s, 0.2s jitter).
• Cancellation: You must call task.cancel() when the watch is no longer needed.

Following logs

follow emits log lines instead of events.

Warning: Unlike watch, the client does not reconnect on errors in follow mode.

// Watch
let task: SwiftkubeClientTask = try await client.pods.watch(in: .allNamespaces)
let stream = await task.start()
for try await event in stream { print(event) }
task.cancel()

// Follow logs
let logTask = try await client.pods.follow(in: .default, name: "nginx", container: "app")
for try await line in await logTask.start() { print(line) }
logTask.cancel()

The client automatically resolves kube config from the KUBECONFIG environment variable, the $HOME/.kube/config directory, or via a ServiceAccount token if running inside Kubernetes.

You can also load configuration manually using KubeConfig methods and then initialize a KubernetesClientConfig.

// Manual KubeConfig loading
let kubeConfig = try KubeConfig.fromDefaultLocalConfig()
let config = KubernetesClientConfig.from(
  kubeConfig: kubeConfig,
  contextName: "some-context" // defaults to "current-context"
)

// Fully manual configuration
let caCert = try NIOSSLCertificate.fromPEMFile(caFile)
let authentication = KubernetesClientAuthentication.basicAuth(
  username: "admin", 
  password: "admin"
)

let config = KubernetesClientConfig(
   masterURL: "https://kubernetesmaster",
   namespace: "default",
   authentication: authentication,
   trustRoots: NIOSSLTrustRoots.certificates(caCert),
   insecureSkipTLSVerify: false,
   timeout: HTTPClient.Configuration.Timeout.init(connect: .seconds(1), read: .seconds(10)),
   redirectConfiguration: HTTPClient.Configuration.RedirectConfiguration.follow(max: 5, allowCycles: false)
)

let client = KubernetesClient(config: config)

The client provides a type-safe DSL for interacting with Kubernetes resources using Swift concurrency.

List resources

Use .list() with optional ListOptions to filter by label selectors, field selectors, or limit results.

Get a resource

Use .get() to retrieve a specific resource by name. You can provide ReadOptions like .pretty() or .exact().

Delete a resource

Use .delete() to remove a resource. You can pass meta.v1.DeleteOptions to control propagation and grace periods.

Create and Update

Resources can be created by passing an instance or using convenience builders provided by SwiftkubeModel.

// List
let deployments = try await client.appsV1.deployments.list(in: .allNamespaces, options: [
  .labelSelector(.eq(["app": "nginx"])),
  .limit(20)
])

// Get
let deployment = try await client.appsV1.deployments.get(in: .namespace("ns"), name: "nginx")

// Delete
try await client.appsV1.deployments.delete(in: .namespace("ns"), name: "nginx")

// Create (using builder)
let pod = try await client.pods.create(inNamespace: .default) { 
   sk.pod { 
     $0.metadata = sk.metadata(name: "nginx") 
     $0.spec = sk.podSpec { $0.containers = [sk.container(name: "nginx") { $0.image = "nginx" }] } 
   } 
}