kr8s

https://docs.kr8s.org
Admin
kr8s is a simple, extensible Python client library for Kubernetes that feels familiar for folks who...
Tokens:44,065
Snippets:482
Trust Score:4.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### Start kubectl proxy

Source: https://docs.kr8s.org/en/stable/_sources/authentication.md.txt

Command to start a local proxy for the Kubernetes API.

```console
$ kubectl proxy
Starting to serve on 127.0.0.1:8001
```

--------------------------------

### Build documentation manually

Source: https://docs.kr8s.org/en/stable/_sources/contributing.md.txt

Install documentation dependencies and run sphinx-autobuild.

```bash
pip install -e .[docs]
sphinx-autobuild docs docs/_build --ignore 'docs/autoapi/**/*' --host 0.0.0.0
```

--------------------------------

### Initialize development environment with uv

Source: https://docs.kr8s.org/en/stable/_sources/contributing.md.txt

Use uv to install dependencies and synchronize the development environment.

```bash
pip install uv
uv sync --dev
```

--------------------------------

### Install kr8s in development mode

Source: https://docs.kr8s.org/en/stable/_sources/contributing.md.txt

Install the package in editable mode to reflect local changes immediately.

```bash
# Create/activate your Python environment
pip install -e .
```

--------------------------------

### Configure pre-commit hooks

Source: https://docs.kr8s.org/en/stable/_sources/contributing.md.txt

Install and run pre-commit hooks to ensure code quality before committing.

```console
$ pip install pre-commit
$ pre-commit install
$ # You can manually run pre-commit on all files too
$ pre-commit run --all
```

--------------------------------

### Define Resources in YAML

Source: https://docs.kr8s.org/en/stable/_sources/examples/creating_resources.md.txt

Example YAML manifest containing a Pod and a Service definition.

```yaml
# manifest.yaml
apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    app.kubernetes.io/name: proxy
spec:
  containers:
  - name: nginx
    image: nginx:stable
    ports:
      - containerPort: 80
        name: http-web-svc

---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app.kubernetes.io/name: proxy
  ports:
  - name: name-of-service-port
    protocol: TCP
    port: 80
    targetPort: http-web-svc
```

--------------------------------

### Install kr8s with pip

Source: https://docs.kr8s.org/en/stable/_sources/installation.md.txt

Use this command to install the package from the Python Package Index.

```console
$ pip install kr8s
```

--------------------------------

### Manage PortForward with Explicit Start and Stop

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/portforward/index.html

Manually control the port forward connection using the start and stop methods.

```python
>>> pf = PortForward(pod, 8888)
>>> await pf.start()
>>> print(f"Forwarding to port {pf.local_port}")
>>> # Do something with port 8888 on the Pod
>>> await pf.stop()
```

--------------------------------

### Wait for Pod readiness

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/objects/index.html

Wait for a Pod to be initialized and ready to start containers.

```python
>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")
```

--------------------------------

### get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) -> Self

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/asyncio/objects/index.rst.txt

Retrieve a Kubernetes resource by name or via selectors.

```APIDOC
## get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) -> Self

### Description
Get a Kubernetes resource by name or via selectors.
```

--------------------------------

### Wait for Kubernetes resource conditions

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/objects/index.html

Examples of waiting for specific resource states, such as a Pod becoming ready or a Job completing or failing.

```python
>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")
```

```python
>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])
```

--------------------------------

### Install kr8s with conda

Source: https://docs.kr8s.org/en/stable/_sources/installation.md.txt

Use this command to install the package from the conda-forge channel.

```console
$ conda install -c conda-forge kr8s
```

--------------------------------

### Port Forwarding a Kubernetes Service

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/asyncio/objects/index.rst.txt

Demonstrates how to use the portforward method as an asynchronous context manager or with explicit start and stop calls.

```python
async with service.portforward(8888) as port:
    print(f"Forwarding to port {port}")
    # Do something with port 8888
```

```python
pf = service.portforward(8888)
await pf.start()
print(f"Forwarding to port {pf.local_port}")
# Do something with port 8888
await pf.stop()
```

--------------------------------

### get

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/objects/index.html

Retrieves a Kubernetes resource by name or via selectors.

```APIDOC
## get(name=None, namespace=None, api=None, label_selector=None, field_selector=None, timeout=2, **kwargs)

### Description
Get a Kubernetes resource by name or via selectors.

### Parameters
- **name** (str) - Optional - The name of the resource.
- **namespace** (str) - Optional - The namespace of the resource.
- **api** (kr8s.api.Api) - Optional - The API client to use.
- **label_selector** (str|dict) - Optional - Label selector for filtering.
- **field_selector** (str|dict) - Optional - Field selector for filtering.
- **timeout** (int) - Optional - Timeout in seconds.
```

--------------------------------

### get(name, namespace, ...)

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/asyncio/objects/index.rst.txt

Retrieves a Kubernetes resource by name or via selectors.

```APIDOC
## get(name=None, namespace=None, api=None, label_selector=None, field_selector=None, timeout=2, **kwargs)

### Description
Get a Kubernetes resource by name or via selectors.

### Parameters
- **name** (str) - Optional. Name of the resource.
- **namespace** (str) - Optional. Namespace of the resource.
- **api** (Api) - Optional. API object to use.
- **label_selector** (str|dict) - Optional. Label selector for filtering.
- **field_selector** (str|dict) - Optional. Field selector for filtering.
- **timeout** (int) - Optional. Timeout in seconds.

### Returns
- **Self** - The retrieved object instance.
```

