static icon + minimal description for cluster

Author: BChoudhury-ms

l10n/bundle.l10n.json

@@ -109,6 +109,7 @@
   "[StreamingWriter] Starting document streaming with {0} strategy": "[StreamingWriter] Starting document streaming with {0} strategy",
   "[StreamingWriter] Throttle: wrote {0} docs, {1} remaining in batch": "[StreamingWriter] Throttle: wrote {0} docs, {1} remaining in batch",
   "[StreamingWriter] Writing {0} documents to target (may take a moment)...": "[StreamingWriter] Writing {0} documents to target (may take a moment)...",
+  "{0}\n\nIf the key pair is correct, make sure your current IP address is on the Access List for this API key and that the key has the required project permissions.": "{0}\n\nIf the key pair is correct, make sure your current IP address is on the Access List for this API key and that the key has the required project permissions.",
   "{0}\n\nNothing is imported until you choose Import. Choose Preview to open the file(s) without importing.": "{0}\n\nNothing is imported until you choose Import. Choose Preview to open the file(s) without importing.",
   "{0}\n\nThe query did not complete successfully. Performance metrics shown are partial and measured up to the failure point.": "{0}\n\nThe query did not complete successfully. Performance metrics shown are partial and measured up to the failure point.",
   "{0}\n\nTip: copy the file into the same filesystem as the editor (for example your WSL or remote home directory), then drop it again, or use the \"Add Kubeconfig Source\" command to browse for it.": "{0}\n\nTip: copy the file into the same filesystem as the editor (for example your WSL or remote home directory), then drop it again, or use the \"Add Kubeconfig Source\" command to browse for it.",
@@ -194,6 +195,7 @@
   "Acceptable execution time": "Acceptable execution time",
   "Access denied (403 Forbidden)": "Access denied (403 Forbidden)",
   "Access denied listing services (403 Forbidden)": "Access denied listing services (403 Forbidden)",
+  "Access denied: {0}": "Access denied: {0}",
   "Access denied. Verify your API key has the required permissions.": "Access denied. Verify your API key has the required permissions.",
   "Account information is incomplete.": "Account information is incomplete.",
   "Account Management Completed": "Account Management Completed",
@@ -258,6 +260,7 @@
   "Authentication data (properties.connectionString) is missing for \"{cluster}\".": "Authentication data (properties.connectionString) is missing for \"{cluster}\".",
   "Authentication failed (401 Unauthorized)": "Authentication failed (401 Unauthorized)",
   "Authentication failed listing services (401)": "Authentication failed listing services (401)",
+  "Authentication failed: {0}": "Authentication failed: {0}",
   "Authentication failed. Please sign in again.": "Authentication failed. Please sign in again.",
   "Authentication is required to run this action.": "Authentication is required to run this action.",
   "Authentication is required to use this migration provider.": "Authentication is required to use this migration provider.",
@@ -445,6 +448,7 @@
   "Creating resource group \"{0}\" in location \"{1}\"...": "Creating resource group \"{0}\" in location \"{1}\"...",
   "Creating storage account \"{0}\" in location \"{1}\" with sku \"{2}\"...": "Creating storage account \"{0}\" in location \"{1}\" with sku \"{2}\"...",
   "Creating user-assigned identity \"{0}\" in location \"{1}\"\"...": "Creating user-assigned identity \"{0}\" in location \"{1}\"\"...",
+  "Creating…": "Creating…",
   "Credentials may have expired. Re-authenticate with your cluster or update the kubeconfig.": "Credentials may have expired. Re-authenticate with your cluster or update the kubeconfig.",
   "Credentials may have expired. Re-authenticate with your cluster.": "Credentials may have expired. Re-authenticate with your cluster.",
   "Credentials updated successfully.": "Credentials updated successfully.",
@@ -476,6 +480,7 @@
   "delete this collection": "delete this collection",
   "delete this database": "delete this database",
   "Deleting...": "Deleting...",
+  "Deleting…": "Deleting…",
   "Demo Task {0}": "Demo Task {0}",
   "Demo Task Configuration": "Demo Task Configuration",
   "Destination: \"{0}\"": "Destination: \"{0}\"",
@@ -820,7 +825,6 @@
   "Invalid connection type selected.": "Invalid connection type selected.",
   "Invalid filter syntax: {0}. Please use valid JSON or a DocumentDB API expression, for example: { name: \"value\" }": "Invalid filter syntax: {0}. Please use valid JSON or a DocumentDB API expression, for example: { name: \"value\" }",
   "Invalid folder type.": "Invalid folder type.",
-  "Invalid MongoDB Atlas API key.": "Invalid MongoDB Atlas API key.",
   "Invalid node type.": "Invalid node type.",
   "Invalid payload for create index action": "Invalid payload for create index action",
   "Invalid payload for drop index action": "Invalid payload for drop index action",
@@ -919,6 +923,7 @@
   "Modify Index…": "Modify Index…",
   "Modifying index visibility ({action}) for \"{indexName}\" on collection: {collection}": "Modifying index visibility ({action}) for \"{indexName}\" on collection: {collection}",
   "MongoDB Atlas": "MongoDB Atlas",
+  "MongoDB Atlas rejected the API key (HTTP {0}).": "MongoDB Atlas rejected the API key (HTTP {0}).",
   "MongoDB Atlas Service Discovery": "MongoDB Atlas Service Discovery",
   "MongoDB Emulator": "MongoDB Emulator",
   "Move": "Move",
@@ -1169,6 +1174,7 @@
   "Rename kubeconfig source": "Rename kubeconfig source",
   "Rename Kubernetes context": "Rename Kubernetes context",
   "Renamed folder from \"{oldName}\" to \"{newName}\"": "Renamed folder from \"{oldName}\" to \"{newName}\"",
+  "Repairing…": "Repairing…",
   "Report a Bug": "Report a Bug",
   "report an issue": "report an issue",
   "Report an issue": "Report an issue",
@@ -1438,6 +1444,11 @@
   "These signals help us improve, but more context in a discussion, issue report, or a direct message adds even more value. ": "These signals help us improve, but more context in a discussion, issue report, or a direct message adds even more value. ",
   "They look like binary files rather than kubeconfigs.": "They look like binary files rather than kubeconfigs.",
   "This cannot be undone.": "This cannot be undone.",
+  "This cluster is being created. It will be available to connect once creation is complete.": "This cluster is being created. It will be available to connect once creation is complete.",
+  "This cluster is being deleted and will no longer be available.": "This cluster is being deleted and will no longer be available.",
+  "This cluster is being repaired. It may be temporarily unavailable.": "This cluster is being repaired. It may be temporarily unavailable.",
+  "This cluster is being updated. It may be temporarily unavailable.": "This cluster is being updated. It may be temporarily unavailable.",
+  "This cluster is in an unknown state. Try refreshing to update its status.": "This cluster is in an unknown state. Try refreshing to update its status.",
   "This ClusterIP service requires port-forwarding. Confirm or change the local port to forward to {0}/{1}:{2}.": "This ClusterIP service requires port-forwarding. Confirm or change the local port to forward to {0}/{1}:{2}.",
   "This field is not set": "This field is not set",
   "This functionality requires installing the Azure Account extension.": "This functionality requires installing the Azure Account extension.",
@@ -1499,6 +1510,7 @@
   "Unknown function '{0}'. Expected a BSON constructor (e.g., ObjectId, ISODate) or a known global (e.g., Date, Math).": "Unknown function '{0}'. Expected a BSON constructor (e.g., ObjectId, ISODate) or a known global (e.g., Date, Math).",
   "Unknown identifier '{0}'. Expected a known global (e.g., Date, Math).": "Unknown identifier '{0}'. Expected a known global (e.g., Date, Math).",
   "Unknown query generation type: {type}": "Unknown query generation type: {type}",
+  "Unknown state": "Unknown state",
   "Unknown strategy": "Unknown strategy",
   "Unknown tenant": "Unknown tenant",
   "unsupported": "unsupported",
@@ -1516,6 +1528,7 @@
   "Update Connection String": "Update Connection String",
   "Update Saved Password": "Update Saved Password",
   "Updated entity \"{name}\".": "Updated entity \"{name}\".",
+  "Updating…": "Updating…",
   "Upload": "Upload",
   "URL handling aborted. Connection was unsuccessful or the specified database/collection does not exist.": "URL handling aborted. Connection was unsuccessful or the specified database/collection does not exist.",
   "Use a Service Account client ID and secret (machine-to-machine)": "Use a Service Account client ID and secret (machine-to-machine)",

src/plugins/service-atlas-mongodb/api/AtlasApiClient.ts

@@ -195,11 +195,20 @@ export class AtlasApiClient {
 
         switch (response.status) {
             case 401:
-                throw new AtlasApiError(vscode.l10n.t('Authentication failed. Please sign in again.'), response.status);
+                throw new AtlasApiError(
+                    detail
+                        ? vscode.l10n.t('Authentication failed: {0}', detail)
+                        : vscode.l10n.t('Authentication failed. Please sign in again.'),
+                    response.status,
+                    detail,
+                );
             case 403:
                 throw new AtlasApiError(
-                    vscode.l10n.t('Access denied. Verify your API key has the required permissions.'),
+                    detail
+                        ? vscode.l10n.t('Access denied: {0}', detail)
+                        : vscode.l10n.t('Access denied. Verify your API key has the required permissions.'),
                     response.status,
+                    detail,
                 );
             case 404:
                 throw new AtlasApiError(vscode.l10n.t('Resource not found.'), response.status);
@@ -212,6 +221,7 @@ export class AtlasApiClient {
                 throw new AtlasApiError(
                     vscode.l10n.t('Atlas API error ({0}): {1}', String(response.status), detail),
                     response.status,
+                    detail,
                 );
         }
     }
@@ -224,6 +234,7 @@ export class AtlasApiError extends Error {
     constructor(
         message: string,
         public readonly statusCode: number,
+        public readonly detail?: string,
     ) {
         super(message);
         this.name = 'AtlasApiError';

src/plugins/service-atlas-mongodb/auth/AtlasApiKeyFlow.ts

@@ -55,18 +55,29 @@ export async function executeApiKeyFlow(sessionManager: AtlasSessionManager): Pr
     }
 
     // Step 3: Validate credentials
+    const { AtlasApiError } = await import('../api/AtlasApiClient');
     try {
-        const isValid = await validateApiKeyCredentials(publicKey.trim(), privateKey.trim());
-        if (!isValid) {
-            sessionManager.cancelAuthentication();
-            void vscode.window.showErrorMessage(vscode.l10n.t('Invalid MongoDB Atlas API key.'), {
-                modal: true,
-                detail: vscode.l10n.t('Please verify your public and private key pair.'),
-            });
-            return false;
-        }
+        await validateApiKeyCredentials(publicKey.trim(), privateKey.trim());
     } catch (error) {
         sessionManager.cancelAuthentication();
+        if (error instanceof AtlasApiError && (error.statusCode === 401 || error.statusCode === 403)) {
+            const reason =
+                error.detail && error.detail.trim().length > 0
+                    ? error.detail
+                    : vscode.l10n.t('Please verify your public and private key pair.');
+            void vscode.window.showErrorMessage(
+                vscode.l10n.t('MongoDB Atlas rejected the API key (HTTP {0}).', String(error.statusCode)),
+                {
+                    modal: true,
+                    detail: vscode.l10n.t(
+                        '{0}\n\nIf the key pair is correct, make sure your current IP address is on the Access List for this API key and that the key has the required project permissions.',
+                        reason,
+                    ),
+                },
+            );
+            return false;
+        }
+
         const errorMessage = error instanceof Error ? error.message : String(error);
         void vscode.window.showErrorMessage(vscode.l10n.t('Failed to validate MongoDB Atlas API key.'), {
             modal: true,
@@ -85,19 +96,14 @@ export async function executeApiKeyFlow(sessionManager: AtlasSessionManager): Pr
 /**
  * Validates API key credentials by making a lightweight API call.
  * Uses HTTP Digest Authentication as required by the Atlas Admin API.
+ *
+ * Resolves when the credentials are accepted. Any {@link AtlasApiError} (including 401/403)
+ * is propagated so the caller can surface the real reason Atlas rejected the request.
  */
-async function validateApiKeyCredentials(publicKey: string, privateKey: string): Promise<boolean> {
-    const { AtlasApiClient, AtlasApiError } = await import('../api/AtlasApiClient');
+async function validateApiKeyCredentials(publicKey: string, privateKey: string): Promise<void> {
+    const { AtlasApiClient } = await import('../api/AtlasApiClient');
     const client = new AtlasApiClient({ type: 'apikey', publicKey, privateKey });
 
-    try {
-        // A successful call to list projects means the credentials are valid
-        await client.listProjects();
-        return true;
-    } catch (error) {
-        if (error instanceof AtlasApiError && (error.statusCode === 401 || error.statusCode === 403)) {
-            return false;
-        }
-        throw error;
-    }
+    // A successful call to list projects means the credentials are valid.
+    await client.listProjects();
 }

src/plugins/service-atlas-mongodb/discovery-tree/AtlasClusterItem.ts

@@ -11,6 +11,7 @@ import {
     type IActionContext,
 } from '@microsoft/vscode-azext-utils';
 import * as l10n from '@vscode/l10n';
+import * as path from 'path';
 import * as vscode from 'vscode';
 import { AuthMethodId } from '../../../documentdb/auth/AuthMethod';
 import { ClustersClient } from '../../../documentdb/ClustersClient';
@@ -23,9 +24,11 @@ import { ProvideUserNameStep } from '../../../documentdb/wizards/authenticate/Pr
 import { ext } from '../../../extensionVariables';
 import { ClusterItemBase, type EphemeralClusterCredentials } from '../../../tree/documentdb/ClusterItemBase';
 import { type TreeCluster } from '../../../tree/models/BaseClusterModel';
+import { getResourcesPath } from '../../../utils/icons';
 import { nonNullValue } from '../../../utils/nonNull';
 import { DISCOVERY_PROVIDER_ID } from '../config';
 import { type AtlasClusterModel } from '../models/AtlasClusterModel';
+import { type AtlasClusterState } from '../models/AtlasProjectModel';
 
 /** Resource type identifier for telemetry */
 const RESOURCE_TYPE = 'atlas-mongodb-cluster';
@@ -216,18 +219,26 @@ export class AtlasClusterItem extends ClusterItemBase<AtlasClusterModel> {
 
     /**
      * Returns the tree item representation with Atlas-specific display.
-     * Shows state icon, tier/provider/region description, and cluster metadata tooltip.
+     * Uses a stable provider-identity icon (the DocumentDB cluster brand mark, matching
+     * sibling discovery plugins); transient cluster state is surfaced through the
+     * description and tooltip rather than the icon so the tree stays visually stable
+     * across refreshes.
      */
     getTreeItem(): vscode.TreeItem {
-        const stateIcon = this.getStateIcon();
-
         return {
             id: this.id,
             contextValue: this.contextValue,
             label: this.cluster.name,
             description: this.buildDescription(),
             tooltip: this.buildTooltip(),
-            iconPath: stateIcon,
+            iconPath: {
+                light: vscode.Uri.file(
+                    path.join(getResourcesPath(), 'icons', 'vscode-documentdb-cluster-light-themes.svg'),
+                ),
+                dark: vscode.Uri.file(
+                    path.join(getResourcesPath(), 'icons', 'vscode-documentdb-cluster-dark-themes.svg'),
+                ),
+            },
             collapsibleState: vscode.TreeItemCollapsibleState.Collapsed,
         };
     }
@@ -265,17 +276,24 @@ export class AtlasClusterItem extends ClusterItemBase<AtlasClusterModel> {
     private buildDescription(): string {
         const parts: string[] = [];
 
+        // The tier (e.g. "M10") should show. When the tier is unavailable (e.g. serverless clusters), fall back to the provider/region pair.
         if (this.cluster.instanceSizeName) {
             parts.push(this.cluster.instanceSizeName);
+        } else {
+            if (this.cluster.providerName) {
+                parts.push(this.cluster.providerName);
+            }
+            if (this.cluster.regionName) {
+                parts.push(this.formatRegion(this.cluster.regionName));
+            }
         }
-        if (this.cluster.providerName) {
-            parts.push(this.cluster.providerName);
-        }
-        if (this.cluster.regionName) {
-            parts.push(this.formatRegion(this.cluster.regionName));
+
+        const stateLabel = this.getStateLabel();
+        if (stateLabel) {
+            parts.push(stateLabel);
         }
 
-        return parts.length > 0 ? parts.join(', ') : this.cluster.stateName;
+        return parts.join(' · ');
     }
 
     private buildTooltip(): vscode.MarkdownString {
@@ -299,6 +317,13 @@ export class AtlasClusterItem extends ClusterItemBase<AtlasClusterModel> {
 
         md.appendMarkdown(`- **Project:** ${escapeMarkdown(this.cluster.projectName)}\n`);
 
+        const stateExplanation = this.getStateExplanation();
+        if (stateExplanation) {
+            md.appendMarkdown(`\n---\n`);
+            md.appendMarkdown(escapeMarkdown(stateExplanation));
+            return md;
+        }
+
         if (this.cluster.connectionString) {
             md.appendMarkdown(`\n---\n`);
             md.appendMarkdown(`Connection string available — expand to connect and browse databases.`);
@@ -307,18 +332,43 @@ export class AtlasClusterItem extends ClusterItemBase<AtlasClusterModel> {
         return md;
     }
 
-    private getStateIcon(): vscode.ThemeIcon {
+    /**
+     * Returns a short, localized label for the current cluster state, or `undefined` for the
+     * normal IDLE state (which needs no annotation). Shown in the tree item description.
+     */
+    private getStateLabel(): string | undefined {
+        const labels: Record<AtlasClusterState, string | undefined> = {
+            IDLE: undefined,
+            CREATING: l10n.t('Creating…'),
+            UPDATING: l10n.t('Updating…'),
+            REPAIRING: l10n.t('Repairing…'),
+            DELETING: l10n.t('Deleting…'),
+            UNKNOWN: l10n.t('Unknown state'),
+        };
+        return labels[this.cluster.stateName];
+    }
+
+    /**
+     * Returns a localized, human-readable explanation of a non-IDLE cluster state for the
+     * tooltip, or `undefined` when the cluster is IDLE.
+     */
+    private getStateExplanation(): string | undefined {
         switch (this.cluster.stateName) {
-            case 'IDLE':
-                return new vscode.ThemeIcon('circle-filled', new vscode.ThemeColor('testing.iconPassed'));
             case 'CREATING':
+                return l10n.t(
+                    'This cluster is being created. It will be available to connect once creation is complete.',
+                );
             case 'UPDATING':
+                return l10n.t('This cluster is being updated. It may be temporarily unavailable.');
             case 'REPAIRING':
-                return new vscode.ThemeIcon('loading~spin');
+                return l10n.t('This cluster is being repaired. It may be temporarily unavailable.');
             case 'DELETING':
-                return new vscode.ThemeIcon('circle-filled', new vscode.ThemeColor('testing.iconFailed'));
+                return l10n.t('This cluster is being deleted and will no longer be available.');
+            case 'UNKNOWN':
+                return l10n.t('This cluster is in an unknown state. Try refreshing to update its status.');
+            case 'IDLE':
             default:
-                return new vscode.ThemeIcon('circle-outline');
+                return undefined;
         }
     }