# Cloud Image Import And Serial-Console Boot

Operator notes for importing the locally-boot-proven hybrid BIOS+UEFI disk
image into GCP and AWS and reaching a serial-console boot. This is packaging and
documentation only: `tools/package-cloud-image.sh` operates on a local artifact,
adds no provider credentials, and performs no live cloud calls. Cloud NIC and
storage driver readiness remain separate, blocked tracks
(`docs/backlog/hardware-boot-storage.md` "Cloud Device Tracks"); the first cloud
milestone is an imported-image serial-console boot, not a driver claim.

## Local Artifacts

`make image` builds `target/capos-image.raw` (default 256 MiB, GPT, 128 MiB
hybrid ESP + Limine MBR) and `make run-disk` / `make run-disk-bios` prove it
boots under OVMF (UEFI) and SeaBIOS (legacy BIOS). Only run the import steps
below once those local boot proofs pass; provider import only makes sense for a
known-good image.

`make package-cloud-image` (or `package-gcp-image` / `package-aws-image`)
repackages that artifact into `target/cloud-image/`:

| Provider | Output | Shape |
| --- | --- | --- |
| GCP | `disk.raw.tar.gz` | `disk.raw` grown to a whole multiple of 1 GiB, GPT backup relocated, inside a gzip `tar --format=oldgnu` archive |
| AWS | `capos-aws.raw` | RAW (exact image size) |
| AWS | `capos-aws.vhd` | fixed VHD (`conectix` footer, disk-type `fixed`) |
| AWS | `capos-aws.vmdk` | stream-optimized VMDK |

The helper self-verifies each shape (gzip + oldgnu tar member for GCP; the VHD
fixed-disk footer and VMDK create-type for AWS) and fails if a conversion is
wrong. It differs from `make capos-cloudboot-image`, which builds a from-scratch
10-GiB GCE disk for the `tools/cloudboot/` end-to-end harness; the packaging
helper repackages the small, already-boot-proven `make image` artifact instead.

## GCP Custom-Image Import

GCP custom-image import requires a single file named exactly `disk.raw`, sized
to a whole multiple of 1 GiB, in a gzip `tar --format=oldgnu` archive -- exactly
the `disk.raw.tar.gz` the helper emits.

```sh
make package-gcp-image
gsutil cp target/cloud-image/disk.raw.tar.gz gs://<your-bucket>/capos-disk.tar.gz
gcloud compute images create capos-hybrid \
  --project=<your-project> \
  --source-uri=gs://<your-bucket>/capos-disk.tar.gz \
  --guest-os-features=UEFI_COMPATIBLE
```

`UEFI_COMPATIBLE` lets the image boot through the GCE UEFI path
(`/EFI/BOOT/BOOTX64.EFI`); the same image still carries the Limine MBR for the
legacy boot path. After creating an instance from the image, read the boot
landmark on the serial console:

```sh
gcloud compute instances create capos-test \
  --project=<your-project> --image=capos-hybrid
gcloud compute instances get-serial-port-output capos-test \
  --project=<your-project> | grep 'capos kernel starting'
```

The reference end-to-end GCE serial-console-boot flow (build, upload, import,
boot, evidence capture, teardown) is the `tools/cloudboot/` harness; see
`tools/cloudboot/README.md`.

## AWS VM Import

AWS VM Import/Export accepts RAW, fixed VHD, and stream-optimized VMDK. Upload
one shape to S3 and import it as a snapshot, then register an AMI:

```sh
make package-aws-image
aws s3 cp target/cloud-image/capos-aws.vhd s3://<your-bucket>/capos-aws.vhd
aws ec2 import-snapshot --disk-container \
  Format=VHD,UserBucket="{S3Bucket=<your-bucket>,S3Key=capos-aws.vhd}"
# after the snapshot import task completes, register an AMI from the snapshot:
aws ec2 register-image --name capos-hybrid \
  --architecture x86_64 --root-device-name /dev/xvda \
  --boot-mode uefi \
  --block-device-mappings \
  '[{"DeviceName":"/dev/xvda","Ebs":{"SnapshotId":"<snap-id>"}}]'
```

### Boot-mode notes

The hybrid image boots either firmware path, so the AWS boot mode is a
deployment choice, not an image rebuild:

- `--boot-mode uefi` -- Nitro-based instance types boot the ESP
  `/EFI/BOOT/BOOTX64.EFI` (Limine UEFI). Recommended on modern Nitro instances.
- `--boot-mode legacy-bios` -- older/legacy instance types boot the Limine MBR
  path. Use this only if the target instance type does not support UEFI.

`uefi-preferred` is also valid and lets the instance type decide. RAW
(`Format=RAW`, file `capos-aws.raw`) and stream-optimized VMDK
(`Format=VMDK`, file `capos-aws.vmdk`) import the same way; choose the container
your upload path prefers. AWS rounds the EBS volume size up to whole GiB on
import, so the RAW shape is not pre-rounded.

## Scope Boundary

These notes cover import + serial-console boot only. They do not enable cloud
NIC or storage drivers, do not automate live cloud runs, and add no new trusted
build inputs beyond format conversion of the already-pinned-Limine image. The
provider-NIC/storage and cloud usable-instance tracks remain blocked in
`docs/backlog/hardware-boot-storage.md`.