# orca.aws

> A module of morca's API.

`orca aws`: a project's orca on AWS, with the `aws` and `docker` commands its user already has (`aws login`, or `AWS_PROFILE` for a named profile).

orca aws up --email you@example.com [--stack orca] [--hostname H]
                [--console-hostname H] [--budget 100] [--zone us-east-2a]
                [--public-data true|false] [--env KEY=VALUE ...]
    orca aws push [--tag T]                     # the project's image, to ECR
    orca aws register [--tag T] [--config F|--no-config] [register flags]
                      <pipeline> [...]
    orca aws app <name> [--host H] [--port 8080] [--tag T]
    orca aws status
    orca aws replace-control [--plan] [--wait] [--keep-old 24h] [--smoke P=KEY]
                             [--env KEY=VALUE ...] | --resume | --rollback
    orca aws down --yes

`up` creates or updates the stack from the template orca carries
(deploy/aws/orca.yaml, in `orca.aws_assets`); the first time it needs
`--email`, for the Budgets alert, and makes the database's password. `push`
builds the project's image from a staged copy of `pixi.toml`, `pixi.lock`,
`bin/`, `pipelines/` and `src/`, with the project's `Dockerfile.orca` or
else the template (deploy/project.Dockerfile), for arm64, tagged with the
commit (or `--tag`) and `latest`, and pushes it to the stack's repository.
`register` and `app` run on the control instance through SSM: `register`
moves the scheduler and the UI to the image (`orca-refresh`) and registers
each pipeline, `/opt/orca/pipelines/<pipeline>`, with the flags given, as
`orca register` takes them, and the project's `orca.toml` (or `--config`'s
file; `orca.config`), which it checks and sends whole with its git commit; `app` runs the image's `/opt/orca/bin/<name>`
beside the UI, at `https://<host>` (for `console`, the stack's
`ConsoleHostname`). `--env KEY=VALUE` (repeated) sets the control
instance's settings beyond the template's (`ControlEnv`, all of them at
once; never a secret). An update changes no running control instance: its
boot script is the stack's `ControlBoot`, which a new one runs, and each
slot's AMI is pinned to the one its instance has. `replace-control`
(`orca.aws_replace`) boots a new control instance from the template, with
the old one's database, and moves the Elastic IP to it. `down` deletes the
stack, which fails while its buckets hold objects.

Files go to `build/orca-aws/`. `--stack` (default `orca`) and `--region`
(default `AWS_REGION`, else the `aws` command's own) go anywhere.

## Functions

### `env_problem`

```mojo
def env_problem(kv: String) -> String
```

Why `kv` can't be one of the control instance's settings (`--env KEY=VALUE`, the stack's `ControlEnv`), or empty if it can.

### `control_env`

```mojo
def control_env(o: _Opts) -> String
```

The `ControlEnv` parameter `--env` gives.

### `deploy`

```mojo
def deploy(o: _Opts, params: List[String], show: Bool)
```

`cloudformation deploy` of the template orca carries with `params` (the others keep their values), printing them if `show`.

### `image_of`

```mojo
def image_of(o: _Opts, instance: String) -> String
```

The AMI `instance` was started from.

### `slot_pins`

```mojo
def slot_pins(o: _Opts, outs: Dict[String, String]) -> List[String]
```

`BlueAmi=` and `GreenAmi=` the images the slots' instances have, so that an update, whose `Ami` resolves again, replaces neither.

### `ssm_run`

```mojo
def ssm_run(o: _Opts, instance: String, commands: List[String]) -> Tuple[Int, String]
```

Runs `commands` on `instance` through SSM and prints what they wrote; 0 and their output if they succeeded, else 3 and it.

### `aws_command`

```mojo
def aws_command(args: List[String]) -> Int
```

`orca aws <cmd> ...`: `args` is the whole command line.

## Aliases

### `AWS_USAGE`

```mojo
comptime AWS_USAGE = "usage:\n  orca aws up --email ADDR [--hostname H] [--console-hostname H] [--budget N]\n              [--zone AZ] [--public-data true|false] [--env KEY=VALUE ...]\n  orca aws push [--tag T]\n  orca aws register [--tag T] [--config F|--no-config] [register flags]\n                    <pipeline> [...]\n  orca aws app <name> [--host H] [--port 8080] [--tag T]\n  orca aws status\n  orca aws replace-control [--plan] [--wait] [--keep-old 24h] [--smoke P=KEY]\n                           [--env KEY=VALUE ...] | --resume | --rollback\n  orca aws down --yes\n  (each takes --stack NAME, default orca, and --region R)"
```