Cloud Account & On-Prem Integration

Every connector uses a polling model: BlueWhale Stack calls cloud provider APIs on a configurable interval (default: 15 minutes) to refresh the asset graph. For on-premises environments the Edge Agent reverses this: the agent polls the BlueWhale control plane, which queues commands for the agent to execute locally.

• Connector credentials are encrypted at rest (AES-256) and scoped to least privilege
• Each connector has an independent health status visible in Settings → Cloud Connectors
• Failed polls are retried with exponential back-off and surfaced as connector health warnings
• You can trigger a manual discovery at any time from the connector card

BlueWhale Stack connects to AWS using a cross-account IAM role with an external ID. This is the most secure pattern: no long-lived access keys are stored, and the trust relationship can be revoked from your AWS account at any time.

1. 1

   Add an AWS connector

   Settings → Cloud Connectors → Add connector → AWS. Note the BlueWhale AWS Account ID and your unique External ID shown on screen.

2. 2

   Create an IAM role

   In AWS IAM, create a role with trust to the BlueWhale account ID, requiring the External ID. Attach ReadOnlyAccess for discovery. For provisioning, also attach the BlueWhaleProvisioningPolicy (JSON provided on screen).

   # Trust policy
   {
     "Version": "2012-10-17",
     "Statement": [{
       "Effect": "Allow",
       "Principal": { "AWS": "arn:aws:iam::<BWS_ACCOUNT_ID>:root" },
       "Action": "sts:AssumeRole",
       "Condition": {
         "StringEquals": { "sts:ExternalId": "<YOUR_EXTERNAL_ID>" }
       }
     }]
   }

3. 3

   Enter the role ARN and save

   Paste the role ARN (arn:aws:iam::123456789012:role/...) into the connector form and click Save & test. A successful test runs a lightweight DescribeRegions call.

Azure connections use an Entra ID (Azure AD) service principal with the Reader role at the subscription scope. No management-plane write access is required for discovery.

1. 1

   Register an app in Entra ID

   Go to Azure portal → Entra ID → App registrations → New registration. Name it BlueWhaleStack and note the Application (client) ID and Directory (tenant) ID.

2. 2

   Create a client secret

   Under Certificates & secrets → New client secret. Copy the secret value immediately — it is shown only once.

3. 3

   Assign the Reader role

   Go to your Subscription → Access control (IAM) → Add role assignment → Reader. Assign it to the app registration you just created.

   # Azure CLI equivalent:
   az ad sp create-for-rbac \
     --name BlueWhaleStack \
     --role Reader \
     --scopes /subscriptions/<SUBSCRIPTION_ID>

4. 4

   Enter credentials in BlueWhale Stack

   Add an Azure connector and enter the Tenant ID, Client ID, Client Secret, and Subscription ID.

GCP connections use a service account with the Viewer role (or a custom least-privilege role) bound to the target project or folder.

1. 1

   Create a service account

   GCP Console → IAM & Admin → Service Accounts → Create. Name it bluewhale-stack-reader.

   gcloud iam service-accounts create bluewhale-stack-reader \
     --display-name="BlueWhale Stack Reader"

2. 2

   Grant the Viewer role

   Bind the Viewer role to the service account at the project level. For organisation-wide discovery, bind at the organisation level.

   gcloud projects add-iam-policy-binding <PROJECT_ID> \
     --member="serviceAccount:bluewhale-stack-reader@<PROJECT_ID>.iam.gserviceaccount.com" \
     --role="roles/viewer"

3. 3

   Create and download a key

   Under the service account → Keys → Add key → Create new key → JSON. The downloaded JSON file is what you upload to the connector form in BlueWhale Stack.

Oracle Cloud Infrastructure (OCI), Alibaba Cloud and Huawei Cloud connectors follow a similar pattern: create a service identity or API key with read-only access, then provide the credentials and tenancy/account identifiers in the connector form.

• OCI: requires an OCI API signing key + tenancy OCID + user OCID + fingerprint
• Alibaba: requires an AccessKey ID and AccessKey Secret with ReadOnlyAccess policy
• Huawei: requires an IAM user Access Key (AK/SK) with the ReadOnlyAccess system policy

The Edge Agent enables BlueWhale Stack to discover and manage VMware vSphere, Nutanix AHV, and Microsoft Hyper-V environments — and any other on-premises workloads — without opening inbound firewall ports.

1. 1

   Download the Edge Agent

   From Settings → Cloud Connectors → Add connector → On-Premises, download the Edge Agent installer for your target OS (Linux x86_64 / ARM64 or Windows Server).

2. 2

   Generate a registration token

   Click Generate token on the connector screen. The token is valid for 24 hours and ties the agent to your BlueWhale Stack organisation.

3. 3

   Install and register

   Run the installer on a VM inside your network. The agent requires outbound HTTPS (port 443) to the BlueWhale control plane endpoint.

   # Linux install + register
   chmod +x bws-edge-agent-linux-amd64
   sudo ./bws-edge-agent-linux-amd64 install \
     --token <REGISTRATION_TOKEN> \
     --endpoint https://enterprise.bluewhalestack.com

4. 4

   Configure hypervisor credentials

   After registration, add your hypervisor endpoint (vCenter URL, Nutanix Prism URL, or Hyper-V host) and credentials via the Edge Agent configuration page in BlueWhale Stack. Credentials are stored locally — they never leave your network.

All connectors report their health in Settings → Cloud Connectors. Each card shows last poll time, resource count, and status (Connected / Warning / Error). Expand a connector card for detailed error messages and the last successful poll timestamp.

• Connected — last poll succeeded, asset graph is fresh
• Warning — last poll succeeded but some regions returned partial results
• Error — last poll failed; the error message shows the root cause (e.g., permission denied, expired token)
• Stale — discovery has not run in over 30 minutes (check agent connectivity for on-prem)