Core Models¶

Pydantic models for Kubernetes resource specifications.

Base Models¶

KubeModel is the base class for all specification models. Extend it to create custom resource specs:

from k8smith import KubeModel, ResourceBuilder
from pydantic import Field

class MySpec(KubeModel):
    name: str
    namespace: str = "default"
    my_field: str = Field(alias="myField")  # outputs as camelCase

Key features:

Excludes None values from output
Supports Pydantic field aliases for camelCase keys
Provides .to_dict() for nested model serialization

`KubeModel` ¶

Base model for all Kubernetes resources.

Provides common configuration and serialization behavior.

Source code in src/k8smith/core/models.py

class KubeModel(BaseModel):
    """Base model for all Kubernetes resources.

    Provides common configuration and serialization behavior.
    """

    model_config = ConfigDict(populate_by_name=True)

    @model_validator(mode="before")
    @classmethod
    def _warn_unknown_fields(cls, data: Any) -> Any:
        if not isinstance(data, dict):
            return data

        # Collect all known field names and aliases
        known: set[str] = set()
        for field_name, field_info in cls.model_fields.items():
            known.add(field_name)
            if field_info.alias:
                known.add(field_info.alias)

        unknown = set(data.keys()) - known
        if unknown:
            warnings.warn(
                f"{cls.__name__}: unknown field(s) {unknown} — "
                f"these will be silently ignored. "
                f"Valid fields: {sorted(known)}",
                UserWarning,
                stacklevel=2,
            )

        return data

    def to_dict(self) -> dict[str, Any]:
        """Serialize to a dict suitable for Kubernetes YAML.

        Excludes None values and empty collections.
        """
        return _clean_dict(self.model_dump(by_alias=True, exclude_none=True))

`to_dict()` ¶

Serialize to a dict suitable for Kubernetes YAML.

Excludes None values and empty collections.

Source code in src/k8smith/core/models.py

def to_dict(self) -> dict[str, Any]:
    """Serialize to a dict suitable for Kubernetes YAML.

    Excludes None values and empty collections.
    """
    return _clean_dict(self.model_dump(by_alias=True, exclude_none=True))

Resource Specifications¶

Deployment¶

`DeploymentSpec` ¶

Bases: KubeModel

Deployment specification.

Example

DeploymentSpec( ... name="web", ... namespace="production", ... replicas=3, ... template=PodTemplateSpec(...), ... )

Source code in src/k8smith/core/models.py

class DeploymentSpec(KubeModel):
    """Deployment specification.

    Example:
        >>> DeploymentSpec(
        ...     name="web",
        ...     namespace="production",
        ...     replicas=3,
        ...     template=PodTemplateSpec(...),
        ... )
    """

    name: str
    namespace: str
    replicas: int | None = None
    labels: dict[str, str] | None = None
    annotations: dict[str, str] | None = None
    selector: dict[str, str] | None = None
    template: PodTemplateSpec
    strategy: dict | None = None
    min_ready_seconds: int | None = Field(default=None, alias="minReadySeconds")
    revision_history_limit: int | None = Field(default=None, alias="revisionHistoryLimit")
    progress_deadline_seconds: int | None = Field(default=None, alias="progressDeadlineSeconds")
    paused: bool | None = None

StatefulSet¶

`StatefulSetSpec` ¶

Bases: KubeModel

StatefulSet specification.

Example

StatefulSetSpec( ... name="db", ... namespace="production", ... service_name="db-headless", ... template=PodTemplateSpec(...), ... )

Source code in src/k8smith/core/models.py

class StatefulSetSpec(KubeModel):
    """StatefulSet specification.

    Example:
        >>> StatefulSetSpec(
        ...     name="db",
        ...     namespace="production",
        ...     service_name="db-headless",
        ...     template=PodTemplateSpec(...),
        ... )
    """

    name: str
    namespace: str
    replicas: int | None = None
    labels: dict[str, str] | None = None
    annotations: dict[str, str] | None = None
    selector: dict[str, str] | None = None
    template: PodTemplateSpec
    service_name: str = Field(alias="serviceName")
    volume_claim_templates: list[dict] | None = Field(default=None, alias="volumeClaimTemplates")
    pod_management_policy: Literal["OrderedReady", "Parallel"] | None = Field(
        default=None, alias="podManagementPolicy"
    )
    update_strategy: dict | None = Field(default=None, alias="updateStrategy")
    revision_history_limit: int | None = Field(default=None, alias="revisionHistoryLimit")
    min_ready_seconds: int | None = Field(default=None, alias="minReadySeconds")
    persistent_volume_claim_retention_policy: dict | None = Field(
        default=None, alias="persistentVolumeClaimRetentionPolicy"
    )

DaemonSet¶

`DaemonSetSpec` ¶

Bases: KubeModel

DaemonSet specification.

