OpenShift Client for Python

2.0.5 · active · verified Thu Apr 16

The `openshift-client` library provides a Pythonic interface for interacting with OpenShift clusters, built on top of the official Kubernetes Python client. It simplifies common OpenShift operations like managing projects, applications, and resources. The current version is 2.0.5, and it has an active development cadence with parallel maintenance of 1.x and 2.x branches, though 2.x is the primary focus for new features.

Common errors

```
ModuleNotFoundError: No module named 'openshift'
```
cause The package `openshift-client` is installed, but the top-level import for the main client module is `openshift.client`, not just `openshift`.

fix Change your import statement from `import openshift` or `from openshift import OC` to `from openshift.client import OC`.
```
kubernetes.client.rest.ApiException: (404) Not Found
```
cause This typically means the requested resource (e.g., pod, deployment) does not exist in the specified project (namespace), or the project itself does not exist or is inaccessible.

fix Verify the resource name and kind are correct. Ensure the `OC().project()` method has been called with the correct project name, or that the default context points to the desired project.
```
TypeError: can't compare offset-naive and offset-aware datetimes
```
cause You are attempting to compare a timezone-naive datetime object in your code with a timezone-aware datetime object returned by the `openshift-client` library (which became timezone-aware in recent versions).

fix Ensure all datetime objects involved in comparisons or operations are consistently timezone-aware. Use `datetime.now(timezone.utc)` or `datetime.fromtimestamp(ts, tz=timezone.utc)` to create timezone-aware datetimes.

Warnings

breaking Python 2 support has been officially deprecated starting with versions 2.0.5 and 1.0.24. Future releases will drop Python 2 compatibility entirely.
Fix: Migrate your environment and code to Python 3. This library now requires Python >=3.0.
gotcha Starting with versions 2.0.2 and 1.0.22, the library internally uses timezone-aware datetime objects instead of timezone-naive `datetime.utcnow()`. This can lead to `TypeError: can't compare offset-naive and offset-aware datetimes` if your application code mixes naive and aware datetimes when interacting with API objects or their properties.
Fix: Ensure all datetime operations and comparisons in your code are consistently using timezone-aware datetime objects (e.g., using `pytz` or `zoneinfo` modules). Convert naive datetimes to aware ones before use, typically UTC or the timezone of your cluster.
gotcha The `OC` client defaults to using the currently active context in your `kubeconfig` file. If you need to interact with a specific context or a different `kubeconfig` file, you must explicitly specify it.
Fix: To use a specific context, instantiate with `OC.from_context('my-context-name')`. To use a different kubeconfig file, pass the path: `OC(kubeconfig='/path/to/my/kubeconfig')`.

Install

pip install openshift-client Install latest version

Imports

OC
wrong:
```
import openshift
```
correct:
```
from openshift.client import OC
```
The primary client object `OC` is located within the `openshift.client` module, not directly under `openshift`.

Quickstart

This quickstart demonstrates how to initialize the `OC` client, switch to a specific OpenShift project (namespace), and list pods within that project. It assumes a `kubeconfig` file is available in the default location or specified via `KUBECONFIG_PATH` environment variable. It also shows how to retrieve the current project name and handle potential errors.

import os
from openshift.client import OC

# Instantiate the OC client. It automatically uses your default kubeconfig context.
# Or specify a kubeconfig path:
# oc_client = OC(kubeconfig=os.environ.get('KUBECONFIG_PATH', '~/.kube/config'))
oc_client = OC()

# Change to a specific project (namespace)
project_name = os.environ.get('OPENSHIFT_PROJECT', 'default')
oc_client.project(project_name)

print(f"Current project: {oc_client.get_project_name()}")

# List all pods in the current project
try:
    pods = oc_client.selector('pods').objects()
    if pods:
        print(f"Found {len(pods)} pods in project '{project_name}':")
        for pod in pods:
            print(f"  - {pod.metadata.name} (Status: {pod.status.phase})")
    else:
        print(f"No pods found in project '{project_name}'.")
except Exception as e:
    print(f"Error listing pods: {e}")

# Example: Get a specific resource (if it exists)
# try:
#     deployment = oc_client.get('deployment', 'my-app-deployment')
#     print(f"Found deployment: {deployment.metadata.name}")
# except Exception as e:
#     print(f"Deployment not found or error: {e}")

view raw JSON →