Install plainfra across many AWS accounts at once

One External ID, every account

plainfra issues one External ID per customer, not one per AWS account. Every account you connect trusts plainfra using that same value, which is what makes a StackSet possible: one parameter set, deployed unchanged across the whole target. When you add a new account in the plainfra console later, plainfra reuses the External ID you already have rather than minting a new one.

Two places to read it:

• From the plainfra console. On the Account page, under Connected AWS accounts, start the Connect another AWS account flow and click Generate launch link. The next step shows your External ID with a copy button, alongside the single-account launch URL.
• From an account you have already connected. In that account, open IAM → Roles → plainfra-ReadOnly → Trust relationships. The value sits under sts:ExternalId in the trust policy.

Treat it like a credential. It is the second factor on the trust policy, so the role cannot be assumed without it, and it should not be posted anywhere public.

Deploy the StackSet

Work in the management account, or in your delegated administrator account. The template is public and you can read it before you deploy anything.

1. Turn on trusted access between StackSets and Organizations. This is a one-time setting for the whole organization. In the CloudFormation console, open StackSets and use the Enable trusted access prompt. If it is already on, there is nothing to do here.
2. Create the StackSet. CloudFormation → StackSets → Create StackSet. Choose Service-managed permissions, then Template is ready and Amazon S3 URL, and paste:

   https://triont-plainfra-onboarding.s3.ap-southeast-2.amazonaws.com/customer-role.yaml

3. Set the parameters. Enter your External ID for ExternalId. Leave PlainfraAccountId and RoleName at their defaults: plainfra looks for a role at that exact name, and a renamed role will not be found. Leave AllowBillingConsoleRead at false unless you want plainfra to read the Billing console as well. Cost Explorer access is included either way.
4. Acknowledge the IAM capability. The template creates a role with a fixed name, so CloudFormation asks you to confirm CAPABILITY_NAMED_IAM before it will proceed.
5. Choose the target. Either Deploy to organizational units with the OU IDs you want covered, or Deploy to accounts with an explicit list. An OU target is the better default if the group of accounts is going to change.
6. Pick one region and one region only. IAM is a global service, so the role covers every region no matter where the stack instance runs. Deploying to more than one region gets you duplicate stacks fighting over the same role name. Use your home region, such as ap-southeast-2.
7. Optional: automatic deployment. With automatic deployment on, an account that joins the target OU later gets the role without anyone revisiting this page. An account that leaves the OU has its stack removed, unless you tell CloudFormation to retain it.

The operation runs per account and finishes in about a minute for each. Watch the Stack instances tab for the per-account status.

One thing service-managed StackSets will not do is deploy into the organization management account itself. If you want plainfra to read that account too, install it there with the ordinary per-account launch link from the plainfra console.

The same thing from the command line

For teams that would rather not click through the console, the four commands below do the whole install. Substitute your own External ID, OU ID, and region.

aws cloudformation activate-organizations-access --region ap-southeast-2

aws cloudformation create-stack-set --stack-set-name plainfra-readonly --template-url https://triont-plainfra-onboarding.s3.ap-southeast-2.amazonaws.com/customer-role.yaml --parameters ParameterKey=ExternalId,ParameterValue=YOUR-EXTERNAL-ID --capabilities CAPABILITY_NAMED_IAM --permission-model SERVICE_MANAGED --auto-deployment Enabled=true,RetainStacksOnAccountRemoval=false --region ap-southeast-2

aws cloudformation create-stack-instances --stack-set-name plainfra-readonly --deployment-targets OrganizationalUnitIds=ou-abcd-1234efgh --regions ap-southeast-2 --region ap-southeast-2

aws cloudformation list-stack-instances --stack-set-name plainfra-readonly --region ap-southeast-2

Notes on the flags. --permission-model SERVICE_MANAGED is what lets you target OUs instead of listing accounts. --auto-deployment is the command-line form of the automatic deployment option, and is only valid with the service-managed model. To target an explicit set of accounts inside an OU, replace the deployment target with OrganizationalUnitIds=ou-abcd-1234efgh,Accounts=111111111111,222222222222,AccountFilterType=INTERSECTION. If you are running from a delegated administrator account rather than the management account, add --call-as DELEGATED_ADMIN to each command.

Then register the accounts in plainfra

The StackSet puts the role in place. plainfra still needs to be told which accounts to use it on, and that part is done once per account in the console. It takes a few seconds each.

1. Sign in to the plainfra console and open the Account page. The Connected AWS accounts card lists what plainfra can already reach.
2. Click Connect another AWS account, then enter the 12-digit AWS account ID, an optional alias such as prod or sandbox, and the default region for that account. The alias is what you will see in answers and reports, so it is worth setting.
3. Click Generate launch link. plainfra records the account against your subscription and hands back a CloudFormation link. Because the StackSet has already installed the role, you can ignore that link and click I've deployed it. The account appears in the list straight away.
4. Repeat for each account. The button disappears once you reach the account limit on your plan, and the page tells you which plan lifts it.

An AWS account can be connected to one plainfra subscription only. If an account ID is refused as already connected, it is attached to a different plainfra account and needs to be disconnected there first.

Every row in the Connected AWS accounts card carries a Verify control. It assumes the read-only role in that account on the spot and records the outcome against the row, so you can confirm a StackSet instance actually landed instead of waiting for a question or a report to fail. The add-account window offers the same check on its last step, which lets you confirm each account as you register it. A row nobody has checked reads as not verified yet, which is not a fault in itself.

When a check fails, the row says what to look at: the stack may still be deploying, the account ID may be wrong, or the stack may have been given a different External ID. Verifying stays optional. plainfra assumes the role on demand, for up to an hour at a time, the first time it needs to read that account, whether or not you have run the check. If the role is missing or the External ID does not match, that account comes back with a connection error while the rest keep working.

Accounts that already have the role

If someone installed plainfra into one of the target accounts earlier with the single-account launch link, that account already holds an IAM role named plainfra-ReadOnly, owned by a stack of the same name. The StackSet will try to create the same role again and the stack instance will fail for that account with an already-exists error. The rest of the target is unaffected.

Two ways out, both fine. Delete the earlier plainfra-ReadOnly stack in that account before you run the StackSet, which removes the role and lets the StackSet own it cleanly. Or leave the earlier install alone and keep that account out of the StackSet target. The role is identical either way, so plainfra cannot tell the difference.

What you are granting

Installing to twenty accounts grants exactly what installing to one grants, twenty times over. The role is read-only and cannot change, create, or delete anything in your accounts. Every permission is written out by name in the template, with no AWS managed policies attached, and an explicit deny block stops the role reading object contents, secrets, log data, and code. The External ID is a second factor on top of the account restriction, so even a party who knew the role name could not assume it. You can revoke any account at any time by deleting its stack, and revoke the whole set by deleting the StackSet.

Read the CloudFormation template before you deploy it. We encourage it. The full detail on data handling, retention, and revocation is on the security page.