kr8s.objects¶

Objects to represent Kubernetes resources.

This module provides classes that represent Kubernetes resources. These classes are used to interact with resources in the Kubernetes API server.

Classes¶

`APIObject`	Base class for Kubernetes objects.
`Binding`	Base class for Kubernetes objects.
`ComponentStatus`	Base class for Kubernetes objects.
`ConfigMap`	Base class for Kubernetes objects.
`Endpoints`	Base class for Kubernetes objects.
`Event`	Base class for Kubernetes objects.
`LimitRange`	Base class for Kubernetes objects.
`Namespace`	Base class for Kubernetes objects.
`Node`	Base class for Kubernetes objects.
`PersistentVolume`	Base class for Kubernetes objects.
`PersistentVolumeClaim`	Base class for Kubernetes objects.
`Pod`	Base class for Kubernetes objects.
`PodTemplate`	Base class for Kubernetes objects.
`ReplicationController`	Base class for Kubernetes objects.
`ResourceQuota`	Base class for Kubernetes objects.
`Secret`	Base class for Kubernetes objects.
`ServiceAccount`	Base class for Kubernetes objects.
`Service`	Base class for Kubernetes objects.
`ControllerRevision`	Base class for Kubernetes objects.
`DaemonSet`	Base class for Kubernetes objects.
`Deployment`	Base class for Kubernetes objects.
`ReplicaSet`	Base class for Kubernetes objects.
`StatefulSet`	Base class for Kubernetes objects.
`HorizontalPodAutoscaler`	Base class for Kubernetes objects.
`CronJob`	Base class for Kubernetes objects.
`Job`	Base class for Kubernetes objects.
`Ingress`	Base class for Kubernetes objects.
`IngressClass`	Base class for Kubernetes objects.
`NetworkPolicy`	Base class for Kubernetes objects.
`PodDisruptionBudget`	Base class for Kubernetes objects.
`ClusterRoleBinding`	Base class for Kubernetes objects.
`ClusterRole`	Base class for Kubernetes objects.
`RoleBinding`	Base class for Kubernetes objects.
`Role`	Base class for Kubernetes objects.
`CustomResourceDefinition`	Base class for Kubernetes objects.
`Table`	Base class for Kubernetes objects.
`IPAddress`	Base class for Kubernetes objects.
`ServiceCIDR`	Base class for Kubernetes objects.

Functions¶

`new_class`(→ type[APIObject])	Create a new APIObject subclass.
`object_from_name_type`(→ APIObject)	Create an APIObject from a Kubernetes resource name.
`objects_from_files`(→ list[APIObject])	Create APIObjects from Kubernetes resource files.
`get_class`(→ type[APIObject])	Get an APIObject subclass by kind and version.
`object_from_spec`(→ APIObject)	Create an APIObject from a Kubernetes resource spec.

Module Contents¶

class kr8s.objects.APIObject(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

As of the current Kubertenetes release when this function was written (1.29) kubectl doesn’t support multiple conditions. There is a PR to implement this but it hasn’t been merged yet https://github.com/kubernetes/kubernetes/pull/119205.

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.Binding(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.Binding

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.ComponentStatus(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.ComponentStatus

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.ConfigMap(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.ConfigMap

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

property data: box.Box¶: Data of the ConfigMap.

class kr8s.objects.Endpoints(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.Endpoints

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.Event(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.Event

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.LimitRange(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.LimitRange

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.Namespace(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.Namespace

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.Node(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.Node

Base class for Kubernetes objects.

cordon()¶

Cordon the node.

This will mark the node as unschedulable.

uncordon()¶

Uncordon the node.

This will mark the node as schedulable.

taint(key, value, *, effect)¶: Taint a node.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

property unschedulable¶

property taints: box.Box¶: Labels of the Kubernetes resource.

class kr8s.objects.PersistentVolume(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.PersistentVolume

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.PersistentVolumeClaim(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.PersistentVolumeClaim

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.Pod(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.Pod

Base class for Kubernetes objects.

ready() → bool¶: Check if the pod is ready.

logs(container=None, pretty=None, previous=False, since_seconds=None, since_time=None, timestamps=False, tail_lines=None, limit_bytes=None, follow=False, timeout=3600) → collections.abc.Generator[str]¶

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

tolerate(key: str, *, operator: str, effect: str, value: str | None = None, toleration_seconds: int | None = None)¶

Add a toleration to the Pod.

Args:: key (str): Key of the taint to tolerate. operator (str): Toleration operator. effect (str): Specifies the effect of the taint to tolerate. value (str): Value of taint to tolerate. toleration_seconds (str): Toleration seconds.

portforward(remote_port, local_port='match', address='127.0.0.1') → kr8s.portforward.PortForward¶

Port forward a pod.

Returns an instance of kr8s.portforward.PortForward for this Pod.

Args:

remote_port:: The port on the Pod to forward to.
local_port:: The local port to listen on. Defaults to "match", which will match the remote_port. Set to "auto" or None to find an available high port. Set to an int to specify a specific port.
address:: List of addresses or address to listen on. Defaults to [“127.0.0.1”], will listen only on 127.0.0.1.

Example:

This can be used as a an async context manager or with explicit start/stop methods.

Context manager:

>>> async with pod.portforward(8888) as port:
...     print(f"Forwarding to port {port}")
...     # Do something with port 8888

Explict start/stop:

>>> pf = pod.portforward(8888)
>>> await pf.start()
>>> print(f"Forwarding to port {pf.local_port}")
>>> # Do something with port 8888
>>> await pf.stop()

Explict bind address:

>>> async with pod.PortForward(8888, address=["127.0.0.1", "10.20.0.1"]) as port:
...     print(f"Forwarding to port {port}")
...     # Do something with port 8888 on the Pod, port will be bind to 127.0.0.1 and 10.20.0.1

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

Generate a pod definition.

Args:

name (str): The name of the pod. generate_name (str): Template for generating the name of the pod. namespace (str): The namespace of the pod. image (str): The image to use. annotations (dict): Annotations to add to the pod. command (list): Command to run in the container. env (dict): Environment variables to set in the container. resources (dict): Resources to set in the container. image_pull_policy (str): Image pull policy to use. labels (dict): Labels to add to the pod. ports (list|int): Ports to expose. restart (str): Restart policy to use.

Returns:

A kr8s.objects.Pod object.

Example:

>>> from kr8s.objects import Pod
>>> pod = Pod.gen(name="my-pod", image="my-image")
>>> pod.create()

Create an nginx Pod that exposes port 80. >>> from kr8s.objects import Pod >>> pod = Pod.gen(name=”nginx”, image=”nginx:latest”, ports=[80]) >>> pod.create()

Create an wordpress Pod that exposes port 80. >>> from kr8s.objects import Pod >>> pod = Pod.gen(name=”wordpress”, image=”wordpress:latest”, ports=[{“containerPort”: 80}]) >>> pod.create()

Create a Pod that requires a GPU >>> from kr8s.objects import Pod >>> pod = Pod.gen(name=”cuda-vectoradd”, … image=”nvidia/samples:vectoradd-cuda11.6.0-ubuntu18.04”, … resources={“limits”: {“nvidia.com/gpu”: 1}})

property tolerations: box.Box¶: Tolerations for Pod.

class kr8s.objects.PodTemplate(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.PodTemplate

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.ReplicationController(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.ReplicationController

Base class for Kubernetes objects.

ready()¶: Check if the deployment is ready.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.ResourceQuota(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.ResourceQuota

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.Secret(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.Secret

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

property data: box.Box¶: Data of the Secret.

class kr8s.objects.ServiceAccount(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.ServiceAccount

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.Service(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.Service

Base class for Kubernetes objects.

proxy_http_request(method: str, path: str, port: int | None = None, **kwargs: Any) → httpx.Response¶

Issue a HTTP request with specific HTTP method to proxy of a Service.

Args:

method: HTTP method to use. path: Path to proxy. port: Port to proxy to. If not specified, the first port in the

Service’s spec will be used.

**kwargs: Additional keyword arguments to pass to the API call.

proxy_http_get(path: str, port: int | None = None, **kwargs) → httpx.Response¶

proxy_http_post(path: str, port: int | None = None, **kwargs) → httpx.Response¶

proxy_http_put(path: str, port: int | None = None, **kwargs) → httpx.Response¶

proxy_http_delete(path: str, port: int | None = None, **kwargs) → httpx.Response¶

ready_pods() → list[Pod]¶: Return a list of ready Pods for this Service.

ready()¶: Check if the service is ready.

portforward(remote_port, local_port='match', address='127.0.0.1') → kr8s.portforward.PortForward¶

Port forward a service.

Returns an instance of kr8s.portforward.PortForward for this Service.

Args:

remote_port:: The port on the Pod to forward to.
local_port:: The local port to listen on. Defaults to "match", which will match the remote_port. Set to "auto" or None to find an available high port. Set to an int to specify a specific port.
address:: List of addresses or address to listen on. Defaults to [“127.0.0.1”], will listen only on 127.0.0.1.

Example:

This can be used as a an async context manager or with explicit start/stop methods.

Context manager:

>>> async with service.portforward(8888) as port:
...     print(f"Forwarding to port {port}")
...     # Do something with port 8888

Explict start/stop:

>>> pf = service.portforward(8888)
>>> await pf.start()
>>> print(f"Forwarding to port {pf.local_port}")
>>> # Do something with port 8888
>>> await pf.stop()

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.ControllerRevision(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.ControllerRevision

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.DaemonSet(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.DaemonSet

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.Deployment(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.Deployment

Base class for Kubernetes objects.

pods() → list[Pod]¶: Return a list of Pods for this Deployment.

ready() → bool¶: Check if the deployment is ready.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

ready_pods() → list[Pod]¶: Return a list of Pods for this Deployment.

class kr8s.objects.ReplicaSet(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.ReplicaSet

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.StatefulSet(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.StatefulSet

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.HorizontalPodAutoscaler(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.HorizontalPodAutoscaler

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.CronJob(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.CronJob

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.Job(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.Job

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.Ingress(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.Ingress

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.IngressClass(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.IngressClass

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.NetworkPolicy(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.NetworkPolicy

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.PodDisruptionBudget(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.PodDisruptionBudget

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.ClusterRoleBinding(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.ClusterRoleBinding

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.ClusterRole(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.ClusterRole

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.RoleBinding(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.RoleBinding

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.Role(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.Role

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.CustomResourceDefinition(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.CustomResourceDefinition

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.Table(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.Table

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

property rows: list[dict]¶: Table rows.

property column_definitions: list[dict]¶: Table column definitions.

class kr8s.objects.IPAddress(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.IPAddress

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

class kr8s.objects.ServiceCIDR(resource: kr8s._types.SpecType, namespace: str | None = None, api: kr8s._api.Api | None = None)¶

Bases: kr8s._objects.APIObjectSyncMixin, kr8s._objects.ServiceCIDR

Base class for Kubernetes objects.

classmethod get(name: str | None = None, namespace: str | None = None, api: kr8s._api.Api | None = None, label_selector: str | dict[str, str] | None = None, field_selector: str | dict[str, str] | None = None, timeout: int = 2, **kwargs) → Self¶: Get a Kubernetes resource by name or via selectors.

exists(ensure=False) → bool¶: Check if this object exists in Kubernetes.

create() → None¶: Create this object in Kubernetes.

delete(propagation_policy: str | None = None, grace_period: int | None = None, force: bool = False) → None¶

Delete this object from Kubernetes.

Args:: propagation_policy: The deletion propagation policy. grace_period: The grace period for deletion. force: Force deletion. (Setting to True is equivelaent to setting grace_period to 0)

refresh() → None¶: Refresh this object from Kubernetes.

patch(patch, *, subresource=None, type=None) → None¶: Patch this object in Kubernetes.

scale(replicas=None) → None¶: Scale this object in Kubernetes.

watch() → collections.abc.Generator[tuple[str, Self]]¶: Watch this object in Kubernetes.

wait(conditions: list[str] | str, mode: Literal['any', 'all'] = 'any', timeout: int | float | None = None) → None¶

Wait for conditions to be met.

Args:

conditions: A list of conditions to wait for. mode: Match any condition with “any” or all conditions with “all”. Defaults to “any”. timeout: Timeout in seconds.

Example:

Wait for a Pod to be ready.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait("condition=Ready")

Wait for a Job to either succeed or fail.

>>> from kr8s.objects import Job
>>> job = Job.get("my-jod")
>>> job.wait(["condition=Complete", "condition=Failed"])

Wait for a Pod to be initialized and ready to start containers.

>>> from kr8s.objects import Pod
>>> pod = Pod.get("my-pod")
>>> pod.wait(["condition=Initialized", "condition=PodReadyToStartContainers"], mode="all")

Note:

Given that for is a reserved word anyway we can’t exactly match the kubectl API so we use condition in combination with a mode instead.

annotate(annotations=None, **kwargs) → None¶: Annotate this object in Kubernetes.

label(*labels: dict | str, **kwargs) → None¶

Add labels to this object in Kubernetes.

Labels can be passed as a dictionary or as keyword arguments.

Args:

labels:: A dictionary of labels to set or string to remove.
**kwargs:: Labels to set.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Both of these are equivalent
>>> deployment.label({"app": "my-app"})
>>> deployment.label(app="my-app")

>>> # You can also remove a label by passing it's name with a `-` on the end
>>> deployment.label("app-")

remove_label(*labels: str) → None¶

Remove labels from this object in Kubernetes.

Labels can be passed as a list of strings.

Args:

labels: A list of labels to remove.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> deployment.remove_label("app")

set_owner(owner) → None¶

Set the owner reference of this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

owner: The owner object to set a reference to.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> pod.set_owner(deployment)

adopt(child) → None¶

Adopt this object.

This will set the owner reference of the child object to this object.

See https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/

Args:

child: The child object to adopt.

Example:

>>> from kr8s.objects import Deployment, Pod
>>> deployment = Deployment.get("my-deployment")
>>> pod = Pod.get("my-pod")
>>> deployment.adopt(pod)

classmethod list(**kwargs) → collections.abc.Generator[Self | dict]¶

List objects in Kubernetes.

Args:: api: An optional API object to use. **kwargs: Keyword arguments to pass to kr8s.get().
Returns:: A list of objects or dictionaries (if raw=True).

version: str¶

endpoint: str¶

kind: str¶

plural: str¶

singular: str¶

namespaced: bool = False¶

scalable: bool = False¶

scalable_spec: str = 'replicas'¶

property api¶

property raw: box.Box¶: Raw object returned from the Kubernetes API.

property raw_template: box.Box¶

Template representation of the Kubernetes resource without instance-specific data.

Returns a copy of the raw object with metadata.resourceVersion and status removed. This is useful for creating new resources based on existing ones.

property name: str¶: Name of the Kubernetes resource.

property namespace: str | None¶: Namespace of the Kubernetes resource.

property metadata: box.Box¶: Metadata of the Kubernetes resource.

property spec: box.Box¶: Spec of the Kubernetes resource.

property status: box.Box¶: Status of the Kubernetes resource.

property labels: box.Box¶: Labels of the Kubernetes resource.

property annotations: box.Box¶: Annotations of the Kubernetes resource.

property replicas: int¶: Replicas of the Kubernetes resource.

exec(command: list[str], *, container: str | None = None, stdin: str | BinaryIO | None = None, stdout: BinaryIO | None = None, stderr: BinaryIO | None = None, check: bool = True, capture_output: bool = True, timeout: int | None = None) → kr8s._exec.CompletedExec¶: Execute a command in this object.

keys() → list¶: Return the keys of this object.

to_dict() → dict¶: Return a dictionary representation of this object.

to_yaml() → str¶: Return a YAML representation of this object.

to_lightkube() → Any¶: Return a lightkube representation of this object.

to_pykube(api) → Any¶

Return a pykube representation of this object.

Args:

api: A pykube API object.

Example:

>>> from kr8s.objects import Deployment
>>> deployment = Deployment.get("my-deployment")
>>> # Create a pykube API object
>>> from pykube import HTTPClient
>>> api = HTTPClient()
>>> pykube_deployment = deployment.to_pykube(api)

pprint(use_rich: bool = True, theme: str = 'ansi_dark') → None¶

Pretty print this object to stdout.

Prints the object as YAML (using rich for syntax highlighting if available).

Args:: use_rich: Use rich to pretty print. If rich` is not installed this will be ignored. theme: The ``pygments theme for rich to use. Defaults to “ansi_dark” to use default terminal colors.

classmethod gen(*args, **kwargs)¶

Abstractmethod:

kr8s.objects.new_class(kind: str, version: str | None = None, asyncio: bool = False, namespaced=True, scalable: bool | None = None, scalable_spec: str | None = None, plural: str | None = None) → type[APIObject]¶

Create a new APIObject subclass.

Args:: kind: The Kubernetes resource kind. version: The Kubernetes API version. asyncio: Whether to use asyncio or not. namespaced: Whether the resource is namespaced or not. scalable: Whether the resource is scalable or not. scalable_spec: The name of the field to use for scaling. plural: The plural form of the resource.
Returns:: A new APIObject subclass.

kr8s.objects.object_from_name_type(name: str, namespace: str | None = None, api: kr8s.Api | None = None) → APIObject¶

Create an APIObject from a Kubernetes resource name.

Args:: name: A Kubernetes resource name. namespace: The namespace of the resource. api: An optional API instance to use.
Returns:: A corresponding APIObject subclass instance.
Raises:: ValueError: If the resource kind or API version is not supported.

kr8s.objects.objects_from_files(path: str | pathlib.Path, api: kr8s.Api | None = None, recursive: bool = False) → list[APIObject]¶

Create APIObjects from Kubernetes resource files.

Args:: path: A path to a Kubernetes resource file or directory of resource files. api: An optional API instance to use. recursive: Whether to recursively search for resource files in subdirectories.
Returns:: A list of APIObject subclass instances.
Raises:: ValueError: If the resource kind or API version is not supported.

kr8s.objects.get_class(kind: str, version: str) → type[APIObject]¶

Get an APIObject subclass by kind and version.

Args:: kind: The Kubernetes resource kind. version: The Kubernetes API group/version.
Returns:: An APIObject subclass.
Raises:: KeyError: If no object is registered for the given kind and version.

kr8s.objects.object_from_spec(spec: dict, api: kr8s.Api | None = None, allow_unknown_type: bool = False) → APIObject¶

Create an APIObject from a Kubernetes resource spec.

Args:: spec: A Kubernetes resource spec. api: An optional API instance to use. allow_unknown_type: Whether to allow unknown resource types.
Returns:: A corresponding APIObject subclass instance.
Raises:: ValueError: If the resource kind or API version is not supported.