[CANOFY-101] Provision EC2 Instance¶

Type: Story
Epic: New Client Onboarding — Automated AWS + Frappe Provisioning
Stage key: aws_provision (pipeline stage 1 of 15)
Component: utils/aws_client.py, utils/onboarding_executor.py

User Story¶

As an operations engineer,
I want the client's EC2 instance provisioned automatically from the
approved Onboarding Request,
so that every new client server is created consistently (encrypted
storage, no SSH access, correct sizing) without manual AWS console work.

Description¶

Implement the first pipeline stage: create a single EC2 instance for the new
client using the parameters captured on Onboarding Request
(aws_region, instance_type, storage_gb, site_name as the Name tag).

Requirements:

• No KeyName passed to RunInstances — SSH access must never be possible.
• Root EBS volume: encrypted, DeleteOnTermination=True, type gp3, sized
  from storage_gb.
• Security group(s) come from the AWS Account.default_security_group_id
  and must be HTTPS-only (no port 22 ingress) — the account is the source
  of truth, not something entered per-request.
• Subnet comes from AWS Account.default_subnet_id.
• Support an "AMI Image" deployment mode: if Onboarding Request .deployment_mode == "AMI Image", resolve the latest AMI tagged
  ami_tag_value instead of the default Ubuntu 22.04 base image.
• On InsufficientInstanceCapacity (or equivalent capacity error) for the
  configured subnet's AZ, automatically retry in sibling subnets of the same
  VPC (other AZs) before failing the stage — AWS's own error message for
  this condition explicitly recommends trying a different AZ, so this
  should not require human intervention for a routine capacity blip.
• Resulting instance_id is written to Onboarding Request.ec2_instance_id
  and threaded through the pipeline context for later stages.

Configuration / Prerequisites¶

• AWS Account record with default_security_group_id and
  default_subnet_id populated. Stage must refuse to run (clear error, not
  a silent default) if default_security_group_id is unset.
• AWS Account.use_oidc=1 + valid oidc_role_arn if the account uses OIDC
  federation — all AWS calls must be made through the account's assumed
  role, never the bare default credential chain.
• Onboarding Request fields populated: aws_account, aws_region,
  instance_type, storage_gb, site_name.

Acceptance Criteria¶

• Instance is created with no KeyName.
• Root volume is encrypted and matches storage_gb.
• Security group has zero port-22 ingress rules.
• Onboarding Request.ec2_instance_id is populated after this stage.
• A capacity error in one AZ results in an automatic retry in a
  different AZ of the same VPC, not an immediate stage failure.
• If capacity is unavailable in every subnet of the VPC, the stage fails
  with a clear error naming every subnet tried.
• Missing default_security_group_id fails fast with an explicit
  message, before any AWS API call is made.

Test Cases¶