Kubernetes TypeScript Types

Common errors

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

  cause 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'.

  cause 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.

  cause 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`.

Warnings

• breaking The 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.
• gotcha Importing 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.
• gotcha Directly 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.

Install

• npm install kubernetes-types npm
• yarn add kubernetes-types yarn
• pnpm add kubernetes-types pnpm

Imports

• Pod
  wrong:

  import { Pod } from 'kubernetes-types'

  correct:

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

  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
  wrong:

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

  correct:

  import { Deployment } from '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
  wrong:

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

  correct:

  import { ObjectMeta } from 'kubernetes-types/meta/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'.

Quickstart

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));