# orca.machines_ec2

> A module of morca's API.

A worker pool's machines on EC2 (#267): `orca.machines.Provider` for a pool with `provider = "ec2"`.

- **Where:** a pool's `locations` are subnet IDs, tried in order (each is
  in one availability zone); with none, EC2's default (or
  `ORCA_EC2_SUBNET`).
- **What each instance gets:** the security group
  `ORCA_POOL_EC2_SECURITY_GROUP` (else `ORCA_EC2_SECURITY_GROUP`), and the
  instance profile `ORCA_POOL_EC2_PROFILE` (else `ORCA_EC2_PROFILE`), whose
  role is what its worker reaches the bucket with. IMDSv2 only;
  `InstanceInitiatedShutdownBehavior=terminate`.
- **Its OS image:** Ubuntu 24.04 for the instance type's architecture,
  from the public SSM parameter Canonical keeps
  (`/aws/service/canonical/ubuntu/server/24.04/stable/current/<arch>/hvm/ebs-gp3/ami-id`),
  or `ORCA_POOL_EC2_AMI_ARM64` / `ORCA_POOL_EC2_AMI_AMD64` to pin one.
  `ORCA_SSM_ENDPOINT` points the lookup elsewhere (tests).
- **Tags:** `orca=pool`, `orca-pool=<pool>`, `orca-owner=<stack>` and
  `Name`, which is how a pool's are listed.
- **No capacity:** `InsufficientInstanceCapacity`, `Unsupported` (the type
  isn't offered in that zone) and `InsufficientCapacity` are no stock;
  `VcpuLimitExceeded` and any other refusal are reported.

## Structs

### `Ec2Machines`

```mojo
struct Ec2Machines
```

Implements: `Movable`

Fields:

- `ec2: Ec2`

#### `__init__`

```mojo
def __init__(out self)
```

#### `arch`

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

`instance_type`'s architecture, Docker's name for it (the first it supports).

#### `create`

```mojo
def create(self, name: String, instance_type: String, subnet: String, user_data: String, tags: List[Tuple[String, String]]) -> Created
```

#### `instances`

```mojo
def instances(self, tags: List[Tuple[String, String]]) -> List[Tuple[String, String, String, String, String]]
```

The live instances with every tag of `tags`: (id, name, state, type, address).

#### `delete`

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

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

## Functions

### `ec2_arch`

```mojo
def ec2_arch(arch: String) -> String
```

EC2's name for an architecture as Docker's (`x86_64` is `amd64`).

### `ubuntu_ami`

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

The Ubuntu 24.04 image for `docker_arch` (`arm64`, `amd64`): pinned by `ORCA_POOL_EC2_AMI_<ARCH>`, else Canonical's public SSM parameter.

### `is_no_capacity`

```mojo
def is_no_capacity(error: String) -> Bool
```

## Aliases

### `NO_CAPACITY`

```mojo
comptime NO_CAPACITY = Array[__literal_size__=Int(3)](String("InsufficientInstanceCapacity"), String("InsufficientCapacity"), String("Unsupported"), __list_literal__=NoneType(None))
```