Example

DaemonSetSpec( ... name="node-agent", ... namespace="kube-system", ... template=PodTemplateSpec(...), ... )

Source code in src/k8smith/core/models.py

class DaemonSetSpec(KubeModel):
    """DaemonSet specification.

    Example:
        >>> DaemonSetSpec(
        ...     name="node-agent",
        ...     namespace="kube-system",
        ...     template=PodTemplateSpec(...),
        ... )
    """

    name: str
    namespace: str
    labels: dict[str, str] | None = None
    annotations: dict[str, str] | None = None
    selector: dict[str, str] | None = None
    template: PodTemplateSpec
    update_strategy: dict | None = Field(default=None, alias="updateStrategy")
    min_ready_seconds: int | None = Field(default=None, alias="minReadySeconds")
    revision_history_limit: int | None = Field(default=None, alias="revisionHistoryLimit")

Service¶

`ServiceSpec` ¶

Bases: KubeModel

Service specification.

Example

ServiceSpec( ... name="web", ... namespace="production", ... ports=[ServicePort(port=80, target_port=8080)], ... selector={"app": "web"}, ... )

Source code in src/k8smith/core/models.py

class ServiceSpec(KubeModel):
    """Service specification.

    Example:
        >>> ServiceSpec(
        ...     name="web",
        ...     namespace="production",
        ...     ports=[ServicePort(port=80, target_port=8080)],
        ...     selector={"app": "web"},
        ... )
    """

    name: str
    namespace: str
    labels: dict[str, str] | None = None
    annotations: dict[str, str] | None = None
    selector: dict[str, str] | None = None
    ports: list[ServicePort] | None = None
    type: Literal["ClusterIP", "NodePort", "LoadBalancer", "ExternalName"] | None = None
    cluster_ip: str | None = Field(default=None, alias="clusterIP")
    external_name: str | None = Field(default=None, alias="externalName")
    external_traffic_policy: Literal["Cluster", "Local"] | None = Field(
        default=None, alias="externalTrafficPolicy"
    )
    internal_traffic_policy: Literal["Cluster", "Local"] | None = Field(
        default=None, alias="internalTrafficPolicy"
    )
    session_affinity: Literal["ClientIP", "None"] | None = Field(
        default=None, alias="sessionAffinity"
    )
    load_balancer_ip: str | None = Field(default=None, alias="loadBalancerIP")
    load_balancer_source_ranges: list[str] | None = Field(
        default=None, alias="loadBalancerSourceRanges"
    )

CronJob¶

`CronJobSpec` ¶

Bases: KubeModel

CronJob specification.

Example

CronJobSpec( ... name="backup", ... namespace="production", ... schedule="0 2 * * *", ... job_template=PodTemplateSpec(...), ... )

Source code in src/k8smith/core/models.py

class CronJobSpec(KubeModel):
    """CronJob specification.

    Example:
        >>> CronJobSpec(
        ...     name="backup",
        ...     namespace="production",
        ...     schedule="0 2 * * *",
        ...     job_template=PodTemplateSpec(...),
        ... )
    """

    name: str
    namespace: str
    schedule: str
    labels: dict[str, str] | None = None
    annotations: dict[str, str] | None = None
    job_template: PodTemplateSpec = Field(alias="jobTemplate")
    concurrency_policy: Literal["Allow", "Forbid", "Replace"] | None = Field(
        default=None, alias="concurrencyPolicy"
    )
    successful_jobs_history_limit: int | None = Field(
        default=None, alias="successfulJobsHistoryLimit"
    )
    failed_jobs_history_limit: int | None = Field(default=None, alias="failedJobsHistoryLimit")
    starting_deadline_seconds: int | None = Field(default=None, alias="startingDeadlineSeconds")
    suspend: bool | None = None
    time_zone: str | None = Field(default=None, alias="timeZone")

ConfigMap¶

`ConfigMapSpec` ¶

Bases: KubeModel

ConfigMap specification.

Example

ConfigMapSpec( ... name="app-config", ... namespace="production", ... data={"config.yaml": "key: value"}, ... )

Source code in src/k8smith/core/models.py

class ConfigMapSpec(KubeModel):
    """ConfigMap specification.

    Example:
        >>> ConfigMapSpec(
        ...     name="app-config",
        ...     namespace="production",
        ...     data={"config.yaml": "key: value"},
        ... )
    """

    name: str
    namespace: str
    labels: dict[str, str] | None = None
    annotations: dict[str, str] | None = None
    data: dict[str, str] | None = None
    binary_data: dict[str, str] | None = Field(default=None, alias="binaryData")
    immutable: bool | None = None

Secret¶

`SecretSpec` ¶

Bases: KubeModel

Secret specification.

Example

SecretSpec( ... name="db-credentials", ... namespace="production", ... string_data={"username": "admin", "password": "secret"}, ... )

Source code in src/k8smith/core/models.py

class SecretSpec(KubeModel):
    """Secret specification.

    Example:
        >>> SecretSpec(
        ...     name="db-credentials",
        ...     namespace="production",
        ...     string_data={"username": "admin", "password": "secret"},
        ... )
    """

    name: str
    namespace: str
    labels: dict[str, str] | None = None
    annotations: dict[str, str] | None = None
    data: dict[str, str] | None = None
    string_data: dict[str, str] | None = Field(default=None, alias="stringData")
    type: str | None = None
    immutable: bool | None = None

HPA¶

`HPASpec` ¶

Bases: KubeModel

HorizontalPodAutoscaler specification.

Example

HPASpec( ... name="web-hpa", ... namespace="production", ... scale_target_ref={"apiVersion": "apps/v1", "kind": "Deployment", "name": "web"}, ... min_replicas=2, ... max_replicas=10, ... )

Source code in src/k8smith/core/models.py

class HPASpec(KubeModel):
    """HorizontalPodAutoscaler specification.

    Example:
        >>> HPASpec(
        ...     name="web-hpa",
        ...     namespace="production",
        ...     scale_target_ref={"apiVersion": "apps/v1", "kind": "Deployment", "name": "web"},
        ...     min_replicas=2,
        ...     max_replicas=10,
        ... )
    """

    name: str
    namespace: str
    labels: dict[str, str] | None = None
    annotations: dict[str, str] | None = None
    scale_target_ref: dict = Field(alias="scaleTargetRef")
    min_replicas: int | None = Field(default=None, alias="minReplicas")
    max_replicas: int = Field(alias="maxReplicas")
    metrics: list[dict] | None = None
    behavior: dict | None = None

PDB¶

`PDBSpec` ¶

Bases: KubeModel

PodDisruptionBudget specification.

Example

PDBSpec( ... name="web-pdb", ... namespace="production", ... selector={"app": "web"}, ... min_available=1, ... )

Source code in src/k8smith/core/models.py

class PDBSpec(KubeModel):
    """PodDisruptionBudget specification.

    Example:
        >>> PDBSpec(
        ...     name="web-pdb",
        ...     namespace="production",
        ...     selector={"app": "web"},
        ...     min_available=1,
        ... )
    """

    name: str
    namespace: str
    labels: dict[str, str] | None = None
    annotations: dict[str, str] | None = None
    selector: dict[str, str] | None = None
    min_available: int | str | None = Field(default=None, alias="minAvailable")
    max_unavailable: int | str | None = Field(default=None, alias="maxUnavailable")

ServiceAccount¶

`ServiceAccountSpec` ¶

Bases: KubeModel

ServiceAccount specification.

Example

ServiceAccountSpec(name="app-sa", namespace="production")

Source code in src/k8smith/core/models.py

class ServiceAccountSpec(KubeModel):
    """ServiceAccount specification.

    Example:
        >>> ServiceAccountSpec(name="app-sa", namespace="production")
    """

    name: str
    namespace: str
    labels: dict[str, str] | None = None
    annotations: dict[str, str] | None = None
    automount_service_account_token: bool | None = Field(
        default=None, alias="automountServiceAccountToken"
    )
    image_pull_secrets: list[dict] | None = Field(default=None, alias="imagePullSecrets")

Namespace¶

`NamespaceSpec` ¶

Bases: KubeModel

Namespace specification.

Example

NamespaceSpec(name="production", labels={"env": "prod"})

Source code in src/k8smith/core/models.py

class NamespaceSpec(KubeModel):
    """Namespace specification.

    Example:
        >>> NamespaceSpec(name="production", labels={"env": "prod"})
    """

    name: str
    labels: dict[str, str] | None = None
    annotations: dict[str, str] | None = None

RBAC Models¶

Role¶

`RoleSpec` ¶

Bases: KubeModel

Role specification (namespaced RBAC).

Example

RoleSpec( ... name="pod-reader", ... namespace="production", ... rules=[ ... PolicyRule(api_groups=[""], resources=["pods"], verbs=["get", "list", "watch"]), ... ], ... )

Source code in src/k8smith/core/models.py

class RoleSpec(KubeModel):
    """Role specification (namespaced RBAC).

    Example:
        >>> RoleSpec(
        ...     name="pod-reader",
        ...     namespace="production",
        ...     rules=[
        ...         PolicyRule(api_groups=[""], resources=["pods"], verbs=["get", "list", "watch"]),
        ...     ],
        ... )
    """

    name: str
    namespace: str
    labels: dict[str, str] | None = None
    annotations: dict[str, str] | None = None
    rules: list[PolicyRule] | None = None

ClusterRole¶

`ClusterRoleSpec` ¶

Bases: KubeModel

ClusterRole specification (cluster-wide RBAC).

Example

ClusterRoleSpec( ... name="node-reader", ... rules=[ ... PolicyRule( ... api_groups=[""], ... resources=["nodes"], ... verbs=["get", "list", "watch"], ... ), ... ], ... )

Source code in src/k8smith/core/models.py

class ClusterRoleSpec(KubeModel):
    """ClusterRole specification (cluster-wide RBAC).

    Example:
        >>> ClusterRoleSpec(
        ...     name="node-reader",
        ...     rules=[
        ...         PolicyRule(
        ...             api_groups=[""],
        ...             resources=["nodes"],
        ...             verbs=["get", "list", "watch"],
        ...         ),
        ...     ],
        ... )
    """

    name: str
    labels: dict[str, str] | None = None
    annotations: dict[str, str] | None = None
    rules: list[PolicyRule] | None = None
    aggregation_rule: dict | None = Field(default=None, alias="aggregationRule")

RoleBinding¶

`RoleBindingSpec` ¶

Bases: KubeModel

RoleBinding specification (namespaced binding).

Example

RoleBindingSpec( ... name="read-pods", ... namespace="production", ... subjects=[ ... RoleBindingSubject(kind="ServiceAccount", name="my-sa", namespace="production"), ... ], ... role_ref=RoleRef(kind="Role", name="pod-reader"), ... )

Source code in src/k8smith/core/models.py

class RoleBindingSpec(KubeModel):
    """RoleBinding specification (namespaced binding).

    Example:
        >>> RoleBindingSpec(
        ...     name="read-pods",
        ...     namespace="production",
        ...     subjects=[
        ...         RoleBindingSubject(kind="ServiceAccount", name="my-sa", namespace="production"),
        ...     ],
        ...     role_ref=RoleRef(kind="Role", name="pod-reader"),
        ... )
    """

    name: str
    namespace: str
    labels: dict[str, str] | None = None
    annotations: dict[str, str] | None = None
    subjects: list[RoleBindingSubject] | None = None
    role_ref: RoleRef = Field(alias="roleRef")

ClusterRoleBinding¶

`ClusterRoleBindingSpec` ¶

Bases: KubeModel

ClusterRoleBinding specification (cluster-wide binding).

Example

ClusterRoleBindingSpec( ... name="read-nodes", ... subjects=[ ... RoleBindingSubject( ... kind="ServiceAccount", ... name="monitoring", ... namespace="kube-system", ... ), ... ], ... role_ref=RoleRef(kind="ClusterRole", name="node-reader"), ... )

Source code in src/k8smith/core/models.py

class ClusterRoleBindingSpec(KubeModel):
    """ClusterRoleBinding specification (cluster-wide binding).

    Example:
        >>> ClusterRoleBindingSpec(
        ...     name="read-nodes",
        ...     subjects=[
        ...         RoleBindingSubject(
        ...             kind="ServiceAccount",
        ...             name="monitoring",
        ...             namespace="kube-system",
        ...         ),
        ...     ],
        ...     role_ref=RoleRef(kind="ClusterRole", name="node-reader"),
        ... )
    """

    name: str
    labels: dict[str, str] | None = None
    annotations: dict[str, str] | None = None
    subjects: list[RoleBindingSubject] | None = None
    role_ref: RoleRef = Field(alias="roleRef")

PolicyRule¶

`PolicyRule` ¶

Bases: KubeModel

RBAC policy rule for Role and ClusterRole.

Example

PolicyRule( ... api_groups=[""], ... resources=["pods", "pods/log"], ... verbs=["get", "list", "watch"], ... ) PolicyRule( ... api_groups=["apps"], ... resources=["deployments"], ... verbs=["get", "list", "watch", "create", "update", "patch", "delete"], ... resource_names=["my-deployment"], ... )

Source code in src/k8smith/core/models.py

class PolicyRule(KubeModel):
    """RBAC policy rule for Role and ClusterRole.

    Example:
        >>> PolicyRule(
        ...     api_groups=[""],
        ...     resources=["pods", "pods/log"],
        ...     verbs=["get", "list", "watch"],
        ... )
        >>> PolicyRule(
        ...     api_groups=["apps"],
        ...     resources=["deployments"],
        ...     verbs=["get", "list", "watch", "create", "update", "patch", "delete"],
        ...     resource_names=["my-deployment"],
        ... )
    """

    api_groups: list[str] | None = Field(default=None, alias="apiGroups")
    resources: list[str] | None = None
    resource_names: list[str] | None = Field(default=None, alias="resourceNames")
    verbs: list[str]
    non_resource_urls: list[str] | None = Field(default=None, alias="nonResourceURLs")

RoleRef¶

`RoleRef` ¶

Bases: KubeModel

Reference to a Role or ClusterRole.

Example

RoleRef(kind="Role", name="pod-reader", api_group="rbac.authorization.k8s.io") RoleRef(kind="ClusterRole", name="admin", api_group="rbac.authorization.k8s.io")

Source code in src/k8smith/core/models.py

class RoleRef(KubeModel):
    """Reference to a Role or ClusterRole.

    Example:
        >>> RoleRef(kind="Role", name="pod-reader", api_group="rbac.authorization.k8s.io")
        >>> RoleRef(kind="ClusterRole", name="admin", api_group="rbac.authorization.k8s.io")
    """

    kind: Literal["Role", "ClusterRole"]
    name: str
    api_group: str = Field(default="rbac.authorization.k8s.io", alias="apiGroup")

RoleBindingSubject¶

`RoleBindingSubject` ¶

Bases: KubeModel

Subject for RoleBinding and ClusterRoleBinding.

Example

RoleBindingSubject(kind="ServiceAccount", name="my-sa", namespace="production") RoleBindingSubject(kind="User", name="jane@example.com") RoleBindingSubject(kind="Group", name="developers")

Source code in src/k8smith/core/models.py

class RoleBindingSubject(KubeModel):
    """Subject for RoleBinding and ClusterRoleBinding.

    Example:
        >>> RoleBindingSubject(kind="ServiceAccount", name="my-sa", namespace="production")
        >>> RoleBindingSubject(kind="User", name="jane@example.com")
        >>> RoleBindingSubject(kind="Group", name="developers")
    """

    kind: Literal["User", "Group", "ServiceAccount"]
    name: str
    namespace: str | None = None
    api_group: str | None = Field(default=None, alias="apiGroup")

Pod Components¶

Container¶

`Container` ¶

Bases: KubeModel

Container specification.

Example

Container( ... name="web", ... image="nginx:1.25", ... ports=[ContainerPort(container_port=80)], ... resources=ResourceRequirements( ... requests=ResourceQuantity(cpu="100m", memory="128Mi"), ... ), ... )

Source code in src/k8smith/core/models.py

class Container(KubeModel):
    """Container specification.

    Example:
        >>> Container(
        ...     name="web",
        ...     image="nginx:1.25",
        ...     ports=[ContainerPort(container_port=80)],
        ...     resources=ResourceRequirements(
        ...         requests=ResourceQuantity(cpu="100m", memory="128Mi"),
        ...     ),
        ... )
    """

    name: str
    image: str
    image_pull_policy: Literal["Always", "IfNotPresent", "Never"] | None = Field(
        default=None, alias="imagePullPolicy"
    )
    command: list[str] | None = None
    args: list[str] | None = None
    working_dir: str | None = Field(default=None, alias="workingDir")
    env: list[EnvVar] | None = None
    env_from: list[EnvFromSource] | None = Field(default=None, alias="envFrom")
    ports: list[ContainerPort] | None = None
    resources: ResourceRequirements | None = None
    volume_mounts: list[VolumeMount] | None = Field(default=None, alias="volumeMounts")
    liveness_probe: Probe | None = Field(default=None, alias="livenessProbe")
    readiness_probe: Probe | None = Field(default=None, alias="readinessProbe")
    startup_probe: Probe | None = Field(default=None, alias="startupProbe")
    security_context: SecurityContext | None = Field(default=None, alias="securityContext")
    stdin: bool | None = None
    tty: bool | None = None

PodSpec¶

`PodSpec` ¶

Bases: KubeModel

Pod specification.

Example

PodSpec( ... containers=[Container(name="app", image="myapp:v1")], ... service_account_name="my-sa", ... )

Source code in src/k8smith/core/models.py

class PodSpec(KubeModel):
    """Pod specification.

    Example:
        >>> PodSpec(
        ...     containers=[Container(name="app", image="myapp:v1")],
        ...     service_account_name="my-sa",
        ... )
    """

    containers: list[Container]
    init_containers: list[Container] | None = Field(default=None, alias="initContainers")
    volumes: list[Volume] | None = None
    service_account_name: str | None = Field(default=None, alias="serviceAccountName")
    automount_service_account_token: bool | None = Field(
        default=None, alias="automountServiceAccountToken"
    )
    node_selector: dict[str, str] | None = Field(default=None, alias="nodeSelector")
    node_name: str | None = Field(default=None, alias="nodeName")
    tolerations: list[Toleration] | None = None
    affinity: dict | None = None
    host_network: bool | None = Field(default=None, alias="hostNetwork")
    host_pid: bool | None = Field(default=None, alias="hostPID")
    dns_policy: str | None = Field(default=None, alias="dnsPolicy")
    dns_config: dict | None = Field(default=None, alias="dnsConfig")
    security_context: PodSecurityContext | None = Field(default=None, alias="securityContext")
    image_pull_secrets: list[dict] | None = Field(default=None, alias="imagePullSecrets")
    restart_policy: Literal["Always", "OnFailure", "Never"] | None = Field(
        default=None, alias="restartPolicy"
    )
    termination_grace_period_seconds: int | None = Field(
        default=None, alias="terminationGracePeriodSeconds"
    )
    priority_class_name: str | None = Field(default=None, alias="priorityClassName")
    topology_spread_constraints: list[TopologySpreadConstraint] | None = Field(
        default=None, alias="topologySpreadConstraints"
    )

PodTemplateSpec¶

`PodTemplateSpec` ¶

Bases: KubeModel

Pod template for Deployment, StatefulSet, etc.

Example

PodTemplateSpec( ... metadata={"labels": {"app": "web"}}, ... spec=PodSpec(containers=[Container(name="web", image="nginx")]), ... )

Source code in src/k8smith/core/models.py

class PodTemplateSpec(KubeModel):
    """Pod template for Deployment, StatefulSet, etc.

    Example:
        >>> PodTemplateSpec(
        ...     metadata={"labels": {"app": "web"}},
        ...     spec=PodSpec(containers=[Container(name="web", image="nginx")]),
        ... )
    """

    metadata: dict | None = None
    spec: PodSpec

Volume¶

`Volume` ¶

Bases: KubeModel

Pod volume definition.

Example

Volume(name="config", config_map={"name": "my-config"}) Volume(name="data", empty_dir={}) Volume(name="secrets", csi={"driver": "secrets-store.csi.k8s.io", "readOnly": True})

Source code in src/k8smith/core/models.py

class Volume(KubeModel):
    """Pod volume definition.

    Example:
        >>> Volume(name="config", config_map={"name": "my-config"})
        >>> Volume(name="data", empty_dir={})
        >>> Volume(name="secrets", csi={"driver": "secrets-store.csi.k8s.io", "readOnly": True})
    """

    name: str
    config_map: dict | None = Field(default=None, alias="configMap")
    secret: dict | None = None
    empty_dir: dict | None = Field(default=None, alias="emptyDir")
    persistent_volume_claim: dict | None = Field(default=None, alias="persistentVolumeClaim")
    host_path: dict | None = Field(default=None, alias="hostPath")
    projected: dict | None = None
    downward_api: dict | None = Field(default=None, alias="downwardAPI")
    csi: dict | None = None

VolumeMount¶

`VolumeMount` ¶

Bases: KubeModel

Container volume mount.

Example

VolumeMount(name="config", mount_path="/etc/config", read_only=True)

Source code in src/k8smith/core/models.py

class VolumeMount(KubeModel):
    """Container volume mount.

    Example:
        >>> VolumeMount(name="config", mount_path="/etc/config", read_only=True)
    """

    name: str
    mount_path: str = Field(alias="mountPath")
    read_only: bool | None = Field(default=None, alias="readOnly")
    sub_path: str | None = Field(default=None, alias="subPath")
    sub_path_expr: str | None = Field(default=None, alias="subPathExpr")

EnvVar¶

`EnvVar` ¶

Bases: KubeModel

Environment variable.

Example

EnvVar(name="DATABASE_URL", value="postgres://localhost/db") EnvVar(name="POD_NAME", value_from={"fieldRef": {"fieldPath": "metadata.name"}})

Source code in src/k8smith/core/models.py

class EnvVar(KubeModel):
    """Environment variable.

    Example:
        >>> EnvVar(name="DATABASE_URL", value="postgres://localhost/db")
        >>> EnvVar(name="POD_NAME", value_from={"fieldRef": {"fieldPath": "metadata.name"}})
    """

    name: str
    value: str | None = None
    value_from: dict | None = Field(default=None, alias="valueFrom")

Probe¶

`Probe` ¶

Bases: KubeModel

Liveness/Readiness/Startup probe configuration.

Example

Probe( ... http_get={"path": "/health", "port": 8080}, ... initial_delay_seconds=30, ... period_seconds=10, ... )

Source code in src/k8smith/core/models.py

class Probe(KubeModel):
    """Liveness/Readiness/Startup probe configuration.

    Example:
        >>> Probe(
        ...     http_get={"path": "/health", "port": 8080},
        ...     initial_delay_seconds=30,
        ...     period_seconds=10,
        ... )
    """

    http_get: dict | None = Field(default=None, alias="httpGet")
    tcp_socket: dict | None = Field(default=None, alias="tcpSocket")
    exec_: dict | None = Field(default=None, alias="exec")
    grpc: dict | None = None
    initial_delay_seconds: int | None = Field(default=None, alias="initialDelaySeconds")
    period_seconds: int | None = Field(default=None, alias="periodSeconds")
    timeout_seconds: int | None = Field(default=None, alias="timeoutSeconds")
    success_threshold: int | None = Field(default=None, alias="successThreshold")
    failure_threshold: int | None = Field(default=None, alias="failureThreshold")

ResourceRequirements¶

`ResourceRequirements` ¶

Bases: KubeModel

Container resource requests and limits.

Example

ResourceRequirements( ... requests=ResourceQuantity(cpu="100m", memory="128Mi"), ... limits=ResourceQuantity(memory="256Mi"), ... )

Source code in src/k8smith/core/models.py

class ResourceRequirements(KubeModel):
    """Container resource requests and limits.

    Example:
        >>> ResourceRequirements(
        ...     requests=ResourceQuantity(cpu="100m", memory="128Mi"),
        ...     limits=ResourceQuantity(memory="256Mi"),
        ... )
    """

    requests: ResourceQuantity | None = None
    limits: ResourceQuantity | None = None

ResourceQuantity¶

`ResourceQuantity` ¶

Bases: KubeModel

Kubernetes resource quantity (e.g., '100m', '512Mi', '2Gi').

Example

ResourceQuantity(cpu="100m", memory="512Mi") ResourceQuantity(memory="4Gi", extended={"nvidia.com/gpu": "1"})

Source code in src/k8smith/core/models.py

class ResourceQuantity(KubeModel):
    """Kubernetes resource quantity (e.g., '100m', '512Mi', '2Gi').

    Example:
        >>> ResourceQuantity(cpu="100m", memory="512Mi")
        >>> ResourceQuantity(memory="4Gi", extended={"nvidia.com/gpu": "1"})
    """

    cpu: str | None = None
    memory: str | None = None
    extended: dict[str, str] = Field(default_factory=dict)

    @model_serializer
    def serialize(self) -> dict[str, str]:
        """Flatten extended resources into the main dict."""
        result: dict[str, str] = {}
        if self.cpu:
            result["cpu"] = self.cpu
        if self.memory:
            result["memory"] = self.memory
        # Flatten extended resources (e.g., nvidia.com/gpu)
        result.update(self.extended)
        return result

`serialize()` ¶

Flatten extended resources into the main dict.

Source code in src/k8smith/core/models.py

@model_serializer
def serialize(self) -> dict[str, str]:
    """Flatten extended resources into the main dict."""
    result: dict[str, str] = {}
    if self.cpu:
        result["cpu"] = self.cpu
    if self.memory:
        result["memory"] = self.memory
    # Flatten extended resources (e.g., nvidia.com/gpu)
    result.update(self.extended)
    return result

Security¶

SecurityContext¶

`SecurityContext` ¶

Bases: KubeModel

Container security context.

Example

SecurityContext( ... run_as_non_root=True, ... read_only_root_filesystem=True, ... allow_privilege_escalation=False, ... )

Source code in src/k8smith/core/models.py

class SecurityContext(KubeModel):
    """Container security context.

    Example:
        >>> SecurityContext(
        ...     run_as_non_root=True,
        ...     read_only_root_filesystem=True,
        ...     allow_privilege_escalation=False,
        ... )
    """

    run_as_user: int | None = Field(default=None, alias="runAsUser")
    run_as_group: int | None = Field(default=None, alias="runAsGroup")
    run_as_non_root: bool | None = Field(default=None, alias="runAsNonRoot")
    read_only_root_filesystem: bool | None = Field(default=None, alias="readOnlyRootFilesystem")
    privileged: bool | None = None
    allow_privilege_escalation: bool | None = Field(default=None, alias="allowPrivilegeEscalation")
    capabilities: dict | None = None
    seccomp_profile: dict | None = Field(default=None, alias="seccompProfile")

PodSecurityContext¶

`PodSecurityContext` ¶

Bases: KubeModel

Pod-level security context.

Example

PodSecurityContext(run_as_non_root=True, fs_group=1000)

Source code in src/k8smith/core/models.py

class PodSecurityContext(KubeModel):
    """Pod-level security context.

    Example:
        >>> PodSecurityContext(run_as_non_root=True, fs_group=1000)
    """

    run_as_user: int | None = Field(default=None, alias="runAsUser")
    run_as_group: int | None = Field(default=None, alias="runAsGroup")
    run_as_non_root: bool | None = Field(default=None, alias="runAsNonRoot")
    fs_group: int | None = Field(default=None, alias="fsGroup")
    fs_group_change_policy: str | None = Field(default=None, alias="fsGroupChangePolicy")
    supplemental_groups: list[int] | None = Field(default=None, alias="supplementalGroups")
    seccomp_profile: dict | None = Field(default=None, alias="seccompProfile")

Networking¶

ServicePort¶

`ServicePort` ¶

Bases: KubeModel

Service port configuration.

Example

ServicePort(port=80, target_port=8080, name="http")

Source code in src/k8smith/core/models.py

class ServicePort(KubeModel):
    """Service port configuration.

    Example:
        >>> ServicePort(port=80, target_port=8080, name="http")
    """

    port: int
    target_port: int | str | None = Field(default=None, alias="targetPort")
    name: str | None = None
    protocol: Literal["TCP", "UDP", "SCTP"] | None = None
    node_port: int | None = Field(default=None, alias="nodePort")
    app_protocol: str | None = Field(default=None, alias="appProtocol")

ContainerPort¶

`ContainerPort` ¶

Bases: KubeModel

Container port configuration.

Example

ContainerPort(container_port=8080, name="http") ContainerPort(container_port=80, host_port=8080)

Source code in src/k8smith/core/models.py

class ContainerPort(KubeModel):
    """Container port configuration.

    Example:
        >>> ContainerPort(container_port=8080, name="http")
        >>> ContainerPort(container_port=80, host_port=8080)
    """

    container_port: int = Field(alias="containerPort")
    host_port: int | None = Field(default=None, alias="hostPort")
    host_ip: str | None = Field(default=None, alias="hostIP")
    name: str | None = None
    protocol: Literal["TCP", "UDP", "SCTP"] = "TCP"
    app_protocol: str | None = Field(default=None, alias="appProtocol")

Scheduling¶

Toleration¶

`Toleration` ¶

Bases: KubeModel

Pod toleration.

Example

Toleration(key="nvidia.com/gpu", operator="Exists", effect="NoSchedule")

Source code in src/k8smith/core/models.py

class Toleration(KubeModel):
    """Pod toleration.

    Example:
        >>> Toleration(key="nvidia.com/gpu", operator="Exists", effect="NoSchedule")
    """

    key: str | None = None
    operator: Literal["Exists", "Equal"] | None = None
    value: str | None = None
    effect: Literal["NoSchedule", "PreferNoSchedule", "NoExecute"] | None = None
    toleration_seconds: int | None = Field(default=None, alias="tolerationSeconds")

Core Models¶

Base Models¶

KubeModel ¶

to_dict() ¶

Resource Specifications¶

Deployment¶

DeploymentSpec ¶

StatefulSet¶

StatefulSetSpec ¶

DaemonSet¶

DaemonSetSpec ¶

Service¶

ServiceSpec ¶

CronJob¶

CronJobSpec ¶

ConfigMap¶

ConfigMapSpec ¶

Secret¶

SecretSpec ¶

HPA¶

HPASpec ¶

PDB¶

PDBSpec ¶

ServiceAccount¶

ServiceAccountSpec ¶

Namespace¶

NamespaceSpec ¶

RBAC Models¶

Role¶

RoleSpec ¶

ClusterRole¶

ClusterRoleSpec ¶

RoleBinding¶

RoleBindingSpec ¶

ClusterRoleBinding¶

ClusterRoleBindingSpec ¶

PolicyRule¶

PolicyRule ¶

RoleRef¶

RoleRef ¶

RoleBindingSubject¶

RoleBindingSubject ¶

Pod Components¶

Container¶

Container ¶

PodSpec¶

PodSpec ¶

PodTemplateSpec¶

PodTemplateSpec ¶

Volume¶

Volume ¶

VolumeMount¶

VolumeMount ¶

EnvVar¶

EnvVar ¶

Probe¶

Probe ¶

ResourceRequirements¶

ResourceRequirements ¶

ResourceQuantity¶

ResourceQuantity ¶

serialize() ¶

Security¶

SecurityContext¶

SecurityContext ¶

PodSecurityContext¶

PodSecurityContext ¶

Networking¶

ServicePort¶

ServicePort ¶

ContainerPort¶

ContainerPort ¶

Scheduling¶

Toleration¶

Toleration ¶

`KubeModel` ¶

`to_dict()` ¶

`DeploymentSpec` ¶

`StatefulSetSpec` ¶

`DaemonSetSpec` ¶

`ServiceSpec` ¶

`CronJobSpec` ¶

`ConfigMapSpec` ¶

`SecretSpec` ¶

`HPASpec` ¶

`PDBSpec` ¶

`ServiceAccountSpec` ¶

`NamespaceSpec` ¶

`RoleSpec` ¶

`ClusterRoleSpec` ¶

`RoleBindingSpec` ¶

`ClusterRoleBindingSpec` ¶

`PolicyRule` ¶

`RoleRef` ¶

`RoleBindingSubject` ¶

`Container` ¶

`PodSpec` ¶

`PodTemplateSpec` ¶

`Volume` ¶

`VolumeMount` ¶

`EnvVar` ¶

`Probe` ¶

`ResourceRequirements` ¶

`ResourceQuantity` ¶

`serialize()` ¶

`SecurityContext` ¶

`PodSecurityContext` ¶

`ServicePort` ¶

`ContainerPort` ¶

`Toleration` ¶