pykube-ng

library23.6.0pypypi✓ verified 87d ago

Pykube-ng is a lightweight Python 3.6+ client library for Kubernetes, providing a Python-native way to interact with the Kubernetes API. It's a community-maintained fork of the unmaintained `kelproject/pykube` library, focusing on simplicity and direct object interaction. The current stable version is 23.6.0, with releases occurring periodically to maintain compatibility and add features.

devops http-networking

pip install pykube-ng

package ↗homepage ↗

INSTALL

IMPORT

SIG · PYKUBE-NG

pykube-ng

devopspythonv23.6.0

Install

2.2s avg

Import

743ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v23.6.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.783s · 23.5MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.2s · import 0.704s · 25MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HTTPClient

✓ from pykube import HTTPClient

KubeConfig

✓ from pykube import KubeConfig

Deployment

✓ from pykube import Deployment

Pod

✓ from pykube import Pod

all

✓ from pykube import all

✗ import pykube.all

The 'all' constant for namespaces is intended for direct import from pykube.

This quickstart demonstrates how to initialize the `pykube-ng` client using environment or local kubeconfig, and then list all Kubernetes pods and retrieve a specific deployment.

import pykube # KubeConfig.from_env() attempts to load config from in-cluster service account or ~/.kube/config config = pykube.KubeConfig.from_env() api = pykube.HTTPClient(config) # List all pods in all namespaces pods = pykube.Pod.objects(api, namespace=pykube.all) print(f"Found {len(list(pods))} pods across all namespaces:") for pod in pods: print(f" {pod.namespace}/{pod.name} (Status: {pod.obj['status']['phase']})") # Get a specific deployment (replace 'my-deployment' and 'default' with actual values) try: deployment = pykube.Deployment.objects(api).get(name="my-deployment", namespace="default") print(f"\nFound deployment: {deployment.name} in namespace {deployment.namespace}") except pykube.exceptions.ObjectDoesNotExist: print("\nDeployment 'my-deployment' not found in 'default' namespace.")

Debug

Known issues

breakingPython 2.7 compatibility was removed in version 0.17 when the project was forked to `pykube-ng`. Users migrating from `kelproject/pykube` must use Python 3.6+.

fix

Ensure your project uses Python 3.6 or newer.

affects: <=0.17

gotchaThe `HTTPClient` object is explicit and needs to be passed to object queries and methods. There is no implicit global configuration like in some other Kubernetes clients.

fix

Always initialize `api = pykube.HTTPClient(config)` and pass `api` to object methods (e.g., `Pod.objects(api)`).

affects: All versions

gotchaWatch calls (e.g., `object.watch()`) terminate after a connection is lost (e.g., due to network issues or API server restarts). `pykube-ng` does not include internal reconnection logic or an automatic `while True` loop.

fix

Implement explicit retry and reconnection logic around watch loops in your application code.

affects: All versions

gotchaThe `APIObject.update()` method can fail if the resource was modified concurrently between being loaded and being updated, leading to a conflict. This is a common pattern in Kubernetes for optimistic concurrency.

fix

Wrap `update()` calls in a retry loop (e.g., with exponential backoff) to handle conflicts gracefully.

affects: All versions

Errors

Common errors & fixes

AttributeError: module 'pykube' has no attribute 'KubeConfig'

This error typically occurs when an older, unmaintained 'pykube' package is implicitly referenced or present in the environment instead of 'pykube-ng', or a local file named 'pykube.py' shadows the installed library.

fix

Ensure 'pykube-ng' is correctly installed and that no conflicting 'pykube' package or local 'pykube.py' file exists. Uninstall the old 'pykube' if present (`pip uninstall pykube`) and make sure 'pykube-ng' is installed (`pip install pykube-ng`). Imports should be 'import pykube' or 'from pykube import KubeConfig'.

FileNotFoundError: [Errno 2] No such file or directory: '~/.kube/config'

The pykube-ng client, when attempting to load Kubernetes configuration from a file, cannot find the specified kubeconfig file, often because it's not at the default path (~/.kube/config), the path is incorrect, or the process lacks necessary read permissions. This is particularly common in containerized environments.

fix

For local development, verify that '~/.kube/config' exists and is readable by the Python process. For in-cluster usage, use 'pykube.KubeConfig.from_service_account()' for service account token authentication. Alternatively, 'pykube.KubeConfig.from_env()' attempts both in-cluster and local config loading. If using a custom path, specify it directly: 'pykube.KubeConfig.from_file('/path/to/your/kubeconfig')'.

pykube.exceptions.HTTPError: 403 Forbidden

This error indicates an authorization failure; the Kubernetes user or service account configured for pykube-ng lacks the necessary Role-Based Access Control (RBAC) permissions to perform the requested API operation (e.g., listing pods in a specific namespace).

fix

Grant the appropriate RBAC permissions to the user or service account. This involves creating or modifying a Kubernetes Role (for namespace-specific permissions) or ClusterRole (for cluster-wide permissions) and binding it to the user/service account via a RoleBinding or ClusterRoleBinding with the required verbs (e.g., 'get', 'list', 'watch') for the resource.

ModuleNotFoundError: No module named 'pykube'

Although the PyPI package is 'pykube-ng', developers might incorrectly assume the module name for import is also 'pykube-ng' or forget to install the package altogether. The actual module name to import is 'pykube'.

fix

Ensure the library is installed using `pip install pykube-ng`. Then, use the correct import statement: `import pykube` or `from pykube import KubeConfig, HTTPClient`.

Upgrade

Version history

23.6.0latest on PyPI · released Jun 16, 2023

Audit

Dependencies

requestsrequiredHTTP client for API communication.

jsonpath-ngoptionalUsed for JSONPath queries.

google-authoptionalAuthentication for Google Cloud Kubernetes Engine.

requests-oauthliboptionalOAuth 1.0/2.0 authentication support for requests.

urllib3requiredHTTP client library, often a dependency of requests.

Agent activity

6 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/pykube-ng/ ↗

homepagehttps://codeberg.org/hjacobs/pykube-ng ↗