--------------------------------

### get(name: str | None, namespace: str | None, ...)

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/asyncio/objects/index.html

Retrieves a Kubernetes object by name and namespace.

```APIDOC
## get(name: str | None, namespace: str | None, api: Api | None, label_selector: str | dict, field_selector: str | dict, timeout: int)

### Description
Retrieves a specific Kubernetes object instance.

### Parameters
- **name** (str) - Optional name of the resource.
- **namespace** (str) - Optional namespace.
- **api** (Api) - Optional API object.
- **label_selector** (str | dict) - Filter by labels.
- **field_selector** (str | dict) - Filter by fields.
- **timeout** (int) - Request timeout.
```

--------------------------------

### Dockerfile for Kopf Operator

Source: https://docs.kr8s.org/en/stable/_sources/guides/kopf_operator.md.txt

A standard Dockerfile setup for running a Python-based Kopf controller with kr8s dependencies.

```dockerfile
FROM python:3.11
ADD controller.py /src
RUN pip install kopf kr8s
CMD kopf run /src/controller.py --verbose
```

--------------------------------

### Initialize kr8s API and get version

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/index.rst.txt

Initializes the API client using the default kubeconfig and retrieves the Kubernetes cluster version.

```python
>>> import kr8s
>>> api = kr8s.api()  # Uses the default kubeconfig
>>> print(api.version())  # Get the Kubernetes version
```

--------------------------------

### get_class(kind, version)

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/objects/index.rst.txt

Get an APIObject subclass by kind and version.

```APIDOC
## get_class(kind: str, version: str) -> type[APIObject]

### Description
Get an APIObject subclass by kind and version.

### Parameters
- **kind** (str) - Required - The Kubernetes resource kind.
- **version** (str) - Required - The Kubernetes API group/version.
```

--------------------------------

### Serve documentation locally

Source: https://docs.kr8s.org/en/stable/_sources/contributing.md.txt

Build and serve the documentation using the task runner.

```bash
uv run task docs-serve
```

--------------------------------

### Creating a Pod with Sync and Async APIs

Source: https://docs.kr8s.org/en/stable/_sources/asyncio.md.txt

Compare creating a Pod resource using the synchronous versus the asynchronous API.

```python
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()
```

```python
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()
```

--------------------------------

### Retrieve Kubernetes Resources

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/asyncio/index.rst.txt

Demonstrates various ways to fetch resources by kind and how to retrieve raw dictionary data for performance.

```python
>>> import kr8s
>>> # All of these are equivalent
>>> ings = await kr8s.asyncio.get("ing")                           # Short name
>>> ings = await kr8s.asyncio.get("ingress")                       # Singular
>>> ings = await kr8s.asyncio.get("ingresses")                     # Plural
>>> ings = await kr8s.asyncio.get("Ingress")                       # Title
>>> ings = await kr8s.asyncio.get("ingress.networking.k8s.io")     # Full group name
>>> ings = await kr8s.asyncio.get("ingress.v1.networking.k8s.io")  # Full with explicit version
>>> ings = await kr8s.asyncio.get("ingress.networking.k8s.io/v1")  # Full with explicit version alt.
>>>
>>> # Get raw dictionaries for better performance
>>> pods = [pod async for pod in kr8s.asyncio.get("pods", raw=True)]
>>> print(pods[0]["metadata"]["name"])
```

--------------------------------

### proxy_http_get

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/asyncio/objects/index.html

Performs an HTTP GET request to a service proxy.

```APIDOC
## proxy_http_get(path: str, port: int | None = None, **kwargs) -> httpx.Response

### Description
Performs an asynchronous HTTP GET request to the specified path on the service proxy.

### Parameters
- **path** (str) - Required - The path to proxy to.
- **port** (int) - Optional - The port to proxy to. If not specified, the first port in the Service's spec will be used.
- **kwargs** (dict) - Optional - Additional keyword arguments to pass to the API call.
```

--------------------------------

### Create a Pod and wait for readiness

Source: https://docs.kr8s.org/en/stable/_sources/examples/creating_resources.md.txt

Create a Pod and block execution or poll until the resource reaches a ready state.

```python
from kr8s.objects import Pod

pod = Pod(...)
pod.create()

# Option 1: Block until ready, similar to kubectl wait
pod.wait("condition=Ready")

# Option 2: Poll readiness
import time
while not pod.ready():
    time.sleep(1)
```

```python
from kr8s.asyncio.objects import Pod

pod = await Pod(...)
await pod.create()

# Option 1: Block until ready, similar to kubectl wait
await pod.wait("condition=Ready")

# Option 2: Poll readiness
import asyncio
while not await pod.ready():
    await asyncio.sleep(1)
```

--------------------------------

### kr8s.asyncio.objects.APIObject.get

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/asyncio/objects/index.rst.txt

Get a Kubernetes resource by name or via selectors.

