[CANOFY-108] Wait for SSM Agent Registration¶

Type: Story
Epic: New Client Onboarding — Automated AWS + Frappe Provisioning
Stage key: ssm_wait (pipeline stage 8 of 15)
Component: utils/ssm_client.py

User Story¶

As an operations engineer,
I want onboarding to wait until the new instance's SSM agent is fully
registered and online before attempting any remote commands,
so that the bootstrap stage doesn't fail on a race condition where the
instance is "running" but not yet reachable via SSM.

Description¶

Poll describe-instance-information for the target instance until
PingStatus == "Online", with a bounded timeout. This is a pure
synchronization stage — no resources created, no state mutated — but is
required because every subsequent stage depends on SSM working.

Configuration / Prerequisites¶

• Depends on stage 1 (instance_id) and stage 6 (IAM role with
  AmazonSSMManagedInstanceCore attached — SSM registration cannot succeed
  without it).
• A maximum wait duration must be configured (e.g. 5 minutes) — this stage
  must not hang the pipeline indefinitely.

Acceptance Criteria¶

• Stage blocks (polling on an interval, not a single check) until the
  instance reports Online.
• Stage fails clearly with a timeout error if the agent never comes
  online within the configured max wait — the error should point at
  likely causes (IAM role, network/security group, agent not installed
  on the AMI) to save debugging time.
• Polling interval is reasonable (not hammering the API every second,
  not waiting so long between polls that a fast registration is missed
  for minutes).

Test Cases¶