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 (AlpaconConnect) pre-filled. 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.

Permissions Alpacon receives

The CloudFormation stack grants Alpacon a role (AlpaconCrossAccountRole) with:

  • 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.

Last updated: