¶

A simple, extensible Python client library for Kubernetes that feels familiar for folks who already know how to use kubectl.

Highlights¶

API inspired by kubectl for a shallow learning curve.
Sensible defaults to reduce boiler plate.
No swagger generated code, human readable code only.
Has both a standard and an async API that can be used with asyncio and trio.
Client caching to reduce passing API objects around.
Batteries included by providing useful utilities and methods inspired by kubectl.

Quickstart¶

Installation¶

$ pip install kr8s

Examples¶

List Nodes¶

Print out all of the node names in the cluster.

Sync

import kr8s

for node in kr8s.get("nodes"):
    print(node.name)

Async

import kr8s.asyncio

for node in await kr8s.asyncio.get("nodes"):
    print(node.name)

Create a Pod¶

Create a new Pod.

Sync

from kr8s.objects import Pod

pod = Pod({
        "apiVersion": "v1",
        "kind": "Pod",
        "metadata": {
            "name": "my-pod",
        },
        "spec": {
            "containers": [{"name": "pause", "image": "gcr.io/google_containers/pause",}]
        },
    })

pod.create()

Async

from kr8s.asyncio.objects import Pod

pod = await Pod({
        "apiVersion": "v1",
        "kind": "Pod",
        "metadata": {
            "name": "my-pod",
        },
        "spec": {
            "containers": [{"name": "pause", "image": "gcr.io/google_containers/pause",}]
        },
    })

await pod.create()

Scale a Deployment¶

Scale the Deployment metrics-server in the Namespace kube-system to 1 replica.

Sync

from kr8s.objects import Deployment

deploy = Deployment.get("metrics-server", namespace="kube-system")
deploy.scale(1)

Async

from kr8s.asyncio.objects import Deployment

deploy = await Deployment.get("metrics-server", namespace="kube-system")
await deploy.scale(1)

List Pods by label selector¶

Get all Pods from all Namespaces matching a label selector.

Sync

import kr8s

selector = {'component': 'kube-scheduler'}

for pod in kr8s.get("pods", namespace=kr8s.ALL, label_selector=selector):
    print(pod.namespace, pod.name)

Async

import kr8s

selector = {'component': 'kube-scheduler'}

for pod in await kr8s.asyncio.get("pods", namespace=kr8s.ALL, label_selector=selector):
    print(pod.namespace, pod.name)

Add a label to a Pod¶

Add the label foo with the value bar to an existing Pod.

Sync

from kr8s.objects import Pod

pod = Pod("kube-apiserver", namespace="kube-system")
pod.label({"foo": "bar"})

Async

from kr8s.asyncio.objects import Pod

pod = await Pod("kube-apiserver", namespace="kube-system")
await pod.label({"foo": "bar"})

Generate a Pod¶

Generate a simple Pod with a couple of keyword arguments.

Sync

from kr8s.objects import Pod

pod = Pod.gen(name="example-1", image="nginx:latest")
pod.create()

Async

from kr8s.asyncio.objects import Pod

pod = await Pod.gen(name="example-1", image="nginx:latest")
await pod.create()

Cordon a Node¶

Cordon a Node to mark it as unschedulable.

Sync

from kr8s.objects import Node

node = Node("k8s-node-1")

node.cordon()

Async

from kr8s.asyncio.objects import Node

node = await Node("k8s-node-1")

await node.cordon()

Pod Exec¶

Exec a command in a Pod.

Sync

from kr8s.objects import Pod

pod = Pod.get("my-pod")

command = pod.exec(["uptime"])
print(command.stdout.decode())
# 13:49:05 up 23:03,  0 users,  load average: 0.66, 0.87, 0.85

Async

from kr8s.asyncio.objects import Pod

pod = await Pod.get("my-pod")

command = await pod.exec(["uptime"])
print(command.stdout.decode())
# 13:49:05 up 23:03,  0 users,  load average: 0.66, 0.87, 0.85

Port forward a Pod¶

Open a port forward to a Pod as a background task/thread.

Sync

from kr8s.objects import Pod

pod = Pod.get("my-pod")
# Listen on port 5678 on 127.0.0.1, forwarding to 5000 in the pod
pf = pod.portforward(remote_port=5000, local_port=5678)


# Starts the port forward in a background thread
pf.start()

# Your other code goes here

# Optionally stop the port forward thread (it will exit with Python anyway)
pf.stop()

Async

from kr8s.asyncio.objects import Pod

pod = await Pod.get("my-pod")
pf = pod.portforward(remote_port=1234, local_port=5678)

# Starts the port forward in a background task
await pf.start()

# Your other code goes here
# WARNING: Your code must be async and non-blocking as the port forward and your code are sharing the same event loop

# Optionally stop the port forward task (it will exit with Python anyway)
await pf.stop()

More examples¶

See the Examples Documentation for a full set of examples.