{"id":4970,"library":"kr8s","title":"kr8s","description":"kr8s is a simple, extensible Python client library for Kubernetes, designed to feel familiar for users accustomed to `kubectl`. It provides a high-level API for interacting with Kubernetes clusters, offering both synchronous and asynchronous interfaces. The library abstracts away many low-level API details, focusing on developer experience and ease of use for scripting, automation, and building Kubernetes operators. It is actively maintained with regular updates.","status":"active","version":"0.20.15","language":"en","source_language":"en","source_url":"https://github.com/kr8s-org/kr8s.git","tags":["kubernetes","client","kubectl","automation","asyncio","python","devops"],"install":[{"cmd":"pip install kr8s","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Asynchronous I/O backend","package":"anyio"},{"reason":"Caching mechanisms","package":"cachetools"},{"reason":"Cryptographic operations for secure communication","package":"cryptography"},{"reason":"Enhanced exception handling (Python 3.10+)","package":"exceptiongroup"},{"reason":"Asynchronous HTTP client","package":"httpx"},{"reason":"WebSocket support for httpx","package":"httpx-ws"},{"reason":"Version parsing and comparison","package":"packaging"},{"reason":"Dot notation access for dictionaries","package":"python-box"},{"reason":"JSONPath querying","package":"python-jsonpath"},{"reason":"YAML parsing and serialization","package":"pyyaml"},{"reason":"Backports of new typing features","package":"typing-extensions"}],"imports":[{"note":"Primary synchronous API entry point.","symbol":"kr8s","correct":"import kr8s"},{"note":"Import specific Kubernetes resource objects.","symbol":"Pod","correct":"from kr8s.objects import Pod"},{"note":"Entry point for the asynchronous API.","symbol":"asyncio","correct":"import kr8s.asyncio"}],"quickstart":{"code":"import kr8s\n\n# Connect to the Kubernetes API (uses kubeconfig by default)\n# Equivalent to 'kubectl get nodes'\n\ntry:\n    # Synchronous API\n    nodes = kr8s.get(\"nodes\")\n    print(\"Synchronous API - Nodes found:\")\n    for node in nodes:\n        print(f\"- {node.name}\")\n\n    # Example using a specific object type and creating one\n    from kr8s.objects import Pod\n\n    # Define a simple Pod specification as a Python dictionary\n    pod_manifest = {\n        \"apiVersion\": \"v1\",\n        \"kind\": \"Pod\",\n        \"metadata\": {\n            \"name\": \"my-test-pod\",\n            \"labels\": {\"app\": \"my-app\"}\n        },\n        \"spec\": {\n            \"containers\": [\n                {\"name\": \"nginx\", \"image\": \"nginx:latest\"}\n            ]\n        }\n    }\n\n    print(f\"\\nAttempting to create pod: {pod_manifest['metadata']['name']}\")\n    test_pod = Pod(pod_manifest)\n    test_pod.create()\n    print(f\"Pod '{test_pod.name}' created in namespace '{test_pod.namespace}'.\")\n\n    # Wait for the pod to be ready (optional)\n    print(\"Waiting for pod to be ready...\")\n    test_pod.wait(conditions=[\"Ready\"], timeout=60)\n    print(\"Pod is ready!\")\n\n    # Clean up the pod\n    print(f\"\\nDeleting pod: {test_pod.name}\")\n    test_pod.delete(cascade=True)\n    print(\"Pod deleted.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure you have a running Kubernetes cluster and valid kubeconfig configured (e.g., `minikube start`).\")\n","lang":"python","description":"This quickstart demonstrates basic synchronous interaction with a Kubernetes cluster using `kr8s`. It retrieves a list of nodes, creates a simple Nginx pod, waits for it to become ready, and then deletes it. kr8s automatically uses your existing kubeconfig for authentication, similar to `kubectl`."},"warnings":[{"fix":"Familiarize yourself with the kr8s design philosophy as outlined in its documentation. Explicit API client creation (e.g., `api = kr8s.api()`) allows for more control if needed.","message":"Unlike some auto-generated Kubernetes client libraries, kr8s is designed with a `kubectl`-like API. It simplifies interactions and makes assumptions about authentication and API versions from your environment/kubeconfig. This is a design choice to reduce boilerplate but may differ from expectations if coming from more verbose, low-level clients.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to `kr8s` documentation on `APIObject` for extending its resource model. For strict validation, consider using Lightkube models or direct dictionary manipulation for spec definitions.","message":"kr8s's object model is an extensible, flexible, minimal set, not a 1:1 reflection of the full Kubernetes OpenAPI schema. While it covers common resources, complex or custom resource definitions might require direct API calls or subclassing `kr8s.objects.APIObject` for full fidelity. For strict typing and schema validation, consider integrating with libraries like `Lightkube`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Choose either the synchronous or asynchronous API for a given code path. When using `kr8s` in an `asyncio` application, prefer `kr8s.asyncio` for non-blocking operations. When integrating sync `kr8s` with async code, consider `anyio.to_thread.run_sync` if you need to call blocking kr8s functions.","message":"kr8s provides both synchronous (`import kr8s`) and asynchronous (`import kr8s.asyncio`) APIs. The synchronous API is a wrapper around the asynchronous one. Mixing them incorrectly or using the synchronous API within an existing `asyncio` event loop without proper handling can lead to blocking or unexpected behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Kubernetes cluster is running a currently supported version. Regularly check the Kubernetes project's and your cloud provider's EOL policies, and the `kr8s` version support documentation.","message":"kr8s aims to support actively maintained Kubernetes versions. As Kubernetes versions reach their end-of-life (EOL) from the community and cloud providers, kr8s may drop official support and testing for these versions. This could lead to compatibility issues for users on older, unsupported Kubernetes clusters.","severity":"breaking","affected_versions":"All versions, specifically against EOL Kubernetes clusters"},{"fix":"Update any custom direct API calls from `api(..., data=...)` to `api(..., content=...)` to ensure future compatibility. Consult the changelog for specific API methods affected.","message":"In version 0.20.15, a change was implemented to \"Use `content` arg instead of `data` when calling api\". This implies that using the `data` argument in direct API calls might be deprecated or will be removed in future versions.","severity":"deprecated","affected_versions":">=0.20.15"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}