Install & Compatibility
Where this runs
tested against v0.13.2 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.901s · 59.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.0s · import 1.736s · 61MB
60MB installed
● package 60MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DynamicClient
✓ from openshift.dynamic import DynamicClient
This is the modern, recommended approach for generic interaction with OpenShift and Kubernetes resources.
config
✓ from kubernetes import config
Used for loading Kubernetes/OpenShift configuration, such as from kubeconfig files or in-cluster settings.
client
✓ from kubernetes import client
Needed for instantiating the core Kubernetes API client which the DynamicClient wraps.
This quickstart demonstrates how to connect to an OpenShift or Kubernetes cluster using `kubeconfig` or in-cluster configuration and then use the `openshift.dynamic.DynamicClient` to list projects (or namespaces as a fallback). It's crucial to have a valid `kubeconfig` file (e.g., at `~/.kube/config`) or appropriate in-cluster permissions for the client to authenticate successfully.
import os
from kubernetes import config
from openshift.dynamic import DynamicClient
try:
# Attempt to load kubeconfig from default locations or KUBECONFIG env var
kube_config_path = os.environ.get('KUBECONFIG', os.path.expanduser('~/.kube/config'))
k8s_client = config.new_client_from_config(config_file=kube_config_path)
except Exception as e:
print(f"Could not load kubeconfig: {e}. Attempting in-cluster config...")
try:
# Fallback to in-cluster configuration if outside kubeconfig fails
k8s_client = config.load_incluster_config()
except config.ConfigException as e_incluster:
print(f"Could not load in-cluster config: {e_incluster}. Please ensure KUBECONFIG is set or run inside a cluster.")
exit(1)
# Instantiate the DynamicClient with the Kubernetes client
dyn_client = DynamicClient(k8s_client)
# Example: List all Projects
# In OpenShift, 'Project' is a custom resource that typically corresponds to a Kubernetes Namespace.
# You might need 'Project' (OpenShift API) or 'Namespace' (Kubernetes API).
# This example tries for OpenShift's Project if available, otherwise Kubernetes Namespace.
try:
# Try to get the 'Project' resource (OpenShift specific)
projects_resource = dyn_client.resources.get(api_version='project.openshift.io/v1', kind='Project')
print("Listing OpenShift Projects:")
for project in projects_resource.get().items:
print(f" - {project.metadata.name}")
except Exception as e:
print(f"Could not list OpenShift Projects (resource 'project.openshift.io/v1, Project' might not exist or be accessible): {e}")
try:
# Fallback to listing Kubernetes Namespaces
namespaces_resource = dyn_client.resources.get(api_version='v1', kind='Namespace')
print("Listing Kubernetes Namespaces instead:")
for namespace in namespaces_resource.get().items:
print(f" - {namespace.metadata.name}")
except Exception as e_ns:
print(f"Could not list Kubernetes Namespaces either: {e_ns}")
Debug
Known issues
breakingOlder versions of the library used a deprecated client approach with swagger-generated models. The current recommended approach, reflected in recent versions, is to use the dynamic client for generic interaction. Users upgrading from very old versions should refactor.fixMigrate to using `openshift.dynamic.DynamicClient` for all resource interactions.
affects: <= 0.10.x (pre-dynamic client focus)
gotchaAuthentication with username/password has historically had issues and is generally less reliable than token-based authentication. It is highly recommended to use token-based authentication, typically through a service account token or by ensuring a valid kubeconfig file is present.fixUtilize service account tokens or `kubeconfig` files (`~/.kube/config` or `KUBECONFIG` environment variable) for authentication. Avoid direct username/password in code where possible.
affects: All versions
breakingVersion 0.13.0 was released with broken requirements, leading to installation issues. This was fixed in version 0.13.1. [changelog]fixEnsure you are using `openshift==0.13.1` or a later version.
affects: 0.13.0
gotchaVersion 0.13.0 removed the upper limit on the `kubernetes` dependency. While this keeps up with Kubernetes API updates, it means that a very new `kubernetes` client library with potential breaking changes could be pulled in, causing unexpected compatibility issues with `openshift`. [changelog]fixRegularly test your application against new `openshift` and `kubernetes` client versions. Consider pinning the `kubernetes` dependency in your `requirements.txt` to a specific major/minor version that is known to be compatible with your `openshift` version.
affects: 0.13.0 and later
gotchaThe PyPI project is currently classified as 'Development Status :: 3 - Alpha'. While actively maintained, this status might imply potential for API instability or significant changes in future releases.fixBe aware that APIs might evolve, and review changelogs carefully when upgrading. Pin to specific versions to manage stability.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'openshift'
The 'openshift' Python package is not installed in the active Python environment or the Python interpreter cannot find it.
fixEnsure the library is installed using pip: `pip install openshift`
ModuleNotFoundError: No module named 'openshift.dynamic'
The 'openshift.dynamic' submodule, which is crucial for the dynamic client, cannot be found. This often happens if the 'openshift' package is not fully or correctly installed, or if there's a version mismatch where the module structure has changed.
fixEnsure the 'openshift' library is correctly installed and updated: `pip install --upgrade openshift`.
ModuleNotFoundError: No module named 'openshift.helper.userpassauth'
This specific helper module for user/password authentication might be deprecated or has been moved/refactored in newer versions of the `openshift-restclient-python` library. The recommended approach for authentication now typically involves using `kubernetes.config` or setting `api_key` for token-based authentication directly.
fixInstead of `openshift.helper.userpassauth`, use `kubernetes.config` for loading kubeconfig or directly configure `kubernetes.client.Configuration` for token-based authentication. Example for token auth: `from kubernetes import client, config; kube_config = client.Configuration(); kube_config.api_key_prefix['authorization'] = 'Bearer'; kube_config.api_key['authorization'] = 'YOUR_TOKEN'; kube_config.host = 'YOUR_OPENSHIFT_API_URL'`
This module requires the OpenShift Python client. Try `pip install openshift`. Detail: No module named 'openshift'
This error frequently occurs when using Ansible modules that interact with OpenShift. It indicates that the 'openshift' Python library is not installed or accessible in the specific Python environment used by Ansible, which might differ from the system's default Python.
fixInstall the 'openshift' library for the Python interpreter that Ansible is using. If using a virtual environment, activate it first. For Ansible, you might need to specify the Python interpreter or install it globally for the user running Ansible, e.g., `pip install openshift pyyaml kubernetes` or `sudo pip install openshift`.
kubernetes.client.rest.ApiException: (403) Reason: Forbidden
This is an authorization error from the Kubernetes API, which the OpenShift client uses. It means the authenticated user or service account lacks the necessary permissions to perform the requested operation (e.g., create a resource in a specific namespace) or the authentication token/credentials are invalid.
fixVerify that the user or service account used for authentication has the correct RBAC permissions in OpenShift. Ensure your `kubeconfig` file is correctly configured or that the token/username/password provided to the client is valid and has sufficient privileges. Using token-based authentication is often recommended.
Upgrade
Version history
0.13.2latest on PyPI · released Jul 25, 2023
Audit
Dependencies
kubernetesrequiredThe OpenShift client depends on the Kubernetes Python client, which is automatically installed as part of the setup process.