lightkube-models

Common errors

• ModuleNotFoundError: No module named 'lightkube.models.Pod'

  cause Attempting to import a Kubernetes model directly from the top-level `lightkube.models` package instead of its versioned API group submodule.
  fix Models are organized by Kubernetes API group and version. You need to import from the specific module, e.g., `from lightkube.models.core_v1 import Pod` for a Pod model, or `from lightkube.models.apps_v1 import Deployment` for a Deployment model.

• lightkube.core.exceptions.LoadResourceError: No module named 'lightkube.resources.stable_example_com_v1'

  cause This error occurs when trying to load a Custom Resource Definition (CRD) object from a YAML file or dictionary using `lightkube.codecs.load_all_yaml()` without `lightkube` being aware of that custom resource's schema. `lightkube-models` only includes standard Kubernetes resources.
  fix For Custom Resources, you need to explicitly define a generic resource class using `lightkube.generic_resource.create_namespaced_resource` or `create_global_resource` before attempting to load or interact with instances of that CRD. Alternatively, `lightkube.generic_resource.load_in_cluster_generic_resources()` can load all CRDs from a cluster dynamically.

Warnings

• gotcha The version of `lightkube-models` (first three parts: major.minor.micro) directly corresponds to the Kubernetes API schema version it encapsulates. Mismatching this version with your Kubernetes cluster's version can lead to schema validation errors or missing fields.
  Fix: Install a `lightkube-models` version that aligns with your target Kubernetes cluster API version. For example, for Kubernetes 1.29, use `lightkube-models>=1.29,<1.30`.
• gotcha `lightkube.models` provides pure dataclass representations of Kubernetes schemas. The `lightkube` client (from the `lightkube` library) often expects `lightkube.resources` classes, which are subclasses of models with additional metadata for client operations.
  Fix: When interacting with the `lightkube` client, prefer importing from `lightkube.resources.{group}_{version}` (e.g., `from lightkube.resources.core_v1 import Pod`) rather than `lightkube.models`. If you only need schema definition without client interaction, `lightkube.models` is appropriate.
• breaking Prior to `lightkube-models` version 1.33, resource models did not automatically set `apiVersion` and `kind` during instantiation. These fields had to be manually provided when creating objects.
  Fix: For `lightkube-models` versions older than 1.33, ensure `apiVersion` and `kind` are explicitly set in the model's constructor, or upgrade to a `lightkube-models` version >= 1.33, which sets these automatically during `post_init`.

Install

• pip install lightkube-models Install lightkube-models

Imports

• ObjectMeta
  wrong:

  from lightkube.models import ObjectMeta

  correct:

  from lightkube.models.meta_v1 import ObjectMeta

  Kubernetes models are organized by API group and version (e.g., `meta_v1`, `apps_v1`). Direct imports from `lightkube.models` will result in an `ImportError`.
• PodSpec

  from lightkube.models.core_v1 import PodSpec

  Similar to `ObjectMeta`, specific model components are nested under their respective API group and version modules.

Quickstart

Demonstrates how to import and instantiate basic Kubernetes model objects like `ObjectMeta` and `PodSpec` using their specific API group and version paths.

from lightkube.models.meta_v1 import ObjectMeta
from lightkube.models.core_v1 import PodSpec, Container

# Create a simple ObjectMeta instance
metadata = ObjectMeta(name='my-pod', namespace='default', labels={'app': 'my-app'})
print(f"Created ObjectMeta: {metadata.name} in {metadata.namespace} with labels {metadata.labels}")

# Create a PodSpec
container = Container(name='nginx', image='nginx:latest')
pod_spec = PodSpec(containers=[container])
print(f"Created PodSpec with container: {pod_spec.containers[0].name}")