Connect an AWS account

Connecting an AWS account lets Alpacon discover your EC2 instances and (optionally) install the agent for you. Setup is guided by a wizard that provisions an IAM role in your account through AWS CloudFormation.

Before you start

  • You need permission to create a CloudFormation stack that provisions IAM roles and a Lambda function (for example, an administrator). On the Quick Create page, select the acknowledgment that CloudFormation may create named IAM resources before you create the stack.
  • Have a server registration token ready (or create one during the wizard). The token determines which groups onboarded servers are assigned to and is required for agent installation.

Connection steps

On the Cloud accounts page, click Connect AWS and follow the wizard.

  1. Name the account — Enter a display name for the account. Choose whether to allow agent installation via AWS SSM, and select the server registration token to use.
  2. Generate the Quick Create URL — Click Open AWS Console to open AWS CloudFormation with the stack pre-filled. Each account gets its own stack name: AlpaconConnect- followed by the first 8 characters of the account’s ID in Alpacon, the ID at the end of the account page’s address. Connecting a second account from the same AWS account and region therefore does not collide with the first. The control-plane region is us-east-1. Create the stack in AWS.
  3. Verify the connection — Keep the Alpacon tab open. Alpacon waits for the CloudFormation stack to finish and confirms it can assume the IAM role. The steps shown are: submit stack → create stack → assume IAM role → connection verified. If verification fails, you can Retry verification or delete and start over.
  4. Discover instances — Alpacon starts syncing your EC2 inventory and shows the instances found per region in real time. A scan can also finish without every region, stop on an error, or never report back; the panel says which happened and offers Scan again.

Permissions Alpacon receives

The CloudFormation stack grants Alpacon a role named AlpaconCrossAccountRole- followed by the stack’s ID—the UUID at the end of the stack ID shown in CloudFormation—so each connection gets its own role. An account connected with an earlier template version has a role named AlpaconCrossAccountRole, with no suffix. The role grants:

  • Read EC2 inventory (required) — list instances, regions, and tags across all regions.
  • Install agent via AWS SSM (optional) — send install commands so you can onboard instances with one click.

You can revoke access at any time by deleting the CloudFormation stack in your AWS account.

Troubleshooting

Verification failed — Confirm the CloudFormation stack finished creating and that the IAM role trust policy is intact. Use Retry verification, or delete the stack and run the wizard again. Check AWS CloudTrail for permission errors.

Discovery failed — The scan stopped before it could finish, so anything it had not reached yet is missing. The panel shows the reason AWS returned; a permission missing from the IAM role is the usual cause. Fix the role and use Scan again. If discovery cannot be made to work at all, you can still register a server by hand with a server registration token.

Some regions were skipped — The scan finished, but could not read every region, so instances in the skipped ones are missing from the list. The panel names each region it skipped and why—commonly a region the account has not enabled, or one the IAM role cannot read. Enable or grant the region, then use Scan again.

No response from the scan — The account is connected, but the scan never reported back, so nothing is known about its instances yet. This is not the same as an account that holds none. Use Scan again.

The account is marked failed — When three scans in a row fail, Alpacon marks the account failed and stops scanning it. Scan again is refused in this state; open the account and use Retry verification in its failure banner to bring it back, which also clears the failure count and starts a new scan on its own. Fix what the panel reported first, or the scans that follow fail the same way. A scan that fails but still finds instances resets the count, and so does a clean scan of an account that holds none.

Last updated: