Manage cloud accounts

The Cloud accounts page lists every connected AWS account. Open an account to review its status, adjust settings, and manage the connection.

Accounts list

Each account shows its name and AWS account ID, the provider (AWS), whether remote command (SSM) is enabled, the connection Status, the owner, and when it was last synced.

Account status can be:

  • Active: connected and syncing.
  • Pending / Verifying: connection is being set up or validated.
  • Failed: AWS denied the IAM role outright: at verification (the first check after connecting, or a later use of Retry verification), or across three discovery scans in a row where AssumeRole was refused, every region was denied, or listing regions was refused. A scan that still finds instances resets the refusal count. A temporary problem—AWS throttling, an AWS outage, a timeout, or an expired credential on Alpacon’s side—does not fail the account: Alpacon records the error and keeps going. The one exception is the first verification after connecting, which retries automatically a few times before marking the account failed if the problem does not clear up. Alpacon stops scanning an account in this state, so fix what the connect panel reported and bring the account back as described in Recover a failed account. See also Connect an AWS account.
  • Disabled: connection is turned off.

Account settings

Open an account to view its Configuration:

  • Auto-provision agent: automatically install the agent on newly discovered instances.
  • Remote agent installation—allow agent installation via AWS SSM. This only turns the feature on in Alpacon; whether AWS allows it is a separate permission, described in Remote command permission.
  • Sync interval: how often Alpacon refreshes the inventory (default every 5 minutes).
  • Registration token: the server registration token used when onboarding instances.

Click Edit to change any of these settings, or to pause background discovery (Sync enabled).

The account detail page also shows an inventory summary (total instances, how many have the agent installed, and how many are pending) and the granted IAM role—AlpaconCrossAccountRole- followed by the stack’s ID, unique per connection. An account connected with an earlier template version has a role named AlpaconCrossAccountRole, with no suffix.

Remote command permission

Installing the agent through AWS SSM needs a permission on the account’s IAM role. That permission comes from the EnableRemoteCommand parameter of the account’s CloudFormation stack, which is fixed when the stack is created. Turning on Remote agent installation in Alpacon later does not grant it in AWS.

The AWS stack permission row on the account detail page shows the permission state and when it was last checked. The state is one of:

  • Not checked yet—no install has shown the permission yet.
  • Granted—the role can run remote commands.
  • Denied—AWS refused an install because the role itself lacks the permission.

Alpacon never tests this permission on its own, so it adds no denied calls to your AWS CloudTrail. It learns the state from real install attempts.

While remote command is on and the state is Denied, every install through AWS SSM is blocked—one instance at a time, in bulk, or by auto-provision—and Alpacon shows how to fix it. The API returns the error code cloud_remote_command_permission_missing. The manual SSH install does not use the role and still works.

AWS can also refuse an install because of a policy outside the role, such as a service control policy, a permission boundary, or an explicit deny. The install fails with the same error code, but the state does not change, and the install dialog asks you to check the policies that apply to that instance and its region instead of the stack. Tell the two apart by the state: Denied means the stack, any other state means a policy on the target.

To enable it later:

  1. Update the account’s CloudFormation stack in AWS with EnableRemoteCommand set to true.
  2. When the state is Denied, the account’s owner or an administrator can click Recheck. The button appears only in that state for members allowed to recheck. Switching Remote agent installation off and on again does the same. The state returns to Not checked yet and the next install checks the permission again.

The recheck is also available through the API as POST /api/cloud/accounts/{id}/recheck-remote-command/, which an API token needs the cloud_account:recheck_remote_command scope to call.

Sync and verify

  • Sync now: queue an immediate inventory refresh instead of waiting for the next scheduled sync.
  • Verify credentials: re-test that Alpacon can assume the account’s IAM role. On a failed account, the failure banner offers the same check instead; see below. Not available on a Pending account that hasn’t received its CloudFormation callback yet—wait for the callback, or continue in the connection wizard instead.

Find this account’s stack

Each account has its own CloudFormation stack in AWS, named AlpaconConnect- followed by the first 8 characters of the ID at the end of the account detail page’s address. Other accounts connected from the same AWS account and region have stacks with other suffixes, so match the suffix before you delete anything. An account connected before per-account stack names were introduced uses AlpaconConnect with no suffix.

Recover a failed account

When an account fails, its page shows a banner with the last error, if there is one, and two actions. Pick the one that matches what is left in AWS:

  • Retry verification—the IAM role still exists in AWS. Alpacon checks the same role again; once that succeeds, the account is active again and a new scan starts on its own.
  • Reconnect—the CloudFormation stack or its IAM role is gone. First delete this account’s stack in AWS: the new stack gets the same stack name and IAM role name, so AWS refuses to create it while the old stack exists. After you confirm, the account goes back to pending, its current credentials are cleared, and the connect wizard opens at the Quick Create step. Create the new stack from the same AWS account; a different AWS account is refused.

Disconnect an account

Click Disconnect account and confirm. The account stops syncing, and its instances leave the instance inventory. The EC2 instances in AWS are untouched, and servers you already onboarded from them keep running in Alpacon. To fully revoke Alpacon’s access, delete this account’s CloudFormation stack in your AWS account.

Last updated: