Quick Start — SaaS

This guide walks you through your first BlueWhale Stack SaaS session: logging in, connecting an AWS account, running a discovery, and reading the unified inventory. The whole process takes under 15 minutes.

What you'll need

• A BlueWhale Stack account (contact sales or use your invite link)
• AWS account with permission to create IAM roles
• AWS account ID (12-digit number found in the AWS console header)

Open your invite email and click the activation link. You will be prompted to set a password and choose your organisation name. If your organisation uses SSO (Entra ID, Okta, etc.), your administrator will have pre-configured federation — just click Continue with SSO.

After logging in you land on the Dashboard. The left navigation panel lists all modules available in your edition. The top bar shows your organisation, active region, and Whale AI token balance.

Navigate to Settings → Cloud Connectors → Add connector → AWS. BlueWhale Stack uses an IAM cross-account role (not your root credentials). This keeps credentials scoped to the minimum required permissions and makes them easy to rotate or revoke.

1. 1

   Note your external ID

   The connector setup screen shows a unique External ID for your organisation. Copy it — you'll need it when creating the IAM role.

2. 2

   Create the IAM role in AWS

   In the AWS console, go to IAM → Roles → Create role → AWS account → Another AWS account. Enter the BlueWhale Stack AWS account ID shown on screen, check Require external ID, and paste the External ID you copied.

   # Or use the AWS CLI:
   aws iam create-role \
     --role-name BlueWhaleStackReadRole \
     --assume-role-policy-document '{
       "Version": "2012-10-17",
       "Statement": [{
         "Effect": "Allow",
         "Principal": { "AWS": "arn:aws:iam::BLUEWHALE_ACCOUNT:root" },
         "Action": "sts:AssumeRole",
         "Condition": { "StringEquals": { "sts:ExternalId": "YOUR_EXTERNAL_ID" } }
       }]
     }'

3. 3

   Attach the read policy

   Attach the AWS-managed ReadOnlyAccess policy for read-only discovery. For provisioning (Service Catalog), attach the additional BlueWhaleProvisioningPolicy — the JSON for this is shown on the connector setup screen.

   aws iam attach-role-policy \
     --role-name BlueWhaleStackReadRole \
     --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess

4. 4

   Enter the role ARN in BlueWhale Stack

   Copy the Role ARN from the IAM console (format: arn:aws:iam::123456789012:role/BlueWhaleStackReadRole) and paste it into the BlueWhale Stack connector form. Click Save & test.

Once the connector test passes (a green tick appears), click Run discovery. BlueWhale Stack will poll every enabled region across your AWS account and populate the asset graph. Discovery time depends on account size — a typical AWS account with 500 resources completes in under 90 seconds.

You can watch progress in real time: the connector card shows a spinner and a live count of resources found. Discovery runs automatically every 15 minutes after the initial run — you can also trigger it manually at any time.

Navigate to Inventory in the left menu. You will see every discovered resource — EC2 instances, S3 buckets, RDS clusters, VPCs, Lambda functions, EKS clusters, and more — normalised into a consistent model regardless of cloud provider.

• Filter by resource type, region, status, or tag
• Group by workload to see resources that belong together
• Click any resource to see live metadata, tags, and available actions
• Export the full inventory as PDF, Excel, or CSV

Try Whale AI

Open the Whale AI drawer (the sparkle icon in the top-right) and ask a natural-language question about your inventory: “Which EC2 instances are running in us-east-1 without a backup policy?” or “What is my total storage footprint across S3?” Whale AI Spark answers from your live asset graph.

• Connect additional cloud accounts (Azure, GCP, Oracle, Alibaba, Huawei)
• Add on-premises environments via the Edge Agent
• Set up identity federation so your team can log in with their existing IdP
• Enable the Service Catalog so teams can self-serve resource provisioning
• Configure Observe for logs, metrics, and SLO alerting