Multi-Account Setup

Overview

KubeSense collects inventory and CloudWatch metrics from an AWS account by assuming a read-only IAM role inside it. For one or two accounts you add each by hand — see Single Account Setup. When your estate spans an AWS Organization, multi-account setup onboards them all in a single rollout — and keeps up with accounts that join, get suspended, or leave later.

There are two ways to run it. Pick based on one question: will you let KubeSense list your organization's accounts?

Both use read-only cross-account roles and store no long-lived AWS keys. Every account is verified against its own identity before any data is ingested, so a misconfigured role fails closed rather than silently attributing one account's resources to another.

Architecture

 Controller account  (the KubeSense controller runs here)
        │  sts:AssumeRole — read-only, nothing stored
        │
        ├── KubeSenseOrgListerRole   (management / delegated-admin account)
        │       └─ organizations:ListAccounts → the account list   [Approach A only]
        │
        ├── KubeSenseCollectorRole → Account A ──┐
        ├── KubeSenseCollectorRole → Account B   ├─ inventory + CloudWatch metrics
        └── KubeSenseCollectorRole → Account C ──┘

Controller account — the AWS account your KubeSense controller runs in. It holds one IAM identity, the controller role, named kubesense-controller by default, and that identity is what reaches into every other account.

Monitored account — any account you want observed. Each contains an identical read-only role, KubeSenseCollectorRole by default, whose trust policy names your controller role. Nothing else is installed in a monitored account.

Management / delegated-administrator account — organizations:ListAccounts only succeeds from one of these. Approach A needs one; a delegated administrator is strongly preferred, since it keeps the lister role out of your most sensitive account.

Prerequisites

Before you begin, ensure you have:

1. A KubeSense controller running in your controller account with an identity of its own — an EKS IRSA role or an EC2 instance profile
2. Permission to create IAM roles in the controller account and in your management account
3. Permission to create CloudFormation StackSets from your management or delegated-administrator account
4. Trusted access enabled between CloudFormation and AWS Organizations — a one-time action under CloudFormation → StackSets → Enable trusted access. Without it the service-managed permission model is unavailable
5. Administrator access to the KubeSense dashboard

Step 1 — Prepare the controller account

Do this once, in the controller account, whichever approach you choose.

1.1 Give the controller its own IAM identity

Skip this if it already has one. A pod with no identity falls back to whatever the node has, which is not something to build organization-wide access on.

Name the role kubesense-controller. Do not name it KubeSenseCollectorRole — that name is reserved for the collector role created in every account, possibly including the controller account, and two roles cannot share a name.

The controller role needs no AWS read permissions of its own. All collection happens through the collector roles it assumes, so the only permission it ever gets is the sts:AssumeRole grant in Step 1.3.

On EKS, confirm the cluster has an IAM OIDC provider — IRSA does not work without one:

aws eks describe-cluster --name <cluster> \
  --query identity.oidc.issuer --output text

# if that printed None, associate one (once per cluster)
eksctl utils associate-iam-oidc-provider --cluster <cluster> --approve

Then create the role and bind it to the controller's ServiceAccount:

kubectl get pod <controller-pod> -n kubesense \
  -o jsonpath='{.spec.serviceAccountName}'

eksctl create iamserviceaccount \
  --cluster <cluster> \
  --namespace kubesense \
  --name <controller-serviceaccount> \
  --role-name kubesense-controller \
  --approve \
  --override-existing-serviceaccounts

kubectl rollout restart deployment/<controller-deployment> -n kubesense

The restart matters: EKS injects credentials at pod startup, so an annotation added to a running pod has no effect until it is replaced. If the ServiceAccount is managed by Helm, add the annotation to your values file too, or the next upgrade removes it.

On EC2, create the role with an EC2 trust policy instead and attach it to the instance as an instance profile. Its ARN is what the rest of this page calls the controller role.

1.2 Confirm the identity the controller actually uses

Every template and trust policy below names this identity, so getting it right here saves the most common class of failure:

kubectl exec -n kubesense <controller-pod> -- \
  aws sts get-caller-identity --query Arn --output text

If it prints an assumed-role ARN such as arn:aws:sts::111111111111:assumed-role/kubesense-controller/..., convert it to the plain IAM role form — arn:aws:iam::111111111111:role/kubesense-controller — and use that everywhere below.

1.3 Allow the controller to assume the collector roles

Attach an inline policy to the controller's role. In the console: IAM → Roles → the controller's role → Add permissions → Create inline policy → JSON, paste the policy, and name it KubeSenseAssumeCollectorRoles.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "sts:AssumeRole",
    "Resource": [
      "arn:aws:iam::*:role/KubeSenseCollectorRole",
      "arn:aws:iam::*:role/KubeSenseOrgListerRole"
    ]
  }]
}

Or with the CLI:

