# orca.machines

> A module of morca's API.

Machines for a worker pool, from whichever provider the pool names (#267): what the autoscaler (`orca.pool_scale`) calls, so it never knows which.

var p = Provider.of("hetzner", owner)   # raises without its settings
    p.arch("cax31")                  # "arm64": Docker's name, for the image
    var got = p.create(MachineSpec("orca-lab-7", "cax31", "hel1", data, "lab"))
    for m in p.machines("lab"): ...
    _ = p.delete(m.id)

**Hetzner** (`orca.hcloud`): the token as there; a machine is a server of
`ORCA_HCLOUD_IMAGE` (`ubuntu-24.04`), with the project's SSH keys
`ORCA_HCLOUD_SSH_KEYS` (comma-separated names, none by default) and the
firewall `ORCA_HCLOUD_FIREWALL` (none by default), labelled `orca=pool`,
`orca-pool=<pool>` and `orca-owner=<owner>` (the stack's id, so stacks
sharing a project keep their machines apart), which is how `machines`
finds a pool's.

**EC2** (`orca.machines_ec2`): subnets for locations, the security group
and instance profile from the scheduler's settings, Ubuntu for the type's
architecture, the same labels as tags.

Architectures are Docker's (`arm64`, `amd64`), the names an image's
manifest uses, so the autoscaler can tell whether the worker image runs on
a type before it makes one.

## Structs

### `MachineSpec`

```mojo
struct MachineSpec
```

Implements: `Copyable`, `Movable`

Fields:

- `name: String`: A host name: 1 to 63 of a-z, 0-9 and `-`.
- `machine_type: String`
- `location: String`
- `user_data: String`
- `pool: String`

### `Machine`

```mojo
struct Machine
```

Implements: `Copyable`, `Movable`

Fields:

- `id: String`
- `name: String`
- `status: String`
- `machine_type: String`
- `location: String`
- `address: String`
- `pool: String`

### `Provider`

```mojo
struct Provider
```

Implements: `Movable`

Fields:

- `kind: String`
- `owner: String`: The stack's id, a label on every machine; empty for none.
- `image: String`
- `ssh_keys: List[String]`
- `firewall: String`

#### `__init__`

```mojo
def __init__(out self, kind: String, owner: String, var hcloud: Optional[HCloud])
```

#### `of`

```mojo
def of(kind: String, owner: String = "") -> Self
```

The provider `kind` (`hetzner`; `ec2` isn't here yet), from this process's settings, its machines labelled `owner`; raises without them.

#### `arch`

```mojo
def arch(self, machine_type: String) -> String
```

`machine_type`'s architecture, Docker's name for it.

#### `create`

```mojo
def create(self, spec: MachineSpec) -> Created
```

Makes the machine `spec` says: ok, or no stock of its type in its location (try again later, or elsewhere), or why not.

#### `machines`

```mojo
def machines(self, pool: String) -> List[Machine]
```

The provider's machines of `pool`, whatever orca.pool_machines says: the autoscaler deletes those it doesn't know.

#### `delete`

```mojo
def delete(self, id: String) -> Bool
```

Deletes machine `id`: True once it's gone, now or before.

## Functions

### `docker_arch`

```mojo
def docker_arch(provider_arch: String) -> String
```

A provider's name for an architecture as Docker's: `arm`/`aarch64` is `arm64`, `x86`/`x86_64` is `amd64`; others as they are.

## Aliases

### `POOL_LABEL`

```mojo
comptime POOL_LABEL = "orca-pool"
```

### `OWNER_LABEL`

```mojo
comptime OWNER_LABEL = "orca-owner"
```