```APIDOC
## get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) -> Self

### Description
Get a Kubernetes resource by name or via selectors.

### Parameters
- **name** (str) - Optional - Name of the resource.
- **namespace** (str) - Optional - Namespace of the resource.
- **api** (kr8s._api.Api) - Optional - API object to use.
- **label_selector** (str | dict) - Optional - Label selector.
- **field_selector** (str | dict) - Optional - Field selector.
- **timeout** (int) - Optional - Timeout in seconds.
```

--------------------------------

### Deployment.ready_pods()

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/asyncio/objects/index.rst.txt

Returns a list of Pods associated with the Deployment that are currently ready.

```APIDOC
## ready_pods()

### Description
Returns a list of Pods for this Deployment that are in a ready state.

### Signature
`async def ready_pods() -> list[Pod]`
```

--------------------------------

### List Ready Pods: kr8s vs pykube-ng

Source: https://docs.kr8s.org/en/stable/_sources/alternatives.md.txt

Comparison of filtering ready pods in a specific namespace between pykube-ng and kr8s.

```python
import pykube

api = pykube.HTTPClient(pykube.KubeConfig.from_file())
for pod in pykube.Pod.objects(api).filter(namespace="kube-system"):
    if pod.ready:
        print(pod.name)
```

```python
import kr8s

for pod in kr8s.get("pods", namespace="kube-system"):
    if pod.ready():
        print(pod.name)
```

--------------------------------

### PortForward Usage Patterns

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/portforward/index.rst.txt

Demonstrates using PortForward as an async context manager, with explicit start/stop methods, and with custom bind addresses.

```python
async with PortForward(pod, 8888) as port:
    print(f"Forwarding to port {port}")
    # Do something with port 8888 on the Pod
```

```python
pf = PortForward(pod, 8888)
await pf.start()
print(f"Forwarding to port {pf.local_port}")
# Do something with port 8888 on the Pod
await pf.stop()
```

```python
async with PortForward(pod, 8888, address=["127.0.0.1", "10.20.0.1"]) as port:
    print(f"Forwarding to port {port}")
    # Do something with port 8888 on the Pod, port will be bind to 127.0.0.1 and 10.20.0.1
```

--------------------------------

### Run tests manually

Source: https://docs.kr8s.org/en/stable/_sources/contributing.md.txt

Install test dependencies and invoke pytest directly.

```bash
pip install -e .[test]
pytest kr8s
```

--------------------------------

### Get a Pod by name

Source: https://docs.kr8s.org/en/stable/_sources/object.md.txt

Retrieves an existing Pod object from the cluster by its name.

```python
from kr8s.object import Pod

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

```python
from kr8s.asyncio.object import Pod

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

--------------------------------

### Scale Deployment: kr8s vs lightkube

Source: https://docs.kr8s.org/en/stable/_sources/alternatives.md.txt

Comparison of scaling a deployment between lightkube and kr8s.

```python
from lightkube import Client
from lightkube.resources.apps_v1 import Deployment
from lightkube.models.meta_v1 import ObjectMeta
from lightkube.models.autoscaling_v1 import ScaleSpec

client = Client()
deploy = Deployment.Scale(
    metadata=ObjectMeta(name='metrics-server', namespace='kube-system'),
    spec=ScaleSpec(replicas=1)
)
client.replace(deploy)
```

```python
from kr8s.objects import Deployment

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

--------------------------------

### Port Forwarding with kr8s Pods

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/objects/index.html

Demonstrates how to use port forwarding with a Pod using either an async context manager or explicit start/stop methods.

```python
>>> async with pod.portforward(8888) as port:
...     print(f"Forwarding to port {port}")
...     # Do something with port 8888
```

```python
>>> pf = pod.portforward(8888)
>>> await pf.start()
>>> print(f"Forwarding to port {pf.local_port}")
>>> # Do something with port 8888
>>> await pf.stop()
```

```python
>>> async with pod.PortForward(8888, address=["127.0.0.1", "10.20.0.1"]) as port:
...     print(f"Forwarding to port {port}")
...     # Do something with port 8888 on the Pod, port will be bind to 127.0.0.1 and 10.20.0.1
```

--------------------------------

### Create a new Pod

Source: https://docs.kr8s.org/en/stable/_sources/object.md.txt

Demonstrates creating a Pod object from a specification dictionary.

```python
# Create a new Pod
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()
```

```python
# Create a new Pod
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()
```

--------------------------------

### List Ingresses Using Various Naming Styles

Source: https://docs.kr8s.org/en/stable/_sources/examples/listing_resources.md.txt

Demonstrates multiple ways to reference resource types, including shorthand, full group names, and class objects.

```python
import kr8s
from kr8s.objects import Ingress

# All of these are equivalent
ings = list(kr8s.get("ing"))                           # Short name
ings = list(kr8s.get("ingress"))                       # Singular
ings = list(kr8s.get("ingresses"))                     # Plural
ings = list(kr8s.get("Ingress"))                       # Title
ings = list(kr8s.get("ingress.networking.k8s.io"))     # Full group name
ings = list(kr8s.get("ingress.v1.networking.k8s.io"))  # Full with explicit version
ings = list(kr8s.get("ingress.networking.k8s.io/v1"))  # Full with explicit version alt.
ings = list(kr8s.get(Ingress))                         # Class
```

```python
import kr8s.asyncio
from kr8s.asyncio.objects import Ingress

