openshift-cluster-login 1.5.0

Openshift cluster login on command line

OCL (OpenShift Login)

OCL does an automatic login to an OpenShift cluster. It fetches cluster information from app-interface and performs a login via Red Hat SSO.

Installation

You can install this tool from PyPI with pip:

python3 -m pip install openshift-cluster-login

or install it with uv:

uv tool install openshift-cluster-login

You can also use uv to run the tool without installing it:

uvx openshift-cluster-login

Usage

Interactive login

ocl

This spawns a new shell with the following environment variables set:

• KUBECONFIG - path to kubeconfig file
• OCL_CLUSTER_NAME - cluster name
• OCL_CLUSTER_CONSOLE - url to cluster console

kubectl exec credential plugin

OCL can act as a kubectl exec credential plugin, allowing kubectl to transparently fetch and refresh credentials without a separate login step.

One-time setup:

ocl --import-cluster <cluster>

This adds the cluster to ~/.kube/config and creates a shared ocl user entry (if not already present) that all imported contexts reference. After that, any kubectl command against the cluster works directly — OCL handles authentication in the background.

To import all clusters at once:

ocl --import-clusters

Use --overwrite to update existing entries.

How it works:

kubectl calls ocl --get-token whenever it needs credentials. OCL reads the cluster's server URL from the KUBERNETES_EXEC_INFO environment variable that kubectl sets, looks up the matching cluster, checks its token cache, validates via oc whoami if needed, re-authenticates if expired, and returns an ExecCredential JSON. Tokens are cached and revalidated at most once every 5 minutes to avoid per-command overhead.

Because all imported contexts share a single ocl user entry, running ocl --import-clusters is a true one-time setup — no per-cluster credential configuration required.

Features

OCL currently provides the following features (get help with --help):

• OpenShift console login (oc login) via GitHub or Red Hat authentication
• kubectl exec credential plugin (--get-token, --import-cluster, --import-clusters)
• Get cluster and namespace information from app-interface or user-defined (OCL_USER_CLUSTERS)
• Open the OpenShift console in the browser (--open-in-browser)
• Star your most often used namespaces Ctrl+S in the UI
• Shell completion (--install-completion, --show-completion)
• Credentials via environment variables or shell command (e.g., 1password CLI)
• Cache App-Interface queries (via GraphQL) for one week

Environment Variables

Variable Name	Description	Default
OCL_APP_INTERFACE_URL OCL_APP_INTERFACE_URL_COMMAND	App-Interface URL
OCL_APP_INT_TOKEN OCL_APP_INT_TOKEN_COMMAND	App-Interface authentication token [optional]
OCL_USER_CLUSTERS OCL_USER_CLUSTERS_COMMAND	User defined clusters as json format (e.g. [{"name": "local-kind", "serverUrl": "https://localhost:6443", "consoleUrl": "not available}])	"[]"
OCL_CACHE_TIMEOUT_MINUTES	GraphQL cache timeout in minutes	1 hour
OCL_HISTORY	Enable/Disable the usage of the last selected namespace	enabled
OCL_CSS_PATH	Path to custom Textual CSS file

You can either set a variable, e.g. export OCL_GITHUB_USERNAME="[e-mail]" or retrieve it via a command, e.g. export OCL_GITHUB_USERNAME_COMMAND="op read op://Private/Github/username". If a variable is not set but needed, OCL will ask for it interactively.

App-Interface

OCL retrieves the cluster information from app-interface via GraphQL (OCL_APP_INTERFACE_URL) and caches them in your user cache directory (on MacOS, e.g., ~/Library/Caches/ocl/gql_cache/). Remove this directory to force a refresh.

Limitations

• Kerberos authentication only
• Works only with a Red Hat associate account

Development