### Full Deployment Example with Context Manager

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/builders.md

A comprehensive example demonstrating the creation of a Kubernetes Deployment object using nested context managers. This includes configuring metadata, spec, containers, ports, and volumes.

```python
from cloudcoil.models.kubernetes.apps.v1 import Deployment
from cloudcoil.models.kubernetes.core.v1 import Container, ContainerPort, VolumeMount
from cloudcoil import apimachinery

with Deployment.new() as deployment:
    # Configure metadata
    with deployment.metadata() as meta:
        meta.name("web-app")
        meta.namespace("production")
        meta.labels({"app": "web", "version": "1.0"})
    
    # Configure spec
    with deployment.spec() as spec:
        spec.replicas(3)
        spec.min_ready_seconds(10)
        
        # Label selector
        with spec.selector() as selector:
            selector.match_labels({"app": "web"})
        
        # Pod template
        with spec.template() as template:
            with template.metadata() as meta:
                meta.labels({"app": "web"})
            
            # Pod spec
            with template.spec() as pod_spec:
                pod_spec.restart_policy("Always")
                
                # Containers
                with pod_spec.containers() as containers:
                    with containers.add() as container:
                        container.name("web")
                        container.image("nginx:1.21")
                        container.image_pull_policy("IfNotPresent")
                        
                        # Ports
                        with container.ports() as ports:
                            with ports.add() as port:
                                port.container_port(80)
                                port.name("http")
                            with ports.add() as port:
                                port.container_port(443)
                                port.name("https")
                        
                        # Volume mounts
                        with container.volume_mounts() as mounts:
                            with mounts.add() as mount:
                                mount.name("config")
                                mount.mount_path("/etc/nginx/conf.d")
                            with mounts.add() as mount:
                                mount.name("data")
                                mount.mount_path("/var/www")
                
                # Volumes
                with pod_spec.volumes() as volumes:
                    with volumes.add() as volume:
                        volume.name("config")
                        # ConfigMap source configured separately
                    with volumes.add() as volume:
                        volume.name("data")
                        # PVC source configured separately

final_deployment = deployment.build()
```

--------------------------------

### Service Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/core-resources.md

Provides Python code examples demonstrating how to create and configure Kubernetes Service resources.

```APIDOC
### Usage Example

```python
from cloudcoil.models.kubernetes.core.v1 import Service, ServicePort, ServiceSpec
from cloudcoil import apimachinery

# ClusterIP Service
service = Service(
    metadata=apimachinery.ObjectMeta(
        name="nginx-service",
        namespace="default"
    ),
    spec=ServiceSpec(
        type="ClusterIP",
        selector={"app": "nginx"},
        ports=[
            ServicePort(port=80, target_port=8080, protocol="TCP")
        ]
    )
)

# LoadBalancer Service
lb_service = (
    Service.builder()
    .metadata(lambda m: m
        .name("nginx-lb")
        .namespace("default")
    )
    .spec(lambda s: s
        .type("LoadBalancer")
        .selector({"app": "nginx"})
        .ports([
            lambda p: p
            .port(80)
            .target_port(80)
            .protocol("TCP")
        ])
    )
    .build()
)
```
```

--------------------------------

### StatefulSet Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/apps-resources.md

Demonstrates how to create a StatefulSet for a PostgreSQL database, configuring replicas, persistent storage, and update strategy. This example highlights stable pod identities and persistent volume claims.

```python
from cloudcoil.models.kubernetes.apps.v1 import (
    StatefulSet, StatefulSetSpec, StatefulSetUpdateStrategy,
    RollingUpdateStatefulSetStrategy
)
from cloudcoil.models.kubernetes.core.v1 import (
    Container, PersistentVolumeClaim, PersistentVolumeClaimSpec,
    PodTemplateSpec, PodSpec
)
from cloudcoil import apimachinery

# Create a database StatefulSet with persistent storage
statefulset = StatefulSet(
    metadata=apimachinery.ObjectMeta(
        name="postgres",
        namespace="database"
    ),
    spec=StatefulSetSpec(
        service_name="postgres-headless",
        replicas=3,
        selector=apimachinery.LabelSelector(
            match_labels={"app": "postgres"}
        ),
        template=PodTemplateSpec(
            metadata=apimachinery.ObjectMeta(
                labels={"app": "postgres"}
            ),
            spec=PodSpec(
                containers=[
                    Container(
                        name="postgres",
                        image="postgres:14",
                        ports=[ContainerPort(container_port=5432)],
                        volume_mounts=[
                            VolumeMount(
                                name="data",
                                mount_path="/var/lib/postgresql"
                            )
                        ]
                    )
                ]
            )
        ),
        volume_claim_templates=[
            PersistentVolumeClaim(
                metadata=apimachinery.ObjectMeta(name="data"),
                spec=PersistentVolumeClaimSpec(
                    access_modes=["ReadWriteOnce"],
                    storage_class_name="fast-ssd",
                    resources={"requests": {"storage": "50Gi"}}
                )
            )
        ],
        update_strategy=StatefulSetUpdateStrategy(
            type="RollingUpdate",
            rolling_update=RollingUpdateStatefulSetStrategy(partition=0)
        ),
        pod_management_policy="OrderedReady"
    )
)

# Pod naming: postgres-0, postgres-1, postgres-2
# Each pod gets stable DNS: postgres-0.postgres-headless.database.svc.cluster.local
```

--------------------------------

### CronJob Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/batch-resources.md

Demonstrates how to create a CronJob resource for daily database backups using direct instantiation.

```python
from cloudcoil.models.kubernetes.batch.v1 import (
    CronJob, CronJobSpec, JobTemplateSpec
)
from cloudcoil.models.kubernetes.batch.v1 import Job, JobSpec
from cloudcoil.models.kubernetes.core.v1 import Container, PodTemplateSpec, PodSpec
from cloudcoil import apimachinery

# Daily database backup
cronjob = CronJob(
    metadata=apimachinery.ObjectMeta(
        name="daily-backup",
        namespace="production"
    ),
    spec=CronJobSpec(
        schedule="0 2 * * *",  # 2 AM daily
        timezone="UTC",
        concurrency_policy="Forbid",  # Don't overlap jobs
        success_history_limit=3,
        failure_history_limit=1,
        job_template=JobTemplateSpec(
            spec=JobSpec(
                backoff_limit=2,
                template=PodTemplateSpec(
                    spec=PodSpec(
                        containers=[
                            Container(
                                name="backup",
                                image="backup-tool:latest",
                                command=["./backup.sh"],
                                env=[
                                    {"name": "DB_HOST", "value": "postgres.db"},
                                    {"name": "BACKUP_PATH", "value": "/backups"}
                                ]
                            )
                        ],
                        restart_policy="OnFailure"
                    )
                )
            )
        )
    )
)
```

--------------------------------

### Create a ConfigMap Instance

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/core-resources.md

Example of creating a ConfigMap object with metadata and string data.

```python
from cloudcoil.models.kubernetes.core.v1 import ConfigMap
from cloudcoil import apimachinery

config = ConfigMap(
    metadata=apimachinery.ObjectMeta(
        name="app-config",
        namespace="default"
    ),
    data={
        "database_url": "postgres://db:5432/app",
        "log_level": "debug",
        "api_timeout": "30"
    }
)
```

--------------------------------

### DaemonSet Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/apps-resources.md

Example of creating a DaemonSet resource to deploy the 'node-exporter' monitoring agent to all nodes in the 'monitoring' namespace. Ensures the agent runs with host networking enabled.

```python
from cloudcoil.models.kubernetes.apps.v1 import DaemonSet, DaemonSetSpec
from cloudcoil.models.kubernetes.core.v1 import Container, PodTemplateSpec, PodSpec
from cloudcoil import apimachinery

# Deploy monitoring agent to all nodes
daemonset = DaemonSet(
    metadata=apimachinery.ObjectMeta(
        name="node-exporter",
        namespace="monitoring"
    ),
    spec=DaemonSetSpec(
        selector=apimachinery.LabelSelector(
            match_labels={"app": "node-exporter"}
        ),
        template=PodTemplateSpec(
            metadata=apimachinery.ObjectMeta(
                labels={"app": "node-exporter"}
            ),
            spec=PodSpec(
                host_network=True,
                containers=[
                    Container(
                        name="exporter",
                        image="prom/node-exporter:latest"
                    )
                ]
            )
        )
    )
)
```

--------------------------------

### RuntimeClass Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/advanced-apis.md

Demonstrates how to create a RuntimeClass object for gVisor and how to reference it within a Pod specification.

```python
from cloudcoil.models.kubernetes.node.v1 import RuntimeClass, Overhead
from cloudcoil import apimachinery

# gVisor runtime
gvisor = RuntimeClass(
    metadata=apimachinery.ObjectMeta(name="gvisor"),
    handler="runsc",
    overhead=Overhead(
        pod_fixed={
            "memory": "50Mi",
            "cpu": "100m"
        }
    )
)

# Using in Pod
pod = Pod(
    metadata=apimachinery.ObjectMeta(name="safe-pod"),
    spec=PodSpec(
        runtime_class_name="gvisor",
        containers=[...]
    )
)
```

--------------------------------

### ReplicaSet Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/apps-resources.md

Demonstrates how to instantiate a ReplicaSet object. Note that direct creation is uncommon; Deployments are preferred for production environments.

```python
# ReplicaSets are typically created by Deployments
# Direct creation is uncommon; Deployment is preferred for production
from cloudcoil.models.kubernetes.apps.v1 import ReplicaSet, ReplicaSetSpec
from cloudcoil.models.kubernetes.core.v1 import Container, PodTemplateSpec, PodSpec
from cloudcoil import apimachinery

replicaset = ReplicaSet(
    metadata=apimachinery.ObjectMeta(
        name="app-replicas",
        namespace="default"
    ),
    spec=ReplicaSetSpec(
        replicas=2,
        selector=apimachinery.LabelSelector(
            match_labels={"app": "myapp"}
        ),
        template=PodTemplateSpec(
            spec=PodSpec(
                containers=[
                    Container(name="app", image="myapp:1.0")
                ]
            )
        )
    )
)
```

--------------------------------

### Kubernetes Object Labels Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/README.md

Demonstrates how to define labels for Kubernetes objects using the ObjectMeta class.

```python
metadata=ObjectMeta(
    labels={"app": "web", "version": "1.0", "tier": "frontend"}
)
```

--------------------------------

### Create ServiceAccount Instance

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/core-resources.md

Example of creating a ServiceAccount instance with metadata and token auto-mount settings.

```python
from cloudcoil.models.kubernetes.core.v1 import ServiceAccount
from cloudcoil import apimachinery

sa = ServiceAccount(
    metadata=apimachinery.ObjectMeta(
        name="app-reader",
        namespace="default"
    ),
    automount_service_account_token=True
)
```

--------------------------------

### Install cloudcoil-models-kubernetes with uv

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/overview.md

Installs the cloudcoil.models.kubernetes package using the uv package manager. This is the recommended installation method.

```bash
uv add cloudcoil.models.kubernetes
```

--------------------------------

### TypeMeta Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/types.md

Shows how to instantiate a TypeMeta object with the API version and kind, for example, specifying 'v1' and 'Pod'.

```python
from cloudcoil import apimachinery

meta = apimachinery.TypeMeta(
    api_version="v1",
    kind="Pod"
)
```

--------------------------------

### ClusterRole Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/rbac-storage-resources.md