# All of these are equivalent
ings = [ing async for ing in kr8s.asyncio.get("ing")]                           # Short name
ings = [ing async for ing in kr8s.asyncio.get("ingress")]                       # Singular
ings = [ing async for ing in kr8s.asyncio.get("ingresses")]                     # Plural
ings = [ing async for ing in kr8s.asyncio.get("Ingress")]                       # Title
ings = [ing async for ing in kr8s.asyncio.get("ingress.networking.k8s.io")]     # Full group name
ings = [ing async for ing in kr8s.asyncio.get("ingress.v1.networking.k8s.io")]  # Full with explicit version
ings = [ing async for ing in kr8s.asyncio.get("ingress.networking.k8s.io/v1")]  # Full with explicit version alt.
ings = [ing async for ing in kr8s.asyncio.get(Ingress)]                         # Class
```

--------------------------------

### Pod.ready()

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/objects/index.html

Checks if the pod is currently in a ready state.

```APIDOC
## Pod.ready()

### Description
Check if the pod is ready.

### Returns
- **bool** - True if the pod is ready, False otherwise.
```

--------------------------------

### Create Pod for Testing

Source: https://docs.kr8s.org/en/stable/_sources/guides/kopf_operator.md.txt

Initialize and create a Pod object using kr8s to trigger controller logic.

```python
>>> from kr8s.objects import Pod
>>> pod = Pod.gen(name="test-pod", image="nginx:latest")
>>> pod.create()
```

--------------------------------

### Open a background port forward

Source: https://docs.kr8s.org/en/stable/_sources/examples/pod_operations.md.txt

Starts a port forward as a background task or thread, allowing the main process to continue execution.

```python
from kr8s.objects import Pod

