OpenShift REST Client for Node.js

Common errors

• TypeError: client.apis['project.openshift.io'].v1.projects.get is not a function

  cause Incorrect API path traversal or a typo in the API group, version, or resource name. The client builds the API structure dynamically based on the OpenShift API schema.
  fix Double-check the OpenShift API documentation for the exact path and method. Ensure the API version (e.g., `v1`) and resource names (e.g., `projects`) are correct and in the correct order.

• Error: read ECONNRESET

  cause This often indicates a network connection issue, an incorrect cluster URL, or a problem with TLS/SSL verification (e.g., self-signed certificate without `rejectUnauthorized: false`).
  fix Verify your OpenShift cluster URL and network connectivity. If using self-signed certificates, ensure `rejectUnauthorized: false` is set in your client configuration. Also check for proxy issues.

• Error: The client only supports Node.js versions 20, 22, 24

  cause The application is running on an unsupported Node.js version, as indicated by the package's `engines` field and recent breaking changes.
  fix Upgrade your Node.js runtime to one of the supported versions (20, 22, or 24) using a Node.js version manager like `nvm` or `volta`.

Warnings

• breaking Version 10.0.0 removed support for Node.js 18. Ensure your environment uses Node.js 20, 22, or 24.
  Fix: Upgrade your Node.js runtime to version 20 or higher. Refer to the package's `engines` field for exact supported versions.
• breaking Version 9.0.0 removed support for Node.js 16. Projects must be on Node.js 18 or newer.
  Fix: Upgrade your Node.js runtime to version 18 or higher.
• breaking Version 8.0.0 removed support for Node.js 14. Projects must be on Node.js 16 or newer.
  Fix: Upgrade your Node.js runtime to version 16 or higher.
• breaking Version 7.1.0 replaced the underlying `request` library with `undici` for HTTP operations. This may affect custom HTTP agents, proxy configurations, or specific `request` options no longer supported or handled differently by `undici`.
  Fix: Review any custom HTTP client configurations or options previously passed to `request`. Adapt them to `undici`'s API or the `kubernetes-client`'s options for underlying HTTP client configuration.
• gotcha The `strictSSL` option was deprecated and replaced with `rejectUnauthorized` in v8.0.3. Using `strictSSL` might lead to unexpected behavior or be ignored.
  Fix: Replace `strictSSL: false` with `rejectUnauthorized: false` in your client configuration when dealing with self-signed certificates or untrusted CAs.

Install

• npm install openshift-rest-client npm
• yarn add openshift-rest-client yarn
• pnpm add openshift-rest-client pnpm

Imports

• OpenshiftClient
  wrong:

  const OpenshiftClient = require('openshift-rest-client');

  correct:

  import { OpenshiftClient } from 'openshift-rest-client';

  The primary client factory. While the README shows CommonJS `require('pkg').OpenshiftClient`, modern Node.js environments (v10+) support named ESM imports for CJS modules. Avoid `require('pkg')` if you intend to get the factory directly.
• config
  wrong:

  const configModule = require('openshift-rest-client'); const specificConfig = configModule.config;

  correct:

  import { config } from 'openshift-rest-client';

  A utility export for advanced configuration options, leveraging `kubernetes-client`'s config module. Direct named import is preferred in ESM.
• OpenShiftClient

  import type { OpenShiftClient } from 'openshift-rest-client';

  Type definition for the instantiated OpenShift client object, useful for TypeScript projects.

Quickstart

This example demonstrates how to initialize the OpenShift client, connect to an API endpoint (projects), and fetch resources. It includes basic error handling and uses environment variables for flexible configuration.

import { OpenshiftClient } from 'openshift-rest-client';
import type { OpenShiftClient } from 'openshift-rest-client';

// Configure the client using environment variables for safety, or a specific kubeconfig path.
// process.env.KUBECONFIG can point to a specific file, or OpenshiftClient() will try default paths.
const kubeConfigPath = process.env.KUBECONFIG || undefined;

async function runClientExample() {
  let client: OpenShiftClient;
  try {
    if (kubeConfigPath) {
      console.log(`Attempting to connect using kubeconfig: ${kubeConfigPath}`);
      client = await OpenshiftClient({ config: kubeConfigPath });
    } else {
      console.log('Attempting to connect using default kubeconfig or in-cluster configuration.');
      client = await OpenshiftClient();
    }

    console.log('Successfully connected to OpenShift API.');

    // Fetch all projects accessible by the authenticated user
    console.log('Fetching all projects...');
    const projectList = await client.apis['project.openshift.io'].v1.projects.get();
    console.log(`Found ${projectList.body.items.length} projects.`);

    // Log details of the first project found, if any
    if (projectList.body.items.length > 0) {
      const firstProjectName = projectList.body.items[0].metadata?.name;
      console.log(`First project name: ${firstProjectName}`);
    }

    // Example: List all build configs in the 'default' namespace
    console.log('Fetching build configs in default namespace...');
    const buildConfigs = await client.apis['build.openshift.io'].v1.namespaces('default').buildconfigs.get();
    console.log(`Found ${buildConfigs.body.items.length} build configs in 'default' namespace.`);

  } catch (error: any) {
    console.error('An error occurred:', error.message);
    if (error.response?.body) {
      console.error('API Error Response:', JSON.stringify(error.response.body, null, 2));
    }
  }
}

runClientExample();