{"id":11218,"library":"kubernetes-types","title":"Kubernetes TypeScript Types","description":"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.","status":"active","version":"1.30.0","language":"javascript","source_language":"en","source_url":"https://github.com/silverlyra/kubernetes-types","tags":["javascript"],"install":[{"cmd":"npm install kubernetes-types","lang":"bash","label":"npm"},{"cmd":"yarn add kubernetes-types","lang":"bash","label":"yarn"},{"cmd":"pnpm add kubernetes-types","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { Pod } from 'kubernetes-types'","symbol":"Pod","correct":"import { Pod } from 'kubernetes-types/core/v1'"},{"note":"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.","wrong":"const Deployment = require('kubernetes-types/apps/v1')","symbol":"Deployment","correct":"import { Deployment } from 'kubernetes-types/apps/v1'"},{"note":"Ensure you are importing common types like `ObjectMeta` from their correct API group and version ('meta/v1'), not a different group like 'core/v1'.","wrong":"import type { ObjectMeta } from 'kubernetes-types/core/v1'","symbol":"ObjectMeta","correct":"import { ObjectMeta } from 'kubernetes-types/meta/v1'"}],"quickstart":{"code":"import { Pod } from 'kubernetes-types/core/v1'\nimport { ObjectMeta } from 'kubernetes-types/meta/v1'\nimport { Deployment } from 'kubernetes-types/apps/v1'\n\nconst metadata: ObjectMeta = {\n  name: 'my-app',\n  labels: { app: 'my-app' }\n};\n\nconst myPod: Pod = {\n  apiVersion: 'v1',\n  kind: 'Pod',\n  metadata: {\n    ...metadata,\n    annotations: { 'example.com/description': 'A simple example pod' }\n  },\n  spec: {\n    containers: [\n      {\n        name: 'nginx-container',\n        image: 'nginx:latest',\n        ports: [{ containerPort: 80 }],\n        resources: { \n          requests: { cpu: '100m', memory: '128Mi' },\n          limits: { cpu: '200m', memory: '256Mi' }\n        }\n      }\n    ]\n  }\n};\n\nconst myDeployment: Deployment = {\n  apiVersion: 'apps/v1',\n  kind: 'Deployment',\n  metadata: {\n    ...metadata,\n    name: 'my-app-deployment'\n  },\n  spec: {\n    replicas: 3,\n    selector: { matchLabels: { app: 'my-app' } },\n    template: {\n      metadata: { labels: { app: 'my-app' } },\n      spec: {\n        containers: [\n          {\n            name: 'my-app-container',\n            image: 'my-org/my-app:1.0.0',\n            ports: [{ containerPort: 3000 }],\n            env: [\n              { name: 'NODE_ENV', value: 'production' },\n              { name: 'API_KEY', value: process.env.MY_API_KEY ?? '' }\n            ],\n            resources: {\n              requests: { cpu: '200m', memory: '256Mi' },\n              limits: { cpu: '500m', memory: '512Mi' }\n            }\n          }\n        ]\n      }\n    }\n  }\n};\n\nconsole.log('Defined Pod:', JSON.stringify(myPod, null, 2));\nconsole.log('Defined Deployment:', JSON.stringify(myDeployment, null, 2));","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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`).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use a Kubernetes API field that either doesn't exist in the specified API version or has been renamed/moved.","error":"Property 'someField' does not exist on type 'V1PodSpec'."},{"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`).","cause":"Trying to import a Kubernetes type directly from the root `kubernetes-types` package instead of its specific API group and version subpath.","error":"Module 'kubernetes-types' has no exported member 'SomeType'."},{"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`.","cause":"An incorrect or non-existent import path for a Kubernetes type.","error":"Cannot find module 'kubernetes-types/some/wrong/path' or its corresponding type declarations."}],"ecosystem":"npm"}