pod = Pod.get("my-pod")
pf = pod.portforward(remote_port=1234, 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()
```

```python
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()
```

--------------------------------

### Fetch a Pod using pykube

Source: https://docs.kr8s.org/en/stable/_sources/object.md.txt

Initializes a pykube client and retrieves a specific Pod object to be used for conversion.

```python
import pykube

api = pykube.HTTPClient(pykube.KubeConfig.from_file())
pykube_pod = pykube.Pod.objects(api).filter(namespace="gondor-system").get(name="my-pod")
```

--------------------------------

### Port Forwarding a Service

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/objects/index.html

Demonstrates how to use port forwarding with a service using either an async context manager or explicit start/stop methods.

```python
>>> async with service.portforward(8888) as port:
...     print(f"Forwarding to port {port}")
...     # Do something with port 8888
```

```python
>>> pf = service.portforward(8888)
>>> await pf.start()
>>> print(f"Forwarding to port {pf.local_port}")
>>> # Do something with port 8888
>>> await pf.stop()
```

--------------------------------

### List Pods with Label Selector: kr8s vs kubernetes

Source: https://docs.kr8s.org/en/stable/_sources/alternatives.md.txt

Comparison of listing pods using a label selector between the official kubernetes library and kr8s.

```python
from kubernetes import client, config

selector = {'component': 'kube-scheduler'}
selector_str = ",".join([f"{key}={value}" for key, value in selector.items()])

config.load_kube_config()

v1 = client.CoreV1Api()
for pods in v1.list_pod_for_all_namespaces(label_selector=selector_str, ).items:
    print(pod.metadata.namespace, pod.metadata.name)
```

```python
import kr8s

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

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

--------------------------------

### Initialize kr8s API client

Source: https://docs.kr8s.org/en/stable/_sources/authentication.md.txt

Initialize the client using either synchronous or asynchronous patterns.

```python
import kr8s

client = kr8s.api()
```

```python
import kr8s.asyncio

client = await kr8s.asyncio.api()
```

--------------------------------

### Retrieve Kubernetes version with explicit client

Source: https://docs.kr8s.org/en/stable/_sources/client.md.txt

Demonstrates manual construction of an API client object to perform operations.

```python
import kr8s

api = kr8s.api()
version = api.version()
print(version)
```

```python
import kr8s

api = await kr8s.asyncio.api()
version = await api.version()
print(version)
```

--------------------------------

### Service.ready_pods

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/asyncio/objects/index.rst.txt

Return a list of ready Pods for this Service.

```APIDOC
## ready_pods() -> list[Pod]

### Description
Return a list of ready Pods for this Service.
```

--------------------------------

### Running PortForward Forever

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/portforward/index.rst.txt

Shows how to initiate a port forward and keep it running indefinitely.

```python
pf = pod.portforward(remote_port=8888, local_port=8889)
# or
pf = PortForward(pod, remote_port=8888, local_port=8889)
await pf.run_forever()
```

--------------------------------

### kr8s.api()

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/index.rst.txt

Initializes a connection to the Kubernetes cluster using the default kubeconfig.

```APIDOC
## kr8s.api()

### Description
Initializes and returns an API client instance to interact with the Kubernetes cluster.

### Usage
```python
import kr8s
api = kr8s.api()
```
```

--------------------------------

### kr8s.asyncio.create

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/asyncio/index.rst.txt

Creates resources in the Kubernetes cluster.

```APIDOC
## async kr8s.asyncio.create(resources, api=None, _asyncio=True)

### Description
Creates the provided list of resources in the Kubernetes cluster.

### Parameters
- **resources** (list[kr8s._objects.APIObject]) - Required - The list of resources to create.
```

--------------------------------

### Cache client objects with factory functions

Source: https://docs.kr8s.org/en/stable/_sources/client.md.txt

Demonstrates how identical arguments result in cached client instances while different arguments create new ones.

```python
import kr8s

api = kr8s.api(kubeconfig="/foo/bar")
api2 = kr8s.api(kubeconfig="/foo/bar")
# api2 is a pointer to api due to caching

api3 = kr8s.api(kubeconfig="/fizz/buzz")
# api3 is a new kr8s.Api instance as it was created with different arguments
```

```python
import kr8s

api = await kr8s.asyncio.api(kubeconfig="/foo/bar")
api2 = await kr8s.asyncio.api(kubeconfig="/foo/bar")
# api2 is a pointer to api due to caching

api3 = await kr8s.asyncio.api(kubeconfig="/fizz/buzz")
# api3 is a new kr8s.Api instance as it was created with different arguments
```

--------------------------------

### Pod.portforward()

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/objects/index.html

Establishes a port forward connection to the pod.

```APIDOC
## Pod.portforward()

### Description
Port forward a pod.

### Parameters
- **remote_port** (int) - Required - The port on the Pod to forward to.
- **local_port** (str|int) - Optional - The local port to listen on.
- **address** (str) - Optional - Address to listen on.
```

--------------------------------

### Implement a Pod OS Labeling Controller

Source: https://docs.kr8s.org/en/stable/_sources/guides/kopf_operator.md.txt

A complete controller implementation that watches for pod creation or resumption to apply OS-specific labels. Choose between synchronous and asynchronous implementations based on your application requirements.

```python
# controller.py
import re

import kopf
import kr8s
from kr8s.objects import Pod


@kopf.on.resume("pods")
@kopf.on.create("pods")
def add_os_labels(body, logger, **kwargs):
    pod = Pod(body)

    # Pod was deleted while trying to add OS labels, give up
    if not pod.exists():
        return

    # Pod already has OS labels, skip
    if "os-release/id" in pod.labels:
        return

    # Pod is not ready yet, retry in a bit
    if not pod.ready():
        raise kopf.TemporaryError(f"Pod {pod.name} is not ready yet", delay=10)

    # Get OS info
    try:
        output = pod.exec(["cat", "/etc/os-release"])
        os_info = output.stdout.decode()
    except kr8s.ExecError:
        logger.error(
            f"Failed to exec in pod {pod.name}, "
            "either cat is not included in the image or /etc/os-release is missing."
        )
        pod.label({"os-release/id": "unknown"})
        return

    # Clean OS labels
    labels = {}
    for label in os_info.splitlines():
        key, value = label.split("=")
        key = f"os-release/{key.lower().replace('_', '-')}"
        # Kubernetes only accepts label values with alphanumeric characters,
        # dots, dashes and underscores and a maximum length of 63 characters.
        value = re.sub("[^0-9a-zA-Z_.-]+", "", value)[:63]
        labels[key] = value

    # Apply OS labels
    pod.label(labels)
```

```python
# controller.py
import re

import kopf
import kr8s
from kr8s.asyncio.objects import Pod


@kopf.on.resume("pods")
@kopf.on.create("pods")
async def add_os_labels(body, logger, **kwargs):
    pod = await Pod(body)

    # Pod was deleted while trying to add OS labels, give up
    if not await pod.exists():
        return

    # Pod already has OS labels, skip
    if "os-release/id" in pod.labels:
        return

    # Pod is not ready yet, retry in a bit
    if not await pod.ready():
        raise kopf.TemporaryError(f"Pod {pod.name} is not ready yet", delay=10)

    # Get OS info
    try:
        output = await pod.exec(["cat", "/etc/os-release"])
        os_info = output.stdout.decode()
    except kr8s.ExecError:
        logger.error(
            f"Failed to exec in pod {pod.name}, "
            "either cat is not included in the image or /etc/os-release is missing."
        )
        await pod.label({"os-release/id": "unknown"})
        return

    # Clean OS labels
    labels = {}
    for label in os_info.splitlines():
        key, value = label.split("=")
        key = f"os-release/{key.lower().replace('_', '-')}"
        # Kubernetes only accepts label values with alphanumeric characters,
        # dots, dashes and underscores and a maximum length of 63 characters.
        value = re.sub("[^0-9a-zA-Z_.-]+", "", value)[:63]
        labels[key] = value

    # Apply OS labels
    await pod.label(labels)
```

--------------------------------

### PortForward.start() / PortForward.stop()

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/portforward/index.rst.txt

Methods to control the lifecycle of the port forward connection.

```APIDOC
## Method: start()

### Description
Starts the port forward connection in the background.

## Method: stop()

### Description
Stops the background port forward connection.
```

--------------------------------

### Pass explicit client to Kubernetes objects

Source: https://docs.kr8s.org/en/stable/_sources/client.md.txt

Demonstrates initializing a Kubernetes object with a custom API client instance.

```python
import kr8s
from kr8s.objects import Pod

api = kr8s.api(kubeconfig="/foo/bar")

pod = Pod({...}, api=api)
```

```python
import kr8s
from kr8s.asyncio.objects import Pod

api = await kr8s.api(kubeconfig="/foo/bar")

pod = Pod({...}, api=api)
```

--------------------------------

### List Ready Pods

Source: https://docs.kr8s.org/en/stable/_sources/examples/listing_resources.md.txt

Retrieves Pods in a specific namespace and filters them by their ready status.

```python
import kr8s

for pod in kr8s.get("pods", namespace="kube-system"):
    if pod.ready():
        print(pod.name)
```

```python
import kr8s

async for pod in kr8s.asyncio.get("pods", namespace="kube-system"):
    if await pod.ready():
        print(pod.name)
```

--------------------------------

### Perform low-level API call with custom base URL

Source: https://docs.kr8s.org/en/stable/_sources/client.md.txt

Demonstrates building a custom URL by setting the base and version arguments in call_api.

```python
import kr8s.asyncio

api = await kr8s.asyncio.api()
async with api.call_api("GET", base="/version", version="") as r:
    version = await r.json()
print(version)
```

--------------------------------

### Run tests with task

Source: https://docs.kr8s.org/en/stable/_sources/contributing.md.txt

Execute the test suite using the configured task runner.

```bash
uv run task test
```

--------------------------------

### List Nodes: kr8s vs kubernetes_asyncio

Source: https://docs.kr8s.org/en/stable/_sources/alternatives.md.txt

Comparison of listing cluster nodes using asynchronous patterns between kubernetes_asyncio and kr8s.

```python
from kubernetes_asyncio import client, config
from kubernetes_asyncio.client.api_client import ApiClient

await config.load_kube_config()

async with ApiClient() as api:
    v1 = client.CoreV1Api(api)
    nodes = await v1.list_node()
    for node in nodes.items:
        print(node.metadata.name)
```

```python
import kr8s.asyncio

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

--------------------------------

### kr8s.create(resources, api=None)

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/index.rst.txt

Creates specified resources within the Kubernetes cluster.

```APIDOC
## kr8s.create(resources, api=None)

### Description
Creates a list of Kubernetes resources in the cluster.

### Parameters
- **resources** (list[type[APIObject]]) - Required - A list of Kubernetes objects to create.
- **api** (object) - Optional - The API client instance to use.
```

--------------------------------

### Service.ready

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/asyncio/objects/index.rst.txt

Check if the service is ready.

```APIDOC
## ready() -> bool

### Description
Check if the service is ready.
```

--------------------------------

### list

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/objects/index.html

List objects in Kubernetes.

```APIDOC
## list(**kwargs)

### Description
List objects in Kubernetes.

### Parameters
- **api** (object) - Optional - An optional API object to use.
- **kwargs** (dict) - Optional - Keyword arguments to pass to kr8s.get().
```

--------------------------------

### pprint(use_rich: bool = True, theme: str = 'ansi_dark') -> None

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/asyncio/objects/index.rst.txt

Pretty print the Kubernetes object to stdout, optionally using rich for syntax highlighting.

```APIDOC
## pprint(use_rich: bool = True, theme: str = 'ansi_dark') -> None

### Description
Pretty print this object to stdout. Prints the object as YAML (using rich for syntax highlighting if available).

### Parameters
- **use_rich** (bool) - Optional - Use rich to pretty print. If rich is not installed this will be ignored.
- **theme** (str) - Optional - The pygments theme for rich to use. Defaults to "ansi_dark".
```

--------------------------------

### Retrieve Kubernetes version without explicit client

Source: https://docs.kr8s.org/en/stable/_sources/client.md.txt

Demonstrates fetching the Kubernetes version using implicit client management.

```python
import kr8s

version = kr8s.version()  # Look ma no client needed!
print(version)
```

```python
import kr8s

version = await kr8s.asyncio.version()  # Look ma no client needed!
print(version)
```

--------------------------------

### Containerize the Controller

Source: https://docs.kr8s.org/en/stable/_sources/guides/labelling_operator.md.txt

Dockerfile and build commands for packaging the Python controller script.

```dockerfile
# Dockerfile
FROM python:3.11

WORKDIR /usr/local/src

RUN pip install kr8s

COPY controller.py /usr/local/src/

CMD ["python3", "/usr/local/src/controller.py"]
```

```console
$ docker build -t foo/labelling-operator:latest .
$ docker push foo/labelling-operator:latest
```

--------------------------------

### Initialize kr8s API

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/asyncio/index.rst.txt

Create an asynchronous API object to interact with the Kubernetes cluster using default configuration.

```python
>>> import kr8s
>>> api = await kr8s.asyncio.api()  # Uses the default kubeconfig
>>> print(await api.version())  # Get the Kubernetes version
```

--------------------------------

### List Pods Across All Namespaces

Source: https://docs.kr8s.org/en/stable/_sources/examples/listing_resources.md.txt

Retrieve all pods in the cluster by setting the namespace parameter to kr8s.ALL.

```python
import kr8s

for pod in kr8s.get("pods", namespace=kr8s.ALL):
    print(pod.status.podIP, pod.metadata.namespace, pod.metadata.name)
```

```python
import kr8s

async for pod in kr8s.asyncio.get("pods", namespace=kr8s.ALL):
    print(pod.status.podIP, pod.metadata.namespace, pod.metadata.name)
```

--------------------------------

### Define kopf event handlers

Source: https://docs.kr8s.org/en/stable/_sources/guides/kopf_operator.md.txt

Sets up listeners for Pod creation and resume events using synchronous or asynchronous functions.

```python
# controller.py
import kopf


@kopf.on.resume("pods")
@kopf.on.create("pods")
def add_os_labels(body, logger, **kwargs):
    pass
```

```python
# controller.py
import kopf


@kopf.on.resume("pods")
@kopf.on.create("pods")
async def add_os_labels(body, logger, **kwargs):
    pass
```

--------------------------------

### kr8s.asyncio.get

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/asyncio/index.rst.txt

Retrieves Kubernetes resources by kind and name.

```APIDOC
## async kr8s.asyncio.get(kind, *names, namespace=None, label_selector=None, field_selector=None, as_object=None, allow_unknown_type=True, raw=False, api=None, _asyncio=True, **kwargs)

### Description
Retrieves a resource from the Kubernetes cluster based on its kind and name(s). Supports filtering via label and field selectors.

### Parameters
- **kind** (str) - Required - The kind of resource to get.
- **names** (str) - Optional - The names of the resources to get.
- **namespace** (str) - Optional - The namespace to query.
- **label_selector** (str|dict) - Optional - Filter by labels.
- **field_selector** (str|dict) - Optional - Filter by fields.
- **raw** (bool) - Optional - If True, returns raw dictionaries instead of APIObject instances.

### Returns
- **List[APIObject]** - The Kubernetes resource objects (or dicts if raw=True).
```

--------------------------------

### Manage object labels

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/objects/index.html

Demonstrates adding and removing labels from a Kubernetes resource.

```python
>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")
```

```python
>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")
```

```python
>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")
```

--------------------------------

### Execute Pod-Specific Methods

Source: https://docs.kr8s.org/en/stable/_sources/object.md.txt

Use specialized methods for Pod resources such as logs, ready checks, and command execution.

```python
# Get Pod logs
logs = [line for line in pod.logs()]

# Check if Pod containers are ready
pod.ready()
# True

# Exec a command in a Pod
pod.exec(["uptime"])
# CompletedExec(args=['uptime'], stdout=..., stderr=..., returncode=0)
```

```python
# Get Pod logs
logs = [line async for line in pod.logs()]

# Check if Pod containers are ready
await pod.ready()
# True

# Exec a command in a Pod
await pod.exec(["uptime"])
# CompletedExec(args=['uptime'], stdout=..., stderr=..., returncode=0)
```

--------------------------------

### Namespace.create

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/objects/index.rst.txt

Creates the current object in the Kubernetes cluster.

```APIDOC
## Namespace.create()

### Description
Create this object in Kubernetes.
```

--------------------------------

### Execute a command in a Pod

Source: https://docs.kr8s.org/en/stable/_sources/examples/pod_operations.md.txt

Run a command and capture the output. Use the sync version for standard scripts and the async version for asyncio applications.

```python
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
```

```python
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
```

--------------------------------

### Open a port forward and communicate

Source: https://docs.kr8s.org/en/stable/examples/pod_operations.html

Establish a port forward to a Pod to communicate with internal services.

```python
import requests
from kr8s.objects import Pod

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

with pod.portforward(remote_port=1234) as local_port:
    # Make an API request
    resp = requests.get(f"http://localhost:{local_port}")
    # Do something with the response

# Listen on port 8888 on all addresses, forwarding to 5000 in the pod
with pod.portforward(remote_port=5000, local_port=8888, address=["0.0.0.0"])
    # Make an API request
    resp = requests.get(f"http://0.0.0.0:{local_port}")
    # Do something with the response
  
# Listen on port 8888 on localhost and selected IP, forwarding to 5000 in the pod
pf = pod.portforward(port=5000, local_port=8888, address=["127.0.0.1", "10.19.21.1"])
    # Make an API request
    resp = requests.get(f"http://10.19.21.1:{local_port}")
    # Do something with the response
```

```python
import httpx
from kr8s.asyncio.objects import Pod

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

async with pod.portforward(remote_port=1234) as local_port, httpx.AsyncClient() as client:
    # Make an API request
    resp = await client.get(f"http://localhost:{local_port}")
    # Do something with the response
```

--------------------------------

### Label Kubernetes objects

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/objects/index.html

Shows the equivalent ways to apply labels to a Kubernetes object using either a dictionary or keyword arguments.

```python
>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")
```

--------------------------------

### Deployment.scale()

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/asyncio/objects/index.rst.txt

Scales the number of replicas for the Deployment.

```APIDOC
## scale(replicas: int | None = None)

### Description
Updates the number of replicas for this Deployment in Kubernetes.

### Parameters
- **replicas** (int) - Optional - The desired number of replicas.
```

--------------------------------

### Api.get

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/asyncio/index.rst.txt

Retrieves Kubernetes resources based on kind, names, and optional filters.

```APIDOC
## Method: Api.get

### Description
Get Kubernetes resources. This method returns an asynchronous generator yielding the requested resources.

### Parameters
- **kind** (str | type) - Required - The kind of resource to get.
- **names** (*str) - Optional - The names of specific resources to get.
- **namespace** (str) - Optional - The namespace to get the resource from.
- **label_selector** (str | dict) - Optional - The label selector to filter the resources by.
- **field_selector** (str | dict) - Optional - The field selector to filter the resources by.
- **as_object** (type) - Optional - The object to return the resources as.
- **allow_unknown_type** (bool) - Optional - Automatically create a class for the resource if none exists, default True.
- **raw** (bool) - Optional - If True, return raw dictionaries instead of APIObject instances, default False.
```

--------------------------------

### Create Resources from YAML Files

Source: https://docs.kr8s.org/en/stable/_sources/examples/creating_resources.md.txt

Loads resources from a YAML file and creates them in the cluster.

```python
import kr8s
from kr8s.objects import objects_from_files

resources = objects_from_files("manifest.yaml")

kr8s.create(resources)
```

```python
import kr8s.asyncio
from kr8s.asyncio.objects import objects_from_files

resources = await objects_from_files("manifest.yaml")

await kr8s.asyncio.create(resources)
```

--------------------------------

### Object Lifecycle and Management

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/objects/index.rst.txt

Methods for interacting with Kubernetes resources, including creation, deletion, patching, and scaling.

```APIDOC
## get(name, namespace, api, label_selector, field_selector, timeout)

### Description
Retrieves a Kubernetes resource by name or via selectors.

## exists(ensure)

### Description
Checks if the object exists in the Kubernetes cluster.

## create()

### Description
Creates the object in the Kubernetes cluster.

## delete(propagation_policy, grace_period, force)

### Description
Deletes the object from the Kubernetes cluster.

## refresh()

### Description
Refreshes the object state from the Kubernetes cluster.

## patch(patch, subresource, type)

### Description
Applies a patch to the object in the Kubernetes cluster.

## scale(replicas)

### Description
Scales the object (e.g., Deployment or ReplicaSet) in the Kubernetes cluster.
```

--------------------------------

### kr8s.asyncio.objects.objects_from_files

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/asyncio/objects/index.html

Creates a list of APIObject instances from Kubernetes resource files at a given path.

```APIDOC
## kr8s.asyncio.objects.objects_from_files(path, api=None, recursive=False, _asyncio=True)

### Description
Create APIObjects from Kubernetes resource files.

### Parameters
- **path** (str|pathlib.Path) - Required - A path to a Kubernetes resource file or directory.
- **api** (kr8s._api.Api) - Optional - An optional API instance to use.
- **recursive** (bool) - Optional - Whether to recursively search for resource files.
- **_asyncio** (bool) - Optional - Whether to use asyncio or not.

### Returns
- **list[APIObject]** - A list of APIObject subclass instances.

### Raises
- **ValueError** - If the resource kind or API version is not supported.
```

--------------------------------

### Deploy the Controller

Source: https://docs.kr8s.org/en/stable/_sources/guides/labelling_operator.md.txt

Deployment manifest and command to run the operator in the cluster.

```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: labelling-operator
spec:
  replicas: 1
  selector:
    matchLabels:
      app: labelling-operator
  template:
    metadata:
      labels:
        app: labelling-operator
    spec:
      serviceAccountName: labelling-operator
      containers:
      - name: operator
        image: foo/labelling-operator:latest
```

```console
$ kubectl apply -f deployment.yaml
```

--------------------------------

### exec(command, container=None, stdin=None, stdout=None, stderr=None, check=True, capture_output=True, timeout=None)

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/asyncio/objects/index.html

Executes a command in a container and waits for completion, behaving similarly to subprocess.run().

```APIDOC
## exec(command, container=None, stdin=None, stdout=None, stderr=None, check=True, capture_output=True, timeout=None)

### Description
Run a command in a container and wait until it completes.

### Parameters
- **command** (list[str]) - Required - Command to execute.
- **container** (str) - Optional - Container to execute the command in.
- **stdin** (str | BinaryIO) - Optional - Read stdin to the container.
- **stdout** (BinaryIO) - Optional - Write stdout to the provided writable stream object.
- **stderr** (BinaryIO) - Optional - Write stderr to the provided writable stream object.
- **check** (bool) - Optional - If True, raise an exception if the command fails.
- **capture_output** (bool) - Optional - If True, store stdout and stderr from the container in an attribute.
- **timeout** (int) - Optional - Timeout for receiving bytes.
```

--------------------------------

### ReplicationController.create

Source: https://docs.kr8s.org/en/stable/autoapi/kr8s/asyncio/objects/index.html

Creates the current object instance in the Kubernetes cluster.

```APIDOC
## ReplicationController.create

### Description
Create this object in Kubernetes.
```

--------------------------------

### pprint(use_rich, theme)

Source: https://docs.kr8s.org/en/stable/_sources/autoapi/kr8s/objects/index.rst.txt

Pretty prints the object to stdout.

```APIDOC
## pprint(use_rich, theme)

### Description
Pretty print this object to stdout as YAML.

### Parameters
- **use_rich** (bool) - Optional - Use rich for syntax highlighting.
- **theme** (str) - Optional - The pygments theme to use.
```
Tokens:
Raw