JavaScript client for Kubernetes API

This Kubernetes client is designed for use in both browser and Node.js environments. It utilizes the fetch API and is compatible with all modern browsers. For older browsers, the fetch polyfill (github/fetch) should be used.

The k8sclient facilitates communication with the Kubernetes API. It minimizes data interpretation and adds only essential logic. In addition to standard HTTP methods like GET or POST, it implements the WATCH method, which establishes a stream to the server and reacts to events.

All functions return Promise objects and can therefore be processed with a chain of then calls. Potential errors can be caught using the catch method and will be of type K8sApiError.

The client requires a Kubernetes API endpoint and a token. Once both parameters are provided, the following functions are available:

• head
• get
• post
• put
• patch
• delete
• watch

Installation

With npm:

npm install @cloudoperators/juno-k8s-client

With pnpm:

pnpm add @cloudoperators/juno-k8s-client

With yarn:

yarn add @cloudoperators/juno-k8s-client

Configuration Options

When creating a client, you can pass the following options:

| Option | Type | Required | Description | | ------------- | ------- | -------- | --------------------------------------------------- | | apiEndpoint | string | Yes | The Kubernetes API server endpoint | | token | string | Yes | Bearer token for authentication | | ignoreSsl | boolean | No | Ignore SSL certificate verification (Node.js only) | | debug | boolean | No | Enable debug logging for API requests and responses |

SSL Certificate Handling

The ignoreSsl option allows you to bypass SSL certificate verification when connecting to Kubernetes APIs with self-signed or invalid certificates.

⚠️ Security Warning: Only use ignoreSsl: true in development environments or with trusted internal APIs. Never disable SSL verification in production.

Browser Limitation: The ignoreSsl option is only supported in Node.js environments. In browser environments, this option is ignored for security reasons, as browsers handle SSL certificate validation automatically.

import { createClient } from "@cloudoperators/juno-k8s-client"

// For internal/development APIs with self-signed certificates (Node.js only)
const apiClient = createClient({
  apiEndpoint: "https://internal-k8s-api.company.com",
  token: "BEARER-TOKEN",
  ignoreSsl: true, // Only works in Node.js
})

Error Handling

All API errors thrown by this client implement the K8sApiError interface:

interface K8sApiError extends Error {
  apiVersion?: string
  kind?: string
  message: string
  metadata?: Record<string, any>
  reason?: string
  status?: string
  code?: number
  response?: {
    data?: { message?: string }
    status?: number
  }
}

This provides detailed information about Kubernetes API errors, including status codes, reasons, and additional metadata.

Example Code (ES6)

Basic client creation

import { createClient } from "@cloudoperators/juno-k8s-client"

const apiEndpoint = "https://k8s-api.com"
let token = "BEARER-TOKEN"
const apiClient = createClient({ apiEndpoint, token })

Client with SSL ignore (Node.js only)

import { createClient } from "@cloudoperators/juno-k8s-client"

const apiEndpoint = "https://internal-k8s-api.company.com"
let token = "BEARER-TOKEN"
const apiClient = createClient({
  apiEndpoint,
  token,
  ignoreSsl: true, // For internal APIs with self-signed certificates
})

List all pods

In this code snippet, we use the get method to fetch all pods from the Kubernetes API endpoint. The retrieved data is then logged to the console.

import { createClient } from "@cloudoperators/juno-k8s-client"

const apiEndpoint = "https://k8s-api.com"
let token = "BEARER-TOKEN"
const apiClient = createClient({ apiEndpoint, token })

apiClient
  .get("/api/v1/pods")
  .then((data) => console.log(data))
  .catch((error) => {
    console.error("Failed to fetch pods:", error.message)
    console.error("Status:", error.status)
    console.error("Reason:", error.reason)
    console.error("HTTP Code:", error.code)
  })

List pods with query parameters

import { createClient } from "@cloudoperators/juno-k8s-client"

const apiEndpoint = "https://k8s-api.com"
let token = "BEARER-TOKEN"
const apiClient = createClient({ apiEndpoint, token })

