Registry / type-stubs / kubernetes-types

kubernetes-types

library1.30.0jsnpmunverified

The `kubernetes-types` package provides comprehensive TypeScript definitions for Kubernetes API resources. It generates these definitions directly from the official Kubernetes OpenAPI specifications, ensuring accuracy and up-to-date type information. The current stable version is 1.30.0, aligning with Kubernetes API version 1.30.x. This package adheres to a strict versioning policy: its major and minor versions directly correspond to the target Kubernetes API version, while the patch version is reserved for updates to the generated types themselves. This approach ensures developers can reliably match their type definitions to their Kubernetes cluster's API version, preventing common runtime errors related to schema mismatches. It is a critical tool for building type-safe Kubernetes clients, controllers, and automation scripts in TypeScript, distinguishing itself by its direct generation from the official OpenAPI specs and strict version adherence rather than manual maintenance.

type-stubs

npm install kubernetes-types

github ↗package ↗

INSTALL

IMPORT

SIG · KUBERNETES-TYPES

kubernetes-types

type-stubsjavascriptv1.30.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Pod

✓ import { Pod } from 'kubernetes-types/core/v1'

✗ import { Pod } from 'kubernetes-types'

Kubernetes API types are imported from specific paths matching their API group and version (e.g., 'core/v1'). Do not import from the root package name.

Deployment

✓ import { Deployment } from 'kubernetes-types/apps/v1'

✗ const Deployment = require('kubernetes-types/apps/v1')

This library is TypeScript-first and designed for ES Modules. While CommonJS `require` might work via transpilation, direct ESM `import` is the idiomatic and recommended approach.

ObjectMeta

✓ import { ObjectMeta } from 'kubernetes-types/meta/v1'

✗ import type { ObjectMeta } from 'kubernetes-types/core/v1'

Ensure you are importing common types like `ObjectMeta` from their correct API group and version ('meta/v1'), not a different group like 'core/v1'.

This quickstart demonstrates how to import and define basic Kubernetes Pod and Deployment resources using the provided TypeScript types, including common metadata and container specifications, and environment variables.

import { Pod } from 'kubernetes-types/core/v1' import { ObjectMeta } from 'kubernetes-types/meta/v1' import { Deployment } from 'kubernetes-types/apps/v1' const metadata: ObjectMeta = { name: 'my-app', labels: { app: 'my-app' } }; const myPod: Pod = { apiVersion: 'v1', kind: 'Pod', metadata: { ...metadata, annotations: { 'example.com/description': 'A simple example pod' } }, spec: { containers: [ { name: 'nginx-container', image: 'nginx:latest', ports: [{ containerPort: 80 }], resources: { requests: { cpu: '100m', memory: '128Mi' }, limits: { cpu: '200m', memory: '256Mi' } } } ] } }; const myDeployment: Deployment = { apiVersion: 'apps/v1', kind: 'Deployment', metadata: { ...metadata, name: 'my-app-deployment' }, spec: { replicas: 3, selector: { matchLabels: { app: 'my-app' } }, template: { metadata: { labels: { app: 'my-app' } }, spec: { containers: [ { name: 'my-app-container', image: 'my-org/my-app:1.0.0', ports: [{ containerPort: 3000 }], env: [ { name: 'NODE_ENV', value: 'production' }, { name: 'API_KEY', value: process.env.MY_API_KEY ?? '' } ], resources: { requests: { cpu: '200m', memory: '256Mi' }, limits: { cpu: '500m', memory: '512Mi' } } } ] } } } }; console.log('Defined Pod:', JSON.stringify(myPod, null, 2)); console.log('Defined Deployment:', JSON.stringify(myDeployment, null, 2));

Debug

Known issues

breakingThe major and minor versions of `kubernetes-types` strictly track the Kubernetes API version. Upgrading to a new major or minor package version (e.g., from `1.29.x` to `1.30.x`) indicates corresponding breaking or feature changes in the underlying Kubernetes API, requiring code review for compatibility.

fix

Always install the `kubernetes-types` version that precisely matches the major and minor version of your target Kubernetes cluster API. For example, for a Kubernetes v1.30 cluster, use `kubernetes-types@1.30.x`. Review Kubernetes API documentation for changes between versions before upgrading.

affects: >=1.0.0

gotchaImporting types for a Kubernetes API version that does not match your cluster's version can lead to subtle runtime issues, even if your TypeScript code compiles. Fields might be missing, deprecated, or have changed types, causing unexpected behavior or errors when applying configurations to the cluster.

fix

Verify your cluster's Kubernetes version (`kubectl version`) and align your `kubernetes-types` package version accordingly. Use a strict version specifier (e.g., `"kubernetes-types": "~1.30.0"` or `"^1.30.0"`) to prevent unintended minor version upgrades that could introduce API mismatches.

affects: >=1.0.0

gotchaDirectly importing from the root `kubernetes-types` package (e.g., `import { Pod } from 'kubernetes-types'`) will likely result in a TypeScript error or incomplete definitions. All Kubernetes API types are organized into deep import paths based on their API group and version (e.g., `kubernetes-types/core/v1`).

fix

Always use specific deep imports for each Kubernetes resource, such as `import { Pod } from 'kubernetes-types/core/v1'` or `import { Deployment } from 'kubernetes-types/apps/v1'`. Consult the Kubernetes API reference or the package's documentation to determine the correct import path for each type.

affects: >=1.0.0

Errors

Common errors & fixes

Property 'someField' does not exist on type 'V1PodSpec'.

Attempting to use a Kubernetes API field that either doesn't exist in the specified API version or has been renamed/moved.

fix

Check the Kubernetes API documentation for the specific API version you are targeting. Ensure your `kubernetes-types` version matches your cluster's version. The field might be deprecated, removed, or belong to a different object or API group.

Module 'kubernetes-types' has no exported member 'SomeType'.

Trying to import a Kubernetes type directly from the root `kubernetes-types` package instead of its specific API group and version subpath.

fix

Correct the import path to reflect the Kubernetes API group and version of the desired type. For example, change `import { SomeType } from 'kubernetes-types'` to `import { SomeType } from 'kubernetes-types/<api-group>/<api-version>'` (e.g., `kubernetes-types/core/v1` for `Pod`).

Cannot find module 'kubernetes-types/some/wrong/path' or its corresponding type declarations.

An incorrect or non-existent import path for a Kubernetes type.

fix

Verify the exact API group and version path. Kubernetes resources are structured under `/apis/<group>/<version>` or `/api/<version>` for core resources. Ensure the path in your import statement matches this structure precisely, e.g., `kubernetes-types/apps/v1` for `Deployment` or `kubernetes-types/meta/v1` for `ObjectMeta`.

Upgrade

Version history

1.30.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

34 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/silverlyra/kubernetes-types ↗

packagehttps://www.npmjs.com/package/kubernetes-types ↗