aws iam put-role-policy \
  --role-name kubesense-controller \
  --policy-name KubeSenseAssumeCollectorRoles \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": [
        "arn:aws:iam::*:role/KubeSenseCollectorRole",
        "arn:aws:iam::*:role/KubeSenseOrgListerRole"
      ]
    }]
  }'

The second ARN is only used by Approach A. Leaving it in costs nothing — it permits assuming a role that does not exist unless you create it — and saves editing this policy if you switch approaches. Narrow the * to explicit account IDs if you prefer; the grant is already bounded by role name.

Approach A — Organization Discovery

You create one extra read-only role that permits organizations:ListAccounts. KubeSense assumes it, enumerates the organization, shows you a plan, and enrolls the accounts you approve. Five steps: roll out the collector role, create the lister role, configure, review, activate.

Step A1 — Roll the collector role out to every account

In the KubeSense dashboard, go to Settings → Integrations → AWS → Add New AWS Account, open the Multi Account tab and choose Organization Discovery. Under Deploy the collector role, click View setup instructions — the modal offers the CloudFormation template (kubesense-monitored-account-role.yaml) as a download and shows the four parameter values ready to copy.

Then, signed in to your management or delegated-administrator account:

1. Go to CloudFormation → StackSets → Create StackSet.
2. Under Permissions, keep the default Service-managed permissions. This lets CloudFormation create roles across the organization without pre-provisioning anything per account.
3. Choose Upload a template file and select the downloaded template.
4. Name the StackSet — for example kubesense-collector-role — and fill in the parameters:

5. On Configure StackSet options, tick "I acknowledge that AWS CloudFormation might create IAM resources with custom names" (CAPABILITY_NAMED_IAM). It is required because the template pins the role name, which is deliberate.
6. Under Deployment targets, choose Deploy to organizational units and select the OUs holding the accounts you want observed. Select the organization root to cover everything.
7. Enable automatic deployment. This is what gives accounts added to those OUs later the role with no action from you, and removes it cleanly when an account leaves. Skipping it is the single most common reason a later-created account never collects.
8. Choose a single region. IAM is global, so extra regions only create redundant stack instances.
9. Submit, and wait for every stack instance to reach CURRENT / SUCCEEDED.

Step A2 — Create the organization lister role

This is the one role Approach B does not need. It lets KubeSense enumerate the organization, and it lives in your management or delegated-administrator account — nowhere else, and only once.

Create a role there named KubeSenseOrgListerRole with this trust policy, using the exact controller ARN from Step 1.2:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::<CONTROLLER-ACCOUNT-ID>:role/kubesense-controller" },
    "Action": "sts:AssumeRole"
  }]
}

and this permissions policy — read-only organization metadata, nothing else:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "organizations:ListAccounts",
      "organizations:ListAccountsForParent",
      "organizations:ListParents",
      "organizations:ListOrganizationalUnitsForParent",
      "organizations:DescribeOrganization"
    ],
    "Resource": "*"
  }]
}

These five actions are exactly what discovery calls, and no more. There is no write permission and no access to account contents. Note the role's ARN — KubeSense asks for it next.

Step A3 — Configure the enrollment in KubeSense

Back on the Organization Setup screen, fill in:

Save the configuration. Nothing is collected yet — a new enrollment starts in preview mode.

Step A4 — Review the preview

KubeSense lists your organization and shows what it would do with each account, without creating anything. Discovery takes 10–30 seconds.

Read the list carefully — it is the last checkpoint before collection starts, and the only place a misconfiguration is cheap to fix:

• An account you expected is missing entirely — it is outside the OUs you selected. Check the OU list.
• Nothing is listed at all, or the preview errors — almost always the lister role: either the controller cannot assume it, or it does not live in the management or delegated-administrator account.
• An account is listed that should not be — add it to excluded accounts and review again.

Step A5 — Activate

Choose Enable Enrollment. KubeSense creates one integration per approved account and begins collecting within a few minutes. (Finish without enrolling leaves it in preview — nothing is created, and you can return and enable it later.)

From here the enrollment maintains itself. On a recurring cycle — roughly every 15 minutes — it re-reads your organization and reconciles:

• New accounts in the covered OUs are enrolled automatically, with your configured defaults.
• Accounts that leave the organization or the selected OUs, become suspended, or are added to your exclude list are paused. Pausing stops collection and retains everything already collected.
• Accounts that return are resumed automatically.
• Accounts you added by hand are never touched, whatever else changes.

Approach B — CloudFormation StackSet

Use this when you will not grant organizations:ListAccounts. Each account registers itself as its stack deploys, so KubeSense never enumerates your organization.

Do these steps in order. Each account calls KubeSense the moment its stack is created, so the KubeSense side has to be ready before the StackSet rolls out — otherwise every stack instance fails and must be retried.

Step B1 — Prepare KubeSense