Example of creating a ClusterRole to grant kubelet node access. Requires importing ClusterRole, PolicyRule, and apimachinery.

```python
from cloudcoil.models.kubernetes.rbac.v1 import ClusterRole, PolicyRule
from cloudcoil import apimachinery

# Node access for kubelet
cluster_role = ClusterRole(
    metadata=apimachinery.ObjectMeta(name="node-reader"),
    rules=[
        PolicyRule(
            verbs=["get", "list"],
            api_groups=[""],
            resources=["nodes"]
        ),
        PolicyRule(
            verbs=["get", "list"],
            api_groups=[""],
            resources=["nodes/status"]
        )
    ]
)
```

--------------------------------

### Install cloudcoil-models-kubernetes with pip

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/overview.md

Installs the cloudcoil.models.kubernetes package using pip. This is an alternative installation method.

```bash
pip install cloudcoil.models.kubernetes
```

--------------------------------

### Pod Initialization Examples

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/core-resources.md

Demonstrates three ways to initialize a Pod object: direct initialization, fluent builder style, and context manager style. Ensure necessary imports are included.

```python
from cloudcoil.models.kubernetes.core.v1 import Pod, Container, ContainerPort
from cloudcoil import apimachinery

# Direct initialization
pod = Pod(
    metadata=apimachinery.ObjectMeta(
        name="nginx-pod",
        namespace="default",
        labels={"app": "nginx"}
    ),
    spec=PodSpec(
        containers=[
            Container(
                name="nginx",
                image="nginx:latest",
                ports=[ContainerPort(container_port=80)]
            )
        ],
        restart_policy="Always"
    )
)
```

```python
# Fluent builder style
pod = (
    Pod.builder()
    .metadata(lambda m: m
        .name("nginx-pod")
        .namespace("default")
        .labels({"app": "nginx"})
    )
    .spec(lambda s: s
        .restart_policy("Always")
        .containers([
            lambda c: c
            .name("nginx")
            .image("nginx:latest")
            .ports(lambda ports: ports.add(
                lambda p: p.container_port(80)
            ))
        ])
    )
    .build()
)
```

```python
# Context manager style
with Pod.new() as pod:
    with pod.metadata() as meta:
        meta.name("nginx-pod")
        meta.namespace("default")
    with pod.spec() as spec:
        spec.restart_policy("Always")
        with spec.containers() as containers:
            with containers.add() as container:
                container.name("nginx")
                container.image("nginx:latest")
```

--------------------------------

### Kubernetes Deployment Construction with Fluent Builder

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/builders.md

Shows a comprehensive example of building a Kubernetes Deployment object using the fluent builder pattern, including metadata, spec, replicas, selector, and container definitions.

```python
from cloudcoil.models.kubernetes.apps.v1 import Deployment
from cloudcoil.models.kubernetes.core.v1 import Container, ContainerPort

deployment = (
    Deployment.builder()
    .metadata(lambda m: m
        .name("web-app")
        .namespace("production")
        .labels({"app": "web"})
    )
    .spec(lambda s: s
        .replicas(3)
        .selector(lambda sel: sel
            .match_labels({"app": "web"})
        )
        .template(lambda t: t
            .metadata(lambda m: m
                .labels({"app": "web"})
            )
            .spec(lambda ps: ps
                .containers([
                    lambda c: c
                    .name("web")
                    .image("nginx:1.21")
                    .ports(lambda ports: ports.add(
                        lambda p: p.container_port(80)
                    ))
                ])
            )
        )
    )
    .build()
)
```

--------------------------------

### IngressClass Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/networking-resources.md

Demonstrates how to create and configure an IngressClass resource to register an ingress controller like nginx. Ensure necessary imports are present.

```python
from cloudcoil.models.kubernetes.networking.v1 import (
    IngressClass, IngressClassSpec, IngressClassParametersReference
)
from cloudcoil import apimachinery

# Register nginx ingress controller
ingress_class = IngressClass(
    metadata=apimachinery.ObjectMeta(name="nginx"),
    spec=IngressClassSpec(
        controller="kubernetes.io/ingress-nginx",
        parameters=IngressClassParametersReference(
            api_group="v1",
            kind="ConfigMap",
            name="nginx-config",
            namespace="ingress-nginx",
            scope="Cluster"
        )
    )
)
```

--------------------------------

### Cron Schedule Syntax Examples

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/batch-resources.md

Illustrates common cron schedule expressions for defining job recurrence patterns.

```text
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
│ │ │ │ │
* * * * *

- `0 0 * * *`: Daily at midnight
- `0 9 * * *`: Daily at 9 AM
- `0 0 1 * *`: First day of month at midnight
- `0 0 * * 0`: Every Sunday at midnight
- `*/15 * * * *`: Every 15 minutes
- `0 */4 * * *`: Every 4 hours
```

--------------------------------

### Role Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/rbac-storage-resources.md

Illustrates how to create and configure Role objects using the Python SDK, demonstrating both basic and builder-pattern usage.

```APIDOC
### Usage Example

```python
from cloudcoil.models.kubernetes.rbac.v1 import Role, PolicyRule
from cloudcoil import apimachinery

# Read-only pod viewer
role = Role(
    metadata=apimachinery.ObjectMeta(
        name="pod-reader",
        namespace="default"
    ),
    rules=[
        PolicyRule(
            verbs=["get", "list", "watch"],
            api_groups=[""],
            resources=["pods"]
        ),
        PolicyRule(
            verbs=["get", "list"],
            api_groups=[""],
            resources=["pods/log"]
        )
    ]
)

