# orca.awsec2

> A module of Orca's API.

The few EC2 calls the `ec2` runner makes (`orca.ec2`), over objectstore's SigV4 signing and HTTP.

EC2's API is a form `POST` of `Action=...&Version=...` to
`https://ec2.<region>.amazonaws.com/`, answered in XML. Credentials come
from the `AWS_*` environment, else the instance role (IMDSv2); the region
from `AWS_REGION`. `ORCA_EC2_ENDPOINT` points the calls elsewhere, as the
tests do at a stand-in (`tests/fake_ec2.py`).

The answers are read for the fields the runner uses and nothing else: an
instance's ID, type, private address, state, why it's in that state, launch
time and tags.

## Structs

### `Instance`

```mojo
struct Instance
```

Implements: `Copyable`, `Movable`

Fields:

- `id: String`
- `instance_type: String`
- `private_ip: String`
- `state: String`: `pending`, `running`, `shutting-down`, `terminated`, ...
- `state_reason: String`: Why it's stopping or stopped, as EC2's code: `Client.InstanceInitiatedShutdown` (it shut itself down), `Client.UserInitiatedShutdown` (TerminateInstances), `Server.SpotInstanceTermination`, ...; empty while it runs.
- `launch_time: String`: ISO 8601, UTC.
- `tags: Dict[String, String]`

### `Ec2`

```mojo
struct Ec2
```

Implements: `Movable`

Fields:

- `region: String`
- `endpoint: String`
- `host: String`
- `http: HttpClient`

#### `__init__`

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

#### `call`

```mojo
def call(self, action: String, params: List[Tuple[String, String]]) -> String
```

The answer to `action` with `params`; raises with EC2's error.

#### `run_instances`

```mojo
def run_instances(self, params: List[Tuple[String, String]]) -> List[Instance]
```

#### `describe`

```mojo
def describe(self, filters: List[Tuple[String, List[String]]]) -> List[Instance]
```

The instances matching every filter, any of its values.

#### `terminate`

```mojo
def terminate(self, ids: List[String])
```

## Functions

### `parse_instances`

```mojo
def parse_instances(xml: String) -> List[Instance]
```

The instances a `RunInstances` or `DescribeInstances` answer lists: each `<instanceId>` begins one, up to the next.

## Aliases

### `EC2_VERSION`

```mojo
comptime EC2_VERSION = "2016-11-15"
```