// Get pods with label selector
apiClient
  .get("/api/v1/namespaces/default/pods", {
    params: {
      labelSelector: "app=nginx",
      fieldSelector: "status.phase=Running",
    },
  })
  .then((data) => console.log(data))
  .catch((error) => {
    if (error.code === 403) {
      console.error("Access forbidden:", error.reason)
    } else if (error.code === 404) {
      console.error("Namespace not found:", error.message)
    } else {
      console.error("API Error:", error.message)
    }
  })

Create a new namespace

You can use this example to create a new namespace in the Kubernetes cluster.

import { createClient } from "@cloudoperators/juno-k8s-client"

const apiEndpoint = "https://k8s-api.com"
let token = "BEARER-TOKEN"
const apiClient = createClient({ apiEndpoint, token })

apiClient
  .post("/api/v1/namespaces", {
    apiVersion: "v1",
    kind: "Namespace",
    metadata: {
      name: "my_namespace",
      annotations: { displayName: "My Namespace" },
      labels: { app: "my-app" },
    },
  })
  .then((result) => console.log("Namespace created:", result))
  .catch((error) => {
    if (error.reason === "AlreadyExists") {
      console.error("Namespace already exists:", error.message)
    } else if (error.code === 422) {
      console.error("Invalid namespace configuration:", error.message)
    } else {
      console.error("Failed to create namespace:", error.message)
    }
  })

Delete a namespace

The following example demonstrates how to delete a namespace in the Kubernetes cluster.

import { createClient } from "@cloudoperators/juno-k8s-client"

const apiEndpoint = "https://k8s-api.com"
let token = "BEARER-TOKEN"
const apiClient = createClient({ apiEndpoint, token })

apiClient
  .delete("/api/v1/namespaces/my_namespace")
  .then((result) => console.log("Namespace deleted:", result))
  .catch((error) => {
    if (error.code === 404) {
      console.error("Namespace not found:", error.message)
    } else if (error.reason === "Forbidden") {
      console.error("Insufficient permissions to delete namespace:", error.message)
    } else {
      console.error("Failed to delete namespace:", error.message)
      console.error("Error details:", error.metadata)
    }
  })

Per-request SSL override (Node.js only)

You can also override SSL behavior on a per-request basis:

import { createClient } from "@cloudoperators/juno-k8s-client"

const apiEndpoint = "https://k8s-api.com"
let token = "BEARER-TOKEN"

// Client with SSL verification enabled by default
const apiClient = createClient({ apiEndpoint, token, ignoreSsl: false })

// Most requests use SSL verification
apiClient.get("/api/v1/pods")

// But you can override for specific requests (Node.js only)
apiClient
  .get("/api/v1/secrets", {
    ignoreSsl: true, // This request ignores SSL
  })
  .catch((error) => {
    console.error("Failed to fetch secrets:", error.message)
    if (error.response?.status) {
      console.error("HTTP Status:", error.response.status)
    }
  })

Refresh Token

Use this example to refresh the authentication token.

import { createClient } from "@cloudoperators/juno-k8s-client"

const apiEndpoint = "https://k8s-api.com"
let token = "BEARER-TOKEN"
const apiClient = createClient({ apiEndpoint, token })

try {
  apiClient.refreshToken("NEW-TOKEN")
  console.log("Token refreshed successfully")
} catch (error) {
  console.error("Failed to refresh token:", error.message)
}

Watch

The watch call establishes a persistent connection to the Kubernetes API server and listens for changes to the specified resource. In this example, we're watching for changes to pods ("/api/v1/pods").

The watch call should be explicitly started using podsWatch.start() to begin listening for changes, and it can be cancelled using podsWatch.cancel() when it's no longer needed.

import { createClient } from "@cloudoperators/juno-k8s-client"

const apiEndpoint = "https://k8s-api.com"
let token = "BEARER-TOKEN"
const apiClient = createClient({ apiEndpoint, token })

const dispatch = (action) => console.log(action)

