Skip to main content

Accounts

For Owners and Operators (or an AccountManager Role) registering the AWS accounts Studio deploys into; Viewers and AccountViewers read everything. An account is registered and verified before anything is installed in it.

Before you start: you need the twelve-digit account id, someone who can create a CloudFormation stack in that account, and the region the deployment will run in. Use a fresh account, for the reasons given on Register an AWS account.

Read the account list​

Open Accounts from the dock. Search by alias or account id (on the server, over every account); columns are Alias, Account (grouped as 1234-5678-9012), Regions, Status, Deployments and Last verified. Status is Verified, Pending (run the role template, then verify), Failed (open the account to see which check failed) or Disabled (no new deployments). Add an account is disabled without the permission ("Requires the AccountManager role (or owner/operator)").

Add an account​

Click Add an account. The form is one page; the older three-step addresses open the same form.

  1. Alias: a name you will recognise.
  2. AWS Account ID: twelve digits. Spaces, hyphens and pasted control characters are removed; anything else is refused with the rule.
  3. Region: one of the eleven supported regions: us-east-1, us-east-2, us-west-2, eu-west-1, eu-west-2, eu-west-3, eu-central-1, eu-central-2, eu-north-1, eu-south-1 and eu-south-2. This is the account's first region: the registration stack is created there, and Clear account clears it. More can be added later.
  4. Click Register AWS account. The account's page opens.

An account already registered is refused: open it from the list instead. The Organisations account itself is refused ("This is the Organisations account. Studio deployments go in their own AWS accounts: register a different account.").

Run the template​

While the account is Pending or Failed, its page shows Run the template, which creates the one role AlphaAgent uses to connect. It shows the Trust policy must name value (the Organisation's task role) and the Template version, and offers Download org-target-account-role.yaml and Launch the stack in the AWS console (CloudFormation opens in the account's first region with the stack name and parameters pre-filled; the line "The stack is created in <region>." names it). The template download comes from the Organisations console itself. Under them, "This link is valid until <time> (about N hours)" states its lifetime; the page signs a fresh link each time it opens and again five minutes before expiry, so use the one on screen.

The template's parameters are on Register an AWS account. Leave EnableApiWafPermissions false: the deployment-level WAF allow-list is not set from the console; restrict callers with the per-key Source IP allow-list on Programmatic Access.

Verify the account​

Click Verify this account (later Verify again; "Running checks…" while it runs). Up to four checks run:

  1. Assume the target role. Pass: "Successfully assumed <role ARN>." Fail: check the stack was run in this account with the External ID copied exactly and RoleNameSuffix matching; or "Denied: the role is missing <action>."
  2. Retry CloudFront edge stacks waiting on Lambda@Edge replica cleanup, once the role can be assumed. It matters only to an account that held a public deployment; when AllowedRegions leaves us-east-1 out it is skipped ("us-east-1 is not allowed for this account, so nothing there was checked. CloudFront is used only by Public deployments.") and no us-east-1 call is made.
  3. Last Clear account left nothing behind, when the account has been cleared before.
  4. Removed deployments' VPC ranges are released, while a removed deployment of the account still holds a VPC range in the Address plan: it releases each range whose VPC is gone.

The result appears in Verification result as the checks' text report, and on a later visit as "Last verification: Pass — N passed, N failed, N not run". A passing account becomes Verified and shows Deploy Studio into this account, which opens the deployment wizard.

Inspect, extend, clear and delete​

The header shows Alias, AWS Account ID, Region, Status and Deployments; Account details lists Alias, Region(s), Role ARN and External id, read-only; the footer shows Last verified, Created and Last updated.

To allow deployments in another region, pick one under Add a region… and click Add region; the first region stays first and is the one Clear account clears. Clear account scans and deletes every AlphaAgent resource in that region (Deleting a deployment and clearing an account).

Delete asks you to type the alias and removes the account from Organisations only. To remove the AWS side, delete the stack alphaagent-org-target-<account id> in that account, in the region it was created in: it removes the role, and with the current template the staging bucket alphaagent-org-staging-<account id>-<region> too. Leaving the stack in place makes a later re-registration fail because the role already exists. An account with deployments cannot be deleted.

  • Run Clear account first. The staging bucket holds only staged copies that expire after seven days, and Clear account empties it. A bucket that still holds staged copies stops the stack delete with "The bucket you tried to delete is not empty": empty it, then delete the stack again.
  • A stack from an earlier template keeps its bucket. Before deleting it, update the stack from the current template (Download org-target-account-role.yaml, then update the stack in CloudFormation with the same parameters), so the delete removes the bucket too. A bucket an earlier registration already left behind is not removed by any later step: empty and delete it yourself.
  • Registering the account again in a region where a bucket from an earlier registration remains: set CreateStagingBucket to false, or remove the bucket first; otherwise the stack fails creating a bucket that already exists.
  • Two roles in one account and region share one bucket, created by the stack with CreateStagingBucket true. Deleting that stack deletes the bucket the other role uses, so delete it last.

What you should see​

  • New account: Pending, with Run the template and Verify this account; Home lists it under Accounts needing verification.
  • After the stack exists and Verify passes: Verified, Last verified set, selectable in the deployment wizard.

Notes​

  • Regions can be added, not removed.
  • "Denied: the role is missing <action>." or a CloudFront edge complaint on an account with a public deployment: update the stack from the current template, then Verify again.
  • A private deployment never needs us-east-1: register its account with AllowedRegions naming only the regions you use.