How organization discovery works

Kumo.io connects to AWS one account at a time: each account you sync is a separate source. Organization discovery saves you finding those accounts by hand.

With a credential in your organization's management account, Kumo.io walks the organization and records what it finds as cloud accounts:

• the organization root,
• each organizational unit (OU),
• each active member account.

New entries are marked discovered. They are proposals: nothing is synced until you create a source for an account. Discovery is read-only and doesn't change anything in AWS.

Run discovery again whenever your organization changes. New accounts appear as new proposals. When a full discovery no longer finds an account it found before, Kumo.io marks that account stale rather than deleting it. A discovery limited to some OUs never marks anything stale, because it can't see the whole organization.

What the management-account credential needs

Connect the management account first, as described in Connect an AWS account. The credential also needs to read your organization's structure. Kumo.io's published read-only policy grants this in its KumoOrganizationsDiscovery statement:

• organizations:DescribeOrganization
• organizations:ListRoots
• organizations:ListOrganizationalUnitsForParent
• organizations:ListAccountsForParent

If you built your role from the published policy without that statement, add it back before running discovery.

Discover your accounts in Kumo.io

1. Open a workspace, go to its Connections tab and select Advanced.
2. In the Cloud Accounts section, select Discover Scopes.
3. Enter aws as the Provider Key, and pick the management-account Credential.
4. Set Discovery Mode to Organization (Org Root, OUs, Member Accounts), then select Discover.

Kumo.io reports how many scopes it found, how many are new proposals and how many it marked stale. The accounts appear in the Cloud Accounts list.

Sync the accounts you want

Each member account needs a credential that can read it. On kumo.io, give each account its own read-only role:

1. Select Add Source on the workspace's Connections tab.
2. Follow Connect an AWS account for the member account, deploying the role template in that account.
3. Repeat for every account you want to sync.

Kumo.io recognises each account from its role and creates its source, so the account's discovered proposal becomes an active, synced account.

Every synced account counts as one source toward your plan's sources limit. Check how many sources your plan includes on Plans and limits before connecting a large organization.

Fan out from the CLI (self-hosted)

From the command line, Kumo.io can create a source for every account in one go. It reaches each member account by assuming a role with the same name in every account, starting from the management-account credential. AWS creates such a role, OrganizationAccountAccessRole, in accounts created through AWS Organizations. Accounts that joined by invitation don't have it unless you add it.

Discover the organization, naming the member role explicitly:

kumo provider-scope discover --provider-key aws --credential <credential-id> \
  --discovery-mode organization --org-member-role OrganizationAccountAccessRole

Add --organizational-units ou-a,ou-b to limit discovery to some OUs.

Or do everything in one call: create the credential from a secret reference, discover the organization, create one source per member account, and sync each one:

kumo source create --provider-key aws --display-name "AWS Org" \
  --secret-ref <secret-ref> --discovery-mode organization \
  --org-member-role OrganizationAccountAccessRole --all-accounts --sync

--all-accounts turns every discovered account into its own source. Use --scope <key> instead to create a source for one discovered account. See the CLI reference for every flag.

The member role must trust the management-account identity Kumo.io starts from, and must grant read access. If its trust policy requires an external ID, Kumo.io presents the management-account credential's own external ID on every member hop, so use the same external ID in each member role's trust. OrganizationAccountAccessRole grants full administrator access by default. Consider a dedicated read-only role with Kumo.io's published policy instead.