Single Account Setup

Overview

KubeSense observes an AWS account using read-only credentials, discovering your resources and pulling their metrics from CloudWatch so the cloud estate appears alongside the Kubernetes telemetry KubeSense already collects. Nothing is created, changed or deleted in the account — every call is a Describe, List, Get or GetMetricData.

This page covers connecting one account. For an estate spread across an AWS Organization, see Multi-Account Setup, which onboards them all in one rollout.

Two ways to connect a single account, offered as cards under Settings → Integrations → AWS → Add New AWS Account → Single Account:

Prerequisites

1. A KubeSense controller running with an identity of its own — an EKS IRSA role or an EC2 instance profile. Both paths reference it, and the Manual path's role mode is built on it
2. Permission to create IAM roles and policies in the account you are connecting
3. For the CloudFormation path, a KubeSense endpoint reachable over public HTTPS from AWS, since the stack registers the account by calling back
4. Administrator access to the KubeSense dashboard

Path A — CloudFormation (recommended)

The stack creates the read-only collector role in the target account and registers that account with KubeSense itself, so there is nothing to copy back.

Step 1 — Fill in the setup screen

Settings → Integrations → AWS → Add New AWS Account → Single Account → CloudFormation:

Continue — that saves the configuration and moves to the launch step.

Step 2 — Launch the stack

Select Launch stack in AWS. KubeSense generates a CloudFormation quick-create link with every stack parameter pre-filled and opens the AWS console in a new tab. Acknowledge the IAM capability and select Create stack. The account appears in KubeSense once the stack completes.

The generated link is also shown on the screen with a copy button. If the console opened signed in to the wrong AWS account, sign in to the account you are enrolling and use that link — it stays valid.

What the stack creates

Two resources, no agents and no persistent compute: the read-only collector role (KubeSenseCollectorRole, with a least-privilege inline policy listing only the API calls KubeSense makes), and a registration function that runs once at stack create and once at stack delete. On create it tells KubeSense the account is available, supplying nothing but its own account ID; on delete it says the reverse and collection stops, with everything already collected retained.

Deleting the stack is therefore how you disconnect an account connected this way.

Path B — Manual

Use this when CloudFormation cannot reach KubeSense, or when the credential already exists. Choose an Authentication Mode on the form:

Step 1 — Create the credential in AWS

For Role Access. Create a read-only role in the target account, named KubeSenseCollectorRole by convention, with a trust policy naming the controller role exactly:

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

Attach read-only permissions: either the AWS-managed ReadOnlyAccess policy, or the read-only permissions policy below if your security review requires least privilege. ReadOnlyAccess is simpler but broader — it also grants read access to data, such as the contents of S3 objects, which KubeSense never reads.

Read-only permissions policy

This policy grants only the API calls KubeSense makes, and every one is read-only:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "KubeSenseCollectorReadOnly",
      "Effect": "Allow",
      "Resource": "*",
      "Action": [
        "ec2:Describe*",
        "autoscaling:DescribeAutoScalingGroups",
        "eks:ListClusters",
        "eks:DescribeCluster",
        "ecs:List*",
        "ecs:Describe*",
        "rds:Describe*",
        "elasticache:Describe*",
        "elasticloadbalancing:Describe*",
        "lambda:ListFunctions",
        "s3:ListAllMyBuckets",
        "s3:GetBucketLocation",
        "sns:ListTopics",
        "sns:GetTopicAttributes",
        "sqs:ListQueues",
        "kinesis:ListStreams",
        "firehose:ListDeliveryStreams",
        "kafka:ListClustersV2",
        "lex:ListBots",
        "wafv2:ListWebACLs",
        "apigateway:GET",
        "cloudfront:ListDistributions",
        "route53:ListHostedZones",
        "route53:ListHealthChecks",
        "dynamodb:ListTables",
        "dynamodb:DescribeTable",
        "states:ListStateMachines",
        "events:ListEventBuses",
        "events:ListRules",
        "redshift:DescribeClusters",
        "es:ListDomainNames",
        "es:DescribeDomain",
        "sagemaker:ListEndpoints",
        "sagemaker:DescribeEndpoint",
        "sagemaker:DescribeEndpointConfig",
        "cloudwatch:GetMetricData",
        "cloudwatch:ListMetrics",
        "pi:DescribeDimensionKeys",
        "pi:ListAvailableResourceMetrics",
        "pi:GetResourceMetrics",
        "tag:GetResources",
        "organizations:DescribeAccount"
      ]
    }
  ]
}

Leaving an action out does not stop collection — the feature it serves just stays empty, which is easy to mistake for a KubeSense problem. These are the ones most often trimmed:

DocumentDB and Neptune are covered by rds:Describe*, and API Gateway by apigateway:GET. The policy needs no s3:ListBucket and no sts: permission.

Then allow the controller to assume the role, once, in the controller account:

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"
    }]
  }'

For Service Account (IRSA). Attach the read-only policy directly to the controller's own role, and confirm the identity resolves to the account you are connecting:

kubectl exec -n kubesense <controller-pod> -- env | grep AWS_
# AWS_ROLE_ARN=arn:aws:iam::123456789012:role/kubesense-controller
# AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/eks.amazonaws.com/serviceaccount/token

kubectl exec -n kubesense <controller-pod> -- aws sts get-caller-identity

The Account value must match the account ID you register below. If the AWS_* variables are absent, the pod started before the ServiceAccount annotation was applied — re-run kubectl rollout restart and check again.

For Credentials (Access Key). Create an IAM user with the same read-only policy and generate an access key pair. Prefer either of the other two modes: a static key is stored, never expires on its own, and has to be rotated by hand.

Step 2 — Connect in KubeSense

Settings → Integrations → AWS → Add New AWS Account → Single Account → Manual:

Select Connect. KubeSense verifies the credential immediately and the next screen reports success, or the exact error AWS returned.

Verify

1. The credential resolves. The screen after Connect reports this. On the CloudFormation path, the stack reaching CREATE_COMPLETE is the equivalent.
2. Resources appear. Open the integration from Settings → Integrations → AWS. Within a minute or two it shows a count per resource type. A type showing zero either has no resources or is not selected under Collection Settings.
3. Metrics arrive. Allow up to 10 minutes for the first metric cycle, then open any discovered resource and confirm its charts are populated.

KubeSense checks, on every collection cycle, that the assumed identity belongs to the account_id you registered. A mismatched or wrong role ARN is rejected automatically — it will never collect the wrong account's data.

Troubleshooting