// Initialize the watch call
const podsWatch = apiClient
  .watch("/api/v1/pods")
  .on(apiClient.WATCH_ERROR, (error) => {
    console.error("Watch error occurred:", error.message)
    console.error("Error reason:", error.reason)
    console.error("Error code:", error.code)

    // Handle specific error cases
    if (error.code === 401) {
      console.error("Authentication failed - token may be expired")
    } else if (error.code === 403) {
      console.error("Access forbidden - insufficient permissions")
    } else if (error.reason === "Expired") {
      console.error("Watch session expired - consider restarting")
    }
  })
  .on(apiClient.WATCH_ADDED, (items) => dispatch({ type: "RECEIVE_ITEMS", items }))
  .on(apiClient.WATCH_MODIFIED, (items) => dispatch({ type: "UPDATE_ITEMS", items }))
  .on(apiClient.WATCH_DELETED, (items) => dispatch({ type: "DELETE_ITEMS", items }))

// Start the watch call to begin listening for changes
podsWatch.start()

// Optionally, set a timeout to cancel the watch call after a certain period
setTimeout(podsWatch.cancel, 5 * 60 * 1000) // 5 minutes

Watch with SSL ignore (Node.js only)

import { createClient } from "@cloudoperators/juno-k8s-client"

const apiEndpoint = "https://internal-k8s-api.company.com"
let token = "BEARER-TOKEN"
const apiClient = createClient({
  apiEndpoint,
  token,
  ignoreSsl: true, // For internal APIs
})

const podsWatch = apiClient
  .watch("/api/v1/pods", {
    params: { watch: "true" },
    ignoreSsl: true, // Can also be set per-request
  })
  .on(apiClient.WATCH_ERROR, (error) => {
    console.error("Watch connection failed:", error.message)
    if (error.response?.data?.message) {
      console.error("Server message:", error.response.data.message)
    }
  })
  .on(apiClient.WATCH_ADDED, (items) => console.log("Added:", items))

podsWatch.start()

Common Use Cases

Internal Kubernetes Clusters

For internal clusters with self-signed certificates (Node.js environments):

const apiClient = createClient({
  apiEndpoint: "https://rancher.internal.company.com/k8s/clusters/c-12345",
  token: process.env.K8S_TOKEN,
  ignoreSsl: true, // Safe for internal networks
})

// Example with error handling for internal clusters
apiClient
  .get("/api/v1/nodes")
  .then((nodes) => console.log("Cluster nodes:", nodes))
  .catch((error) => {
    console.error("Failed to connect to internal cluster:", error.message)
    if (error.code === 0 || error.message.includes("ECONNREFUSED")) {
      console.error("Network connectivity issue - check VPN or firewall")
    }
  })

Development Environment

const apiClient = createClient({
  apiEndpoint: "https://localhost:6443",
  token: "dev-token",
  ignoreSsl: process.env.NODE_ENV === "development", // Only in development
})

// Development-specific error handling
apiClient.get("/api/v1/namespaces").catch((error) => {
  if (process.env.NODE_ENV === "development") {
    console.warn("Development API error:", error.message)
    console.warn("This might be expected in dev environment")
  } else {
    console.error("Production API error:", error)
  }
})

Production Environment

const apiClient = createClient({
  apiEndpoint: "https://prod-k8s-api.company.com",
  token: process.env.K8S_TOKEN,
  // ignoreSsl should not be used in production
})

// Production error handling with monitoring
apiClient.get("/api/v1/pods").catch((error) => {
  // Log detailed error information for monitoring
  console.error("Production API Error:", {
    message: error.message,
    status: error.status,
    reason: error.reason,
    code: error.code,
    apiVersion: error.apiVersion,
    kind: error.kind,
    timestamp: new Date().toISOString(),
  })

  // Send to monitoring service
  // monitoringService.reportError(error)
})

Environment Support

Browser Environment

• ✅ Full HTTP methods support (GET, POST, PUT, PATCH, DELETE, HEAD)
• ✅ Watch functionality
• ✅ Token refresh
• ✅ Complete error handling with K8sApiError
• ❌ ignoreSsl option (ignored for security reasons)

Node.js Environment

• ✅ Full HTTP methods support
• ✅ Watch functionality
• ✅ Token refresh
• ✅ Complete error handling with K8sApiError
• ✅ ignoreSsl option with HTTPS agent support

Development

All dependencies of this project are expressed in its package.json file. Before you start developing, ensure that you have NPM installed, then run:

pnpm install
pnpm test
pnpm build

Contributing

We welcome contributions from the community. Please follow our contribution guidelines to contribute to this project.

License

Licensed under the Apache License.