Go to Settings → Integrations → AWS → Add New AWS Account, open the Multi Account tab and choose CloudFormation StackSet. On the Setup step provide the Controller Role ARN from Step 1.2, the regions to collect from, any OU or account filters, and the resource types to enable on each account. No lister role is required. Save to continue.

On the Deploy step, copy the Template URL and click Generate Token. That completes the parameter set: ControllerRoleArn, KubeSenseEndpoint, PushToken, PushPath and CollectorRoleName, each with a copy button.

Step B2 — Create the StackSet

Signed in to your management or delegated-administrator account, go to CloudFormation → StackSets → Create StackSet, keep Service-managed permissions, paste the template URL from Step B1, and fill in:

Acknowledge CAPABILITY_NAMED_IAM as in Step A1, target your OUs, and enable automatic deployment — that is what onboards future accounts and cleanly removes departing ones.

Step B3 — Deploy the management account as a plain stack

Skip this only if you do not want your organization's management account observed. A service-managed StackSet never deploys to it, silently, so it registers nothing.

1. Sign in to the management account and go to CloudFormation → Create stack → With new resources. This is Create stack, not Create StackSet.
2. Use the same template URL.
3. Enter the same parameter values as the StackSet — particularly CollectorRoleName, PushPath and PushToken, since KubeSense derives this account's role ARN by the same convention as every other. Reuse the same push token; generating a new one invalidates the StackSet's.
4. Acknowledge CAPABILITY_NAMED_IAM and create the stack.

Because this is a plain stack it is not covered by the StackSet's automatic deployment. It is the one account you maintain by hand: if you later update the StackSet's parameters, update this stack too.

Step B4 — Verify the rollout

Watch the StackSet's Stack instances tab until every instance reports SUCCEEDED. Each successful instance means that account has created its read-only role and registered itself with KubeSense. A failed instance carries the HTTP status in its status reason — see Troubleshooting. Registration is idempotent, so failed instances can be retried safely once the cause is fixed.

Then confirm from the KubeSense side: the enrolled account count should be your successful stack instances, plus one if you deployed the management account in Step B3. If the dashboard is one short and every instance succeeded, the missing account is almost always the management account.

What the StackSet deploys

Two resources per account — no agents, no persistent compute:

1. The read-only collector role, trusting your controller. Unlike Approach A's template, this one uses a least-privilege inline policy listing only the API calls KubeSense makes, rather than the broad AWS-managed ReadOnlyAccess.
2. A registration function, which runs only at stack create and stack delete. On create it tells KubeSense "this account is now available", supplying nothing but its own account ID; on delete it says the reverse. It also calls iam:ListAccountAliases in its own account so the account appears under its alias rather than a bare twelve-digit number — best-effort, and an account that denies it still registers.

The function cannot choose which role KubeSense uses — KubeSense derives that itself from the account ID and your configured role name, so a registration request cannot point KubeSense at an arbitrary role even if the token leaks. Deleting a stack instance de-registers that account and stops collection; data already collected is retained, and a KubeSense outage never blocks a stack teardown.

Managing enrolled accounts

Seeing what is enrolled. The AWS integration page lists every automatically enrolled account, whether it is collecting or paused, and how it was registered. Manually added integrations are listed separately — enrollment never claims them.

Changing what one account collects. Adjust that account's resource types as usual. Enrollment will not overwrite the change on a later cycle.

Changing the defaults for future accounts. Edit the resource types on the enrollment. Existing accounts keep their current settings; only accounts enrolled from that point on pick up the new defaults.

Stopping collection for one account. With Organization Discovery, add it to Exclude Account IDs — it is paused on the next cycle and its data is retained; removing it from the list resumes it. With the StackSet, delete that account's stack instance; redeploying re-registers it.

Pausing enrollment entirely. With Organization Discovery, choose Return to preview on the Organization Setup screen and save: discovery keeps running so the plan stays current, but no account is enrolled, paused, or resumed automatically. Choose Enable Enrollment on the Review screen to resume. With the StackSet, generate a new push token without redeploying — accounts whose stacks are created after that cannot register until the StackSet is updated.

Accounts already enrolled keep collecting either way; tearing those down is a separate, deliberate action, so pausing can never silently stop collection.

Troubleshooting

Best practices

• Use a delegated administrator for the lister role rather than the management account, so organization read access lives outside your most sensitive account.
• Set OrgId on the collector role template — the trust policy then also requires the caller to belong to your organization, so a leaked controller ARN is not enough on its own.
• Always enable automatic deployment on the StackSet. It is what onboards accounts created later, and its absence is the commonest cause of a missing account.
• Select regions deliberately. Every enrolled account is queried in every selected region on each cycle, so unused regions cost API calls for nothing.
• Rotate the push token once a rollout finishes, and again before onboarding a new batch — updating the StackSet in the same change.
• Prefer Organization Discovery unless organization listing is genuinely off the table: the preview, OU filtering and automatic pause/resume have no equivalent in the push path.