# Admin-like role for namespace
admin_role = (
    Role.builder()
    .metadata(lambda m: m
        .name("app-admin")
        .namespace("production"
    )
    .rules([
        lambda r: r
        .verbs(["*"])
        .api_groups(["*"])
        .resources(["*"]),
        lambda r: r
        .verbs(["*"])
        .non_resource_urls(["*"])
    ])
    .build()
)
```
```

--------------------------------

### Create a Namespace object

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/core-resources.md

Example of creating a Namespace object with metadata. Ensure the 'production' name is appropriate for your environment.

```python
from cloudcoil.models.kubernetes.core.v1 import Namespace
from cloudcoil import apimachinery

ns = Namespace(
    metadata=apimachinery.ObjectMeta(name="production")
)
```

--------------------------------

### ClusterRoleBinding Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/rbac-storage-resources.md

Example of creating a ClusterRoleBinding to grant cluster-admin role to a user. Requires importing ClusterRoleBinding, RoleRef, Subject, and apimachinery.

```python
from cloudcoil.models.kubernetes.rbac.v1 import ClusterRoleBinding, RoleRef, Subject
from cloudcoil import apimachinery

# Make user admin across entire cluster
cluster_binding = ClusterRoleBinding(
    metadata=apimachinery.ObjectMeta(name="cluster-admin"),
    role_ref=RoleRef(
        api_group="rbac.authorization.k8s.io",
        kind="ClusterRole",
        name="cluster-admin"
    ),
    subjects=[
        Subject(
            kind="User",
            name="ops@example.com",
            api_group="rbac.authorization.k8s.io"
        )
    ]
)
```

--------------------------------

### Create a Secret Instance

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/core-resources.md

Example of creating a Secret object with metadata, type, and string data.

```python
from cloudcoil.models.kubernetes.core.v1 import Secret
from cloudcoil import apimachinery
import base64

secret = Secret(
    metadata=apimachinery.ObjectMeta(
        name="db-creds",
        namespace="default"
    ),
    type="Opaque",
    string_data={
        "username": "admin",
        "password": "secretpassword123"
    }
)
```

--------------------------------

### Create a Zone-Constrained StorageClass

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/rbac-storage-resources.md

Example demonstrating how to create a StorageClass with zone constraints using a builder pattern. This is useful for regional storage provisioning.

```python
from cloudcoil.models.kubernetes.storage.v1 import (
    StorageClass, TopologySelectorTerm, TopologySelectorLabelRequirement
)
from cloudcoil import apimachinery

# Zone-constrained storage
zoned_storage = (
    StorageClass.builder()
    .metadata(lambda m: m
        .name("regional-storage"
    )
    .provisioner("ebs.csi.aws.com")
    .parameters({
        "type": "io1",
        "iops": "1000"
    })
    .volume_binding_mode("WaitForFirstConsumer")
    .allowed_topologies([
        lambda t: t
        .match_label_expressions([
            lambda lr: lr
            .key("topology.kubernetes.io/zone")
            .values(["us-east-1a", "us-east-1b"])
        ])
    ])
    .build()
)
```

--------------------------------

### CronJob Fluent Builder Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/batch-resources.md

Illustrates creating a CronJob resource using a fluent builder pattern for a log cleanup task.

```python
# Fluent builder
cronjob = (
    CronJob.builder()
    .metadata(lambda m: m
        .name("cleanup-logs")
        .namespace("ops"
    )
    .spec(lambda s: s
        .schedule("0 3 * * *")  # 3 AM daily
        .concurrency_policy("Replace")
        .job_template(lambda jt: jt
            .spec(lambda js: js
                .template(lambda t: t
                    .spec(lambda ps: ps
                        .restart_policy("OnFailure")
                        .containers([
                            lambda c: c
                            .name("cleanup")
                            .image("log-cleaner:1.0")
                            .command(["cleanup.sh"])
                        ])
                    )
                )
            )
        )
    )
    .build()
)
```

--------------------------------

### Mixing Builder Styles for Kubernetes Deployment

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/README.md

This example shows how to combine direct object initialization, fluent style, and context manager patterns when defining a Kubernetes Deployment using CloudCoil models. The IDE automatically adapts to the chosen style at each level, offering full support.

```python
from cloudcoil.models.kubernetes.apps.v1 import Deployment
from cloudcoil import apimachinery

# Mixing styles lets you choose the best approach for each part
# The IDE automatically adapts to your chosen style at each level
with Deployment.new() as nginx_deployment:
    # Direct object initialization with full type checking
    nginx_deployment.metadata(apimachinery.ObjectMeta(
        name="nginx",
        namespace="default",
        labels={"app": "nginx"}
    ))
    
    with nginx_deployment.spec() as deployment_spec:
        # IDE shows all available fields with types
        deployment_spec.replicas(3)
        # Fluent style with rich autocomplete
        deployment_spec.selector(lambda sel: sel.match_labels({"app": "nginx"}))
        
        # Context manager style with full type hints
        with deployment_spec.template() as pod_template:
            # Mix and match freely - IDE adjusts automatically
            pod_template.metadata(apimachinery.ObjectMeta(labels={"app": "nginx"}))
            with pod_template.spec() as pod_spec:
                with pod_spec.containers() as container_list:
                    with container_list.add() as nginx_container:
                        # Complete IDE support regardless of style
                        nginx_container.name("nginx")
                        nginx_container.image("nginx:latest")
                        # Switch styles any time
                        nginx_container.ports(lambda ports: ports
                            .add(lambda p: p.container_port(80))
                            .add(lambda p: p.container_port(443))
                        )

final_deployment = nginx_deployment.build()
```

--------------------------------

### Usage Example: Creating Label Selectors

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/types.md

Demonstrates how to create LabelSelector instances for exact label matching and complex expression-based selection.

```python
from cloudcoil import apimachinery

# Select by exact labels
selector = apimachinery.LabelSelector(
    match_labels={"app": "web", "tier": "frontend"}
)

# Complex selection with expressions
complex_selector = apimachinery.LabelSelector(
    match_labels={"tier": "backend"},
    match_expressions=[
        apimachinery.LabelSelectorRequirement(
            key="environment",
            operator="In",
            values=["prod", "staging"]
        ),
        apimachinery.LabelSelectorRequirement(
            key="version",
            operator="NotIn",
            values=["beta", "alpha"]
        ),
        apimachinery.LabelSelectorRequirement(
            key="high-availability",
            operator="Exists"
        )
    ]
)
```

--------------------------------

### Leader Election Lease Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/advanced-apis.md

Demonstrates how to create a Lease object for leader election. Ensure necessary imports are present.

```python
from cloudcoil.models.kubernetes.coordination.v1 import Lease, LeaseSpec
from cloudcoil import apimachinery

# Leader election lease
lease = Lease(
    metadata=apimachinery.ObjectMeta(
        name="my-app-leader",
        namespace="production"
    ),
    spec=LeaseSpec(
        holder_identity="pod-1",
        lease_duration_seconds=15,
        renew_time=apimachinery.Time.now()
    )
)
```

--------------------------------

### Container with Environment Variables

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/types.md

Example demonstrating how to create a Kubernetes Container object and populate its environment variables from literal values, ConfigMaps, Secrets, and Pod fields.

```python
from cloudcoil.models.kubernetes.core.v1 import (
    Container, EnvVar, EnvVarSource, ConfigMapKeySelector,
    SecretKeySelector, ObjectFieldSelector
)

container = Container(
    name="app",
    image="myapp:1.0",
    env=[
        # Literal value
        EnvVar(name="APP_MODE", value="production"),
        
        # From ConfigMap
        EnvVar(
            name="DATABASE_URL",
            value_from=EnvVarSource(
                config_map_key_ref=ConfigMapKeySelector(
                    name="app-config",
                    key="database_url"
                )
            )
        ),
        
        # From Secret
        EnvVar(
            name="API_KEY",
            value_from=EnvVarSource(
                secret_key_ref=SecretKeySelector(
                    name="api-secrets",
                    key="api_key"
                )
            )
        ),
        
        # Pod name
        EnvVar(
            name="POD_NAME",
            value_from=EnvVarSource(
                field_ref=ObjectFieldSelector(
                    field_path="metadata.name"
                )
            )
        )
    ]
)
```

--------------------------------

### PriorityClass Usage Examples

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/advanced-apis.md

Demonstrates how to instantiate PriorityClass objects for critical system components, default user workloads, and low priority batch jobs. Ensure correct metadata naming and value assignment.

```python
from cloudcoil.models.kubernetes.scheduling.v1 import PriorityClass
from cloudcoil import apimachinery

# Critical system component
critical = PriorityClass(
    metadata=apimachinery.ObjectMeta(name="critical"),
    value=1000000,
    description="Critical system components"
)

# Default for user workloads
default_priority = PriorityClass(
    metadata=apimachinery.ObjectMeta(name="default-priority"),
    value=100,
    global_default=True,
    description="Default priority for user applications"
)

# Low priority batch jobs
low_priority = PriorityClass(
    metadata=apimachinery.ObjectMeta(name="batch-priority"),
    value=10,
    description="Batch processing and best-effort workloads"
)
```

--------------------------------

### Job Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/batch-resources.md

Demonstrates creating a Kubernetes Job for a one-time data processing task using both direct instantiation and a fluent builder pattern. Ensure restart_policy is set to 'Never' for jobs.

```python
from cloudcoil.models.kubernetes.batch.v1 import Job, JobSpec
from cloudcoil.models.kubernetes.core.v1 import Container, PodTemplateSpec, PodSpec
from cloudcoil import apimachinery

# One-time data processing job
job = Job(
    metadata=apimachinery.ObjectMeta(
        name="data-processor",
        namespace="default"
    ),
    spec=JobSpec(
        completions=5,  # Need 5 successful completions
        parallelism=2,  # Run 2 in parallel
        backoff_limit=3,  # Retry up to 3 times
        ttl_seconds_after_finished=3600,  # Clean up after 1 hour
        template=PodTemplateSpec(
            spec=PodSpec(
                containers=[
                    Container(
                        name="processor",
                        image="myapp:process",
                        command=["python", "process.py"],
                        env=[{"name": "BATCH_ID", "value": "1"}]
                    )
                ],
                restart_policy="Never"  # Jobs must not use "Always"
            )
        )
    )
)
```

```python
# Fluent builder
job = (
    Job.builder()
    .metadata(lambda m: m
        .name("data-processor")
        .namespace("default")
    )
    .spec(lambda s: s
        .completions(5)
        .parallelism(2)
        .backoff_limit(3)
        .ttl_seconds_after_finished(3600)
        .template(lambda t: t
            .spec(lambda ps: ps
                .restart_policy("Never")
                .containers([
                    lambda c: c
                    .name("processor")
                    .image("myapp:process")
                    .command(["python", "process.py"])
                ])
            )
        )
    )
    .build()
)
```

--------------------------------

### Create Aggregated ClusterRole

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/advanced-apis.md

Example of creating a 'super-admin' ClusterRole that aggregates other ClusterRoles matching a specific label selector.

```python
from cloudcoil.models.kubernetes.rbac.v1 import ClusterRole, AggregationRule
from cloudcoil import apimachinery

# Aggregate all "admin" ClusterRoles
admin_role = ClusterRole(
    metadata=apimachinery.ObjectMeta(name="super-admin"),
    aggregation_rule=AggregationRule(
        cluster_role_selectors=[
            apimachinery.LabelSelector(
                match_labels={"admin": "true"}
            )
        ]
    )
)
```

--------------------------------

### HorizontalPodAutoscaler Usage Example (v1)

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/rbac-storage-resources.md

Demonstrates how to create and configure a HorizontalPodAutoscaler object to scale a Kubernetes Deployment based on CPU utilization. Ensure necessary imports are present.

```python
from cloudcoil.models.kubernetes.autoscaling.v1 import (
    HorizontalPodAutoscaler, HorizontalPodAutoscalerSpec,
    CrossVersionObjectReference
)
from cloudcoil import apimachinery

# Scale deployment based on CPU
hpa = HorizontalPodAutoscaler(
    metadata=apimachinery.ObjectMeta(
        name="app-scaler",
        namespace="default"
    ),
    spec=HorizontalPodAutoscalerSpec(
        scale_target_ref=CrossVersionObjectReference(
            api_version="apps/v1",
            kind="Deployment",
            name="app"
        ),
        min_replicas=2,
        max_replicas=10,
        target_cpu_utilization_percentage=70
    )
)
```

--------------------------------

### Hybrid Kubernetes Deployment Construction

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/builders.md

This example shows how to construct a Kubernetes Deployment object using a combination of context manager for the overall resource, direct initialization for metadata, and a fluent builder for the specification. It requires importing Deployment, apimachinery, and Container/PodSpec from Cloudcoil.

```python
from cloudcoil.models.kubernetes.apps.v1 import Deployment
from cloudcoil import apimachinery
from cloudcoil.models.kubernetes.core.v1 import Container, PodSpec

# Start with context manager
with Deployment.new() as deployment:
    # Use direct init for simple metadata
    deployment.metadata(apimachinery.ObjectMeta(
        name="hybrid-app",
        namespace="default",
        labels={"app": "hybrid"}
    ))
    
    # Use fluent builder for spec
    deployment.spec(lambda s: s
        .replicas(2)
        .selector(lambda sel: sel.match_labels({"app": "hybrid"}))
        .template(lambda t: t
            # Direct init for pod template spec
            .spec(PodSpec(
                containers=[
                    Container(
                        name="app",
                        image="app:latest"
                    )
                ]
            ))
        )
    )

hybrid = deployment.build()
```

--------------------------------

### RBAC Role Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/rbac-storage-resources.md

Demonstrates how to create Role objects for read-only pod viewing and administrative tasks using the RBAC API.

```python
from cloudcoil.models.kubernetes.rbac.v1 import Role, PolicyRule
from cloudcoil import apimachinery

# Read-only pod viewer
role = Role(
    metadata=apimachinery.ObjectMeta(
        name="pod-reader",
        namespace="default"
    ),
    rules=[
        PolicyRule(
            verbs=["get", "list", "watch"],
            api_groups=[""],
            resources=["pods"]
        ),
        PolicyRule(
            verbs=["get", "list"],
            api_groups=[""],
            resources=["pods/log"]
        )
    ]
)

# Admin-like role for namespace
admin_role = (
    Role.builder()
    .metadata(lambda m: m
        .name("app-admin")
        .namespace("production"
    )
    .rules([
        lambda r: r
        .verbs(["*"])
        .api_groups(["*"])
        .resources(["*"]),
        lambda r: r
        .verbs(["*"])
        .non_resource_urls(["*"])
    ])
    .build()
)
```

--------------------------------

### Kubernetes Quantity Examples

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/types.md

Illustrates how to define Kubernetes resource quantities for storage, CPU, and memory using string representations. Supports both binary (Ki, Mi, Gi) and decimal (k, M, G) suffixes.

```python
# Quantity values as strings
capacity = {"storage": "10Gi"}  # 10 Gigabytes
requests = {"cpu": "500m", "memory": "128Mi"}  # 500 millicpu, 128 Mebibytes
```

```python
from cloudcoil.models.kubernetes.core.v1 import (
    Container,
    ContainerResources
)

container = Container(
    name="app",
    image="myapp:1.0",
    resources=ContainerResources(
        requests={
            "cpu": "100m",  # Minimum guaranteed
            "memory": "64Mi"
        },
        limits={
            "cpu": "500m",  # Maximum allowed
            "memory": "256Mi"
        }
    )
)
```

--------------------------------

### RoleBinding Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/rbac-storage-resources.md

Demonstrates how to create a RoleBinding object by directly instantiating the class with role and subject details, and also shows how to use the fluent builder pattern for a more declarative approach.

```python
from cloudcoil.models.kubernetes.rbac.v1 import RoleBinding, RoleRef, Subject
from cloudcoil import apimachinery

# Bind role to service account
binding = RoleBinding(
    metadata=apimachinery.ObjectMeta(
        name="pod-reader-binding",
        namespace="default"
    ),
    role_ref=RoleRef(
        api_group="rbac.authorization.k8s.io",
        kind="Role",
        name="pod-reader"
    ),
    subjects=[
        Subject(
            kind="ServiceAccount",
            name="app-service-account",
            namespace="default"
        ),
        Subject(
            kind="User",
            name="alice@example.com",
            api_group="rbac.authorization.k8s.io"
        )
    ]
)

# Fluent builder
binding = (
    RoleBinding.builder()
    .metadata(lambda m: m
        .name("dev-access")
        .namespace("development"
    )
    .role_ref(lambda rr: rr
        .api_group("rbac.authorization.k8s.io")
        .kind("Role")
        .name("developer-role")
    )
    .subjects([
        lambda s: s
        .kind("Group")
        .name("developers")
        .api_group("rbac.authorization.k8s.io")
    ])
    .build()
)
```

--------------------------------

### Time Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/types.md

Illustrates creating a Time object from a Python datetime object and accessing its string representation in RFC3339 format.

```python
from cloudcoil import apimachinery
import datetime

# Time from datetime
creation_time = apimachinery.Time(datetime.datetime.now(datetime.timezone.utc))

# Access as string/datetime
timestamp_str = str(creation_time)  # RFC3339 format
```

--------------------------------

### Define Container with Volume Mounts

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/types.md

Example of creating a Kubernetes Container object with multiple VolumeMount configurations. Specifies the name, mount path, and read-only status for each volume.

```python
from cloudcoil.models.kubernetes.core.v1 import (
    Container, Volume, VolumeMount,
    EmptyDirVolumeSource,
    ConfigMapVolumeSource,
    PersistentVolumeClaimVolumeSource
)

container = Container(
    name="app",
    image="myapp:1.0",
    volume_mounts=[
        VolumeMount(
            name="config",
            mount_path="/etc/config"
        ),
        VolumeMount(
            name="data",
            mount_path="/var/lib/app"
        ),
        VolumeMount(
            name="cache",
            mount_path="/tmp/cache",
            read_only=False
        )
    ]
)
```

--------------------------------

### Create an ObjectReference for an Event

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/types.md

Example showing how to create an ObjectReference to a Kubernetes Pod, specifying its API version, kind, name, namespace, and UID. Requires importing apimachinery.

```python
from cloudcoil import apimachinery

event_ref = apimachinery.ObjectReference(
    api_version="v1",
    kind="Pod",
    name="my-pod",
    namespace="default",
    uid="12345-67890"
)
```

--------------------------------

### OwnerReference Usage Example

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/types.md

Demonstrates how to create an OwnerReference object to link a child object to its controller, such as a Pod owned by a Deployment. Includes setting controller and block owner deletion flags.

```python
from cloudcoil import apimachinery

# Pod owned by Deployment
owner_ref = apimachinery.OwnerReference(
    api_version="apps/v1",
    kind="Deployment",
    name="web-deployment",
    uid="12345-67890",
    controller=True,
    block_owner_deletion=True
)
```

--------------------------------

### Create LoadBalancer Service

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/core-resources.md

Example of creating a LoadBalancer Service using a builder pattern. This service is exposed externally via a cloud provider's load balancer.

```python
# LoadBalancer Service
lb_service = (
    Service.builder()
    .metadata(lambda m: m
        .name("nginx-lb")
        .namespace("default")
    )
    .spec(lambda s: s
        .type("LoadBalancer")
        .selector({"app": "nginx"})
        .ports([
            lambda p: p
            .port(80)
            .target_port(80)
            .protocol("TCP")
        ])
    )
    .build()
)
```

--------------------------------

### Create a Fast SSD StorageClass

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/rbac-storage-resources.md

Example of creating a StorageClass for fast SSD storage on AWS using the `StorageClass` model. It specifies provisioner, parameters, reclaim policy, and volume expansion settings.

```python
from cloudcoil.models.kubernetes.storage.v1 import (
    StorageClass, TopologySelectorTerm, TopologySelectorLabelRequirement
)
from cloudcoil import apimachinery

# Fast SSD storage
storage_class = StorageClass(
    metadata=apimachinery.ObjectMeta(name="fast-ssd"),
    provisioner="ebs.csi.aws.com",
    parameters={
        "type": "gp3",
        "iops": "3000",
        "throughput": "125"
    },
    reclaim_policy="Delete",
    allow_volume_expansion=True,
    volume_binding_mode="WaitForFirstConsumer"
)
```

--------------------------------

### Create, List, Update, and Delete Kubernetes Resources

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/README.md

Demonstrates creating a Deployment and Service, listing Deployments, updating a Deployment's replicas, and deleting the Service and Deployment. Ensure you have the necessary Kubernetes context configured.

```python
from cloudcoil import apimachinery
import cloudcoil.models.kubernetes.core.v1 as k8score
import cloudcoil.models.kubernetes.apps.v1 as k8sapps

# Create a Deployment
deployment = k8sapps.Deployment(
    metadata=apimachinery.ObjectMeta(name="nginx"),
    spec=k8sapps.DeploymentSpec(
        replicas=3,
        selector=apimachinery.LabelSelector(
            match_labels={"app": "nginx"}
        ),
        template=k8score.PodTemplateSpec(
            metadata=apimachinery.ObjectMeta(
                labels={"app": "nginx"}
            ),
            spec=k8score.PodSpec(
                containers=[
                    k8score.Container(
                        name="nginx",
                        image="nginx:latest",
                        ports=[k8score.ContainerPort(container_port=80)]
                    )
                ]
            )
        )
    )
).create()

# Create a Service
service = k8score.Service(
    metadata=apimachinery.ObjectMeta(name="nginx"),
    spec=k8score.ServiceSpec(
        selector={"app": "nginx"},
        ports=[k8score.ServicePort(port=80, target_port=80)]
    )
).create()

# List Deployments
for deploy in k8sapps.Deployment.list():
    print(f"Found deployment: {deploy.metadata.name}")

# Update a Deployment
deployment.spec.replicas = 5
deployment.save()

# Delete resources
k8score.Service.delete("nginx")
k8sapps.Deployment.delete("nginx")
```

--------------------------------

### Mixing Direct Initialization and Fluent Style in Builders

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/builders.md

Illustrates how to combine direct object initialization with the fluent builder pattern for constructing a Kubernetes Deployment, offering flexibility in configuration.

```python
from cloudcoil import apimachinery
from cloudcoil.models.kubernetes.apps.v1 import Deployment

deployment = (
    Deployment.builder()
    # Direct initialization for metadata
    .metadata(apimachinery.ObjectMeta(
        name="web-app",
        namespace="production"
    ))
    # Fluent lambda for spec
    .spec(lambda s: s
        .replicas(3)
        .selector(lambda sel: sel.match_labels({"app": "web"}))
    )
    .build()
)
```

--------------------------------

### Kubernetes Pod Direct Initialization

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/README.md

Shows how to create a Kubernetes Pod resource using direct initialization of its metadata and spec.

```python
Pod(
    metadata=ObjectMeta(name="my-pod"),
    spec=PodSpec(containers=[...])
)
```

--------------------------------

### Kubernetes Pod Creation with ObjectMeta

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/types.md

Demonstrates creating a Kubernetes Pod object with rich metadata, including name, namespace, labels, annotations, and finalizers. Shows how to access metadata fields after creation.

```python
from cloudcoil import apimachinery
from cloudcoil.models.kubernetes.core.v1 import Pod, PodSpec, Container
import datetime

# Create pod with rich metadata
pod = Pod(
    metadata=apimachinery.ObjectMeta(
        name="web-server",
        namespace="production",
        labels={
            "app": "web",
            "version": "1.0",
            "tier": "frontend"
        },
        annotations={
            "description": "Production web server",
            "owner": "platform-team@example.com",
            "cost-center": "eng-001"
        },
        finalizers=["cleanup.example.com/finalizer"]
    ),
    spec=PodSpec(
        containers=[
            Container(name="web", image="nginx:latest")
        ]
    )
)

# Access metadata
pod_name = pod.metadata.name  # "web-server"
pod_ns = pod.metadata.namespace  # "production"
app_label = pod.metadata.labels.get("app")  # "web"
```

--------------------------------

### Create a CertificateSigningRequest

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/advanced-apis.md

Example of how to create a CertificateSigningRequest object for requesting a service certificate. Ensure the CSR is properly base64 encoded.

```python
from cloudcoil.models.kubernetes.certificates.v1 import (
    CertificateSigningRequest, CertificateSigningRequestSpec
)
from cloudcoil import apimachinery
import base64

# Request service certificate
csr = CertificateSigningRequest(
    metadata=apimachinery.ObjectMeta(name="my-service-cert"),
    spec=CertificateSigningRequestSpec(
        request=base64.b64encode(b"...pem-encoded-csr..."),
        signer_name="kubernetes.io/kubelet-serving",
        usages=[
            "digital signature",
            "key encipherment",
            "server auth"
        ],
        expires_seconds=86400  # 1 day
    )
)
```

--------------------------------

### Initialize Kubernetes Deployment with Fluent Builder

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/apps-resources.md

Utilize the fluent builder pattern for a more readable and chained approach to constructing Deployment objects. This style can improve code clarity for complex configurations.

```python
# Fluent builder style
deployment = (
    Deployment.builder()
    .metadata(lambda m: m
        .name("nginx-deployment")
        .namespace("default")
        .labels({"app": "nginx"})
    )
    .spec(lambda s: s
        .replicas(3)
        .selector(lambda sel: sel.match_labels({"app": "nginx"}))
        .min_ready_seconds(10)
        .template(lambda pt: pt
            .metadata(lambda m: m.labels({"app": "nginx"}))
            .spec(lambda ps: ps
                .containers([
                    lambda c: c
                    .name("nginx")
                    .image("nginx:1.21")
                    .ports(lambda ports: ports.add(
                        lambda p: p.container_port(80)
                    ))
                ])
            )
        )
        .strategy(lambda st: st
            .type("RollingUpdate")
            .rolling_update(lambda ru: ru
                .max_surge("1")
                .max_unavailable("0")
            )
        )
    )
    .build()
)
```

--------------------------------

### Create ClusterIP Service

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/core-resources.md

Example of creating a ClusterIP Service using the Service and ServicePort models. This service is only accessible within the cluster.

```python
from cloudcoil.models.kubernetes.core.v1 import Service, ServicePort, ServiceSpec
from cloudcoil import apimachinery

# ClusterIP Service
service = Service(
    metadata=apimachinery.ObjectMeta(
        name="nginx-service",
        namespace="default"
    ),
    spec=ServiceSpec(
        type="ClusterIP",
        selector={"app": "nginx"},
        ports=[
            ServicePort(port=80, target_port=8080, protocol="TCP")
        ]
    )
)
```

--------------------------------

### Define a Scheduled Task (CronJob)

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/patterns-and-practices.md

Create a CronJob to schedule recurring tasks. This example sets up a daily backup job at 2 AM UTC.

```python
from cloudcoil.models.kubernetes.batch.v1 import CronJob, CronJobSpec, JobTemplateSpec, Job, JobSpec
from cloudcoil.models.kubernetes.core.v1 import Container, PodTemplateSpec, PodSpec

cronjob = CronJob(
    metadata=apimachinery.ObjectMeta(
        name="daily-backup",
        namespace="ops"
    ),
    spec=CronJobSpec(
        schedule="0 2 * * *",  # 2 AM daily
        timezone="UTC",
        concurrency_policy="Forbid",
        success_history_limit=3,
        failure_history_limit=1,
        job_template=JobTemplateSpec(
            spec=JobSpec(
                backoff_limit=2,
                template=PodTemplateSpec(
                    spec=PodSpec(
                        restart_policy="OnFailure",
                        containers=[
                            Container(
                                name="backup",
                                image="backup:1.0",
                                command=["./backup.sh"]
                            )
                        ]
                    )
                )
            )
        )
    )
)
```

--------------------------------

### Define Kubernetes Volumes

Source: https://github.com/cloudcoil/models-kubernetes/blob/main/_autodocs/types.md

Example of defining Kubernetes Volume objects, linking them to their respective sources like ConfigMaps, PersistentVolumeClaims, and EmptyDir. This complements the VolumeMount definitions.

```python
volumes = [
    Volume(
        name="config",
        config_map=ConfigMapVolumeSource(name="app-config")
    ),
    Volume(
        name="data",
        persistent_volume_claim=PersistentVolumeClaimVolumeSource(
            claim_name="app-data"
        )
    ),
    Volume(
        name="cache",
        empty_dir=EmptyDirVolumeSource()
    )
]
```