> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes

> Run captured programs in a Kubernetes pod, including a Nitro Sandbox on EKS.

The `kubernetes` machine provider reaches a running pod, by name, through
`kubectl exec`, and the `machine` runtime runs captured programs in it. You
create the pod; Mirage only runs programs in it. Python SDK and Node.

## Installation

Install `kubectl` and sign it in to the cluster. Mirage uses the credentials and
context `kubectl` already has. Create a pod that stays running:

```yaml theme={null}
apiVersion: v1
kind: Pod
metadata:
  name: mirage-box
spec:
  containers:
    - name: main
      image: my-mirage-image
      command: ["sleep", "infinity"]
```

## Nitro Sandboxes on EKS

To run the pod in an [AWS Nitro Sandbox](https://docs.aws.amazon.com/eks/latest/userguide/sandboxing.html),
a lightweight VM with its own kernel, set the runtime class on it. This needs
Kubernetes 1.36 or later.

```yaml theme={null}
spec:
  runtimeClassName: isolated-sandbox
```

Mirage needs `exec` and stdin, so use `isolated-sandbox`. A
`confidential-sandbox` pod denies them, and programs cannot run in it.

## Usage

`captures` defaults to [`@external`](https://docs.mirage.strukto.ai/home/setup/runtime/overview#captures):
every program Mirage does not have itself. Name `@python` to run
Python in the pod too.

> [tab] Python
>
> ```python theme={null}
> from mirage import RAMVFS, MountMode, Workspace
> from mirage.runtime.machine import MachineRuntime
>
> ws = Workspace(
>     {"/data": RAMVFS()},
>     mode=MountMode.EXEC,
>     machines={"box": {"provider": "kubernetes", "pod": "mirage-box"}},
>     runtimes=[MachineRuntime(["@python", "@external"], machine="box")],
> )
> await ws.shell("python3 -c 'print(1 + 1)'")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { MountMode, MachineRuntime, RAMVFS, Workspace } from '@struktoai/mirage-node'
>
> const ws = new Workspace(
>   { '/data': new RAMVFS() },
>   {
>     mode: MountMode.EXEC,
>     machines: { box: { provider: 'kubernetes', pod: 'mirage-box' } },
>     runtimes: [new MachineRuntime({ captures: ['@python', '@external'], machine: 'box' })],
>   },
> )
> await ws.shell("python3 -c 'print(1 + 1)'")
> ```

> [tab] YAML
>
> ```yaml theme={null}
> mode: exec
> machines:
>   box:
>     provider: kubernetes
>     pod: mirage-box
> runtimes:
>   - name: machine
>     captures: ["@python", "@external"]
>     machine: box
> mounts:
>   /data:
>     vfs: ram
> ```

## Configuration

| Field | Meaning |
| - | - |
| `pod` | Name of a running pod. Required. |
| `namespace` | The pod's namespace. Defaults to the context's. |
| `container` | The container in the pod. Defaults to the pod's default. |
| `context` | The kubeconfig context. Defaults to the current one. |

## Connecting the workspace

Pick a [`mount_type`](https://docs.mirage.strukto.ai/home/setup/machine/overview#connecting-the-workspace). With `ssh`, the pod needs `sshfs` and
access to `/dev/fuse`. With `fuse`, put `sandbox.yaml` in the pod and start Mirage:

```bash theme={null}
kubectl exec mirage-box -- mirage workspace create /tmp/sandbox.yaml
```

## Notes

* The pod's phase must be `Running`.
* The working directory and environment travel on the `kubectl` command line,
  where other users of the host can see them in `ps`.
* A run whose connection to the pod drops ends with status 129.
* Lines sent to one pod share its files and processes. Give each tenant its
  own pod.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.