# Provider API

Module: `citadel_operator.k3s.provider`

Manages the local K3s cluster via Rancher Desktop for development. Provides cluster lifecycle operations, image management, and configuration for Cilium integration.

## Constants

```python
DEFAULT_KUBE_CONTEXT = "rancher-desktop"
HOST_FROM_CLUSTER = "host.rancher-desktop.internal"
```

## ClusterState

Enum representing the state of the Rancher Desktop cluster.

```python
class ClusterState(Enum):
    RUNNING = "running"
    STOPPED = "stopped"
    STARTING = "starting"
    ERROR = "error"
    UNKNOWN = "unknown"
```

## ClusterInfo

Frozen dataclass representing the current cluster status.

```python
@dataclass(frozen=True)
class ClusterInfo:
    state: ClusterState
    kubernetes_version: str
    node_name: str
    node_ready: bool
    flannel_enabled: bool
    traefik_enabled: bool
    container_engine: str
```

## ResetResult

Frozen dataclass representing the outcome of a cluster reset.

```python
@dataclass(frozen=True)
class ResetResult:
    success: bool
    previous_state: ClusterState
    new_state: ClusterState
    error: str | None = None
```

## RancherDesktopProvider

### Constructor

```python
RancherDesktopProvider()
```

No constructor arguments. Uses the default Rancher Desktop context (`rancher-desktop`).

### Methods

| Method | Signature | Description |
|--------|-----------|-------------|
| `get_status` | `() -> ClusterInfo` | Get current cluster state, K8s version, node readiness, and configuration |
| `is_ready` | `() -> bool` | Check if the cluster is running and the node is ready |
| `configure_for_cilium` | `() -> bool` | Disable Flannel and Traefik to prepare for Cilium CNI |
| `reset_k3s` | `() -> ResetResult` | Reset the K3s cluster to a clean state |
| `shutdown` | `() -> bool` | Stop the Rancher Desktop cluster |
| `start` | `() -> bool` | Start the Rancher Desktop cluster |
| `shell` | `(*cmd: str) -> CompletedProcess` | Execute a command inside the Rancher Desktop VM |
| `build_image` | `(context_dir: str, tag: str, dockerfile: str \| None = None) -> bool` | Build a container image via nerdctl |
| `list_images` | `(filter_name: str \| None = None) -> list[ImageInfo]` | List container images in the k8s.io namespace |
| `load_image` | `(path: str) -> bool` | Load a container image from a tarball into Rancher Desktop |

### Usage

```python
from citadel_operator.k3s.provider import RancherDesktopProvider

provider = RancherDesktopProvider()

# Check cluster status
info = provider.get_status()
print(f"State: {info.state}")
print(f"K8s: {info.kubernetes_version}")
print(f"Node ready: {info.node_ready}")

# Configure for Cilium (disable Flannel + Traefik)
if info.flannel_enabled:
    provider.configure_for_cilium()

# Build and load an operator image
provider.build_image(context_dir=".", tag="citadel-operator:latest")
```
