Managing workloads

The k8s module provides high-level APIs to deploy and manage containerized workloads in a cluster. By utilizing these APIs, you can automate deployment pipelines, perform scaling actions, configure autoscalers, and monitor resource consumption.

Deploying Workloads

The client.deploy() function provides a unified interface to deploy containerized workloads. In a single API call, it creates a Kubernetes Deployment and an optional ClusterIP Service, matching standard application patterns.

def main():
    # Configure the client for the target namespace
    client = k8s.config(namespace="staging")

    # Deploy an application and expose it on port 80
    result = client.deploy(
        name = "alice-web",
        image = "nginx:1.27",
        replicas = 3,
        port = 80,
        labels = {"app": "alice-web", "team": "platform"},
    )

    # The function returns an AttrDict with the names of the created resources
    print("Created Deployment:", result.deployment)
    print("Created Service:", result.service)

Scaling Workloads

To adjust the capacity of a workload, use the client.scale() function. This directly updates the replica count of the target controller (such as a Deployment or StatefulSet).

def scale_app():
    client = k8s.config(namespace="staging")

    # Scale the deployment to 5 replicas
    client.scale(
        kind = "deployment",
        name = "alice-web",
        replicas = 5,
    )
    print("Workload scaled to 5 replicas.")

Autoscaling Workloads

For dynamic scaling based on resource demand, use client.autoscale(). This configures a HorizontalPodAutoscaler (HPA) targeting the deployment.

def configure_autoscaling():
    client = k8s.config(namespace="staging")

    # Attach an HPA targeting 70% CPU utilization
    client.autoscale(
        kind = "deployment",
        name = "alice-web",
        min = 2,
        max = 10,
        cpu_percent = 70,
    )
    print("Horizontal Pod Autoscaler configured.")

In-Place Pod Vertical Scaling

To modify CPU or memory allocations on running containers without restarting pods or triggering rolling updates, use client.resize(). This targets the Pod resize subresource (Kubernetes 1.27+, GA 1.35).

def resize_container():
    client = k8s.config(namespace="staging")

    # Resize CPU and memory allocations for a running container
    result = client.resize(
        name = "alice-web-76b9f47b-x8q2z",
        container = "alice-web",
        cpu = "2",
        memory = "4Gi",
    )
    print("Resize request submitted for pod:", result.metadata.name)

Zero-Shell Diagnostics with Ephemeral Containers

For secure or distroless container images that lack shells and debugging utilities, use client.debug(). This injects an ephemeral container via the /ephemeralcontainers API subresource to attach diagnostic tools and inspect the running environment.

def debug_container():
    client = k8s.config(namespace="staging")

    # Run network diagnostics against a target container using netshoot
    result = client.debug(
        name = "alice-web-76b9f47b-x8q2z",
        image = "nicolaka/netshoot",
        target_container = "alice-web",
        command = ["tcpdump", "-i", "any", "-c", "5", "port", "80"],
    )
    print("Debug output (exit code %d):" % result.code)
    print(result.stdout)

Inspecting Workload Metrics

To monitor the performance of your running workloads, use the client.top_pods() function. It retrieves real-time CPU and memory utilization details from the cluster's Metric Server.

def check_resource_metrics():
    client = k8s.config(namespace="staging")

    # Query pod resource metrics sorted by CPU usage
    metrics = client.top_pods(sort_by="cpu", timeout="10s")

    print("Active Resource Consumption:")
    for pod in metrics:
        if "alice-web" in pod.name:
            print(
                "Pod Name:", pod.name,
                "CPU request:", pod.cpu_request,
                "Status:", pod.status,
            )