ec2: add case-specific errors for when instance is not running and when attached IAM invalid (#3587)

* add empty connect command

* create sample QuickPick on click

* hacky prompt + func to list instanceId

* very hacky way to create prompt with instanceIds

* move extractInstanceIds to own function

* utilize lastTouchedRegion in prompt

* throw cancellationError on user cancel

* add a title to quickpick

* refactor: increase testability

* move test utility func to shared utility file

* add general test cases for extractInstanceIdsFromReservations

* add basic test for prompter

* configure command to devMode

* refactor to utilize wizard + integrate regionSubmenu

* add new testing file

* refactor to utilize regionSubmenu in isolation, rather than wrapped in Wizard class

* fix awkward indent

* add test file from feature/cwl branch

* remove old prompter old + tests

* delete tests that rely on feature/cwl changes

* refactor to avoid circular dependency

* fix improper headers + imports

* introduce Ec2ConnectClient to handle connection

* remove dead parameter

* close connection on terminal close

* add a little more to error msg

* remove dead imports

* log error to console

* rename function

Co-authored-by: Justin M. Keyes <[email protected]>

* fix header

Co-authored-by: Justin M. Keyes <[email protected]>

* fix headers and imports

* remove year from header

* delete outdated test case

* delete outdated test file

* remove year from copyright header

* fix formatting of files

* remove alias in Ec2Instance

* utilize interface for object-like shape

* improve style + start of work on debugging error

* make distinction between status error and permission error

* start to add tests for error handling

* move code to general Ec2Client

* change Log Groups to selection in region submenu

* refactor to avoid circular dependency

* fix formatting

* fix formatting

* comment out the ec2Client we are not using

* style fix

* fix formatting

* add test for error handling

* fix formatting

* add extra wrapper

* generalize some code to a remoteSession file

* add space between pieces

* retrieve IAM role attached to instance when fails to connect

* remove dead import

* refactor to avoid circular dependency

* checks if relevant policies are on attached role

* use both probes to determine source of error

* update tests

* change callback to async/await

* remove onError parameter and utilize .catch instead

* add test for permissions detection

* fix test

* make error handling a try-catch

* avoid unnecessary default prefix on client name

Co-authored-by: Justin M. Keyes <[email protected]>

* fix old import

* refactor defaultEc2client -> ec2Client

* rename Ec2ConnectClient

* fix outdated imports in the test

* bubble error up

* update test case

* Remove please in text

Co-authored-by: Justin M. Keyes <[email protected]>

* Remove please in text in other error

Co-authored-by: Justin M. Keyes <[email protected]>

* remove unnecessary types and update tests to match

* change name of test utility to match other examples

* remove `Error` from error code

* change default error message to be more concise.

Co-authored-by: Justin M. Keyes <[email protected]>

* change text in error message

Co-authored-by: Justin M. Keyes <[email protected]>

* change text on documentation button.

Co-authored-by: Justin M. Keyes <[email protected]>

* refactor instanceStatus functionality to be more direct

* add error to prevent friendlyName extracter from returning undefined

* add tests for getFriendlyName

* move variable to the end of message.

Co-authored-by: Justin M. Keyes <[email protected]>

---------

Co-authored-by: Justin M. Keyes <[email protected]>

Author: Hweinstock

src/auth/ui/vue/types.ts

@@ -8,8 +8,6 @@ export type ServiceItemId = 'resourceExplorer' | 'codewhisperer' | 'codecatalyst
 export function isServiceItemId(value: unknown): value is ServiceItemId {
     return (
         typeof value === 'string' &&
-        (value === 'resourceExplorer' ||
-            value === 'codewhisperer' ||
-            value === 'codecatalyst')
+        (value === 'resourceExplorer' || value === 'codewhisperer' || value === 'codecatalyst')
     )
 }

src/cloudWatchLogs/commands/searchLogGroup.ts

@@ -242,7 +242,7 @@ export function createRegionSubmenu() {
         getLogGroupsFromRegion,
         { title: localize('AWS.cwl.searchLogGroup.logGroupPromptTitle', 'Select Log Group') },
         { title: localize('AWS.cwl.searchLogGroup.regionPromptTitle', 'Select Region for Log Group') },
-        "Log Groups"
+        'Log Groups'
     )
 }
 

src/ec2/activation.ts

@@ -9,7 +9,7 @@ import { tryConnect } from './commands'
 export async function activate(ctx: ExtContext): Promise<void> {
     ctx.extensionContext.subscriptions.push(
         Commands.register('aws.ec2.connectToInstance', async (param?: unknown) => {
-            tryConnect()
+            await tryConnect()
         })
     )
 }

src/ec2/model.ts

@@ -4,29 +4,90 @@
  */
 import * as vscode from 'vscode'
 import { Session } from 'aws-sdk/clients/ssm'
+import { AWSError, IAM } from 'aws-sdk'
 import { Ec2Selection } from './utils'
 import { getOrInstallCli } from '../shared/utilities/cliUtils'
 import { isCloud9 } from '../shared/extensionUtilities'
 import { ToolkitError, isAwsError } from '../shared/errors'
 import { SsmClient } from '../shared/clients/ssmClient'
+import { Ec2Client } from '../shared/clients/ec2Client'
+
+export type Ec2ConnectErrorCode = 'EC2SSMStatus' | 'EC2SSMPermission' | 'EC2SSMConnect'
+
 import { openRemoteTerminal } from '../shared/remoteSession'
+import { DefaultIamClient } from '../shared/clients/iamClient'
 
 export class Ec2ConnectionManager {
-    // Will need the ec2Client for probing errors,
     private ssmClient: SsmClient
-    //private ec2Client: DefaultEc2Client
+    private ec2Client: Ec2Client
+    private iamClient: DefaultIamClient
 
     public constructor(readonly regionCode: string) {
-        this.ssmClient = new SsmClient(this.regionCode)
-        //this.ec2Client = new DefaultEc2Client(this.regionCode)
+        this.ssmClient = this.createSsmSdkClient()
+        this.ec2Client = this.createEc2SdkClient()
+        this.iamClient = this.createIamSdkClient()
+    }
+
+    protected createSsmSdkClient(): SsmClient {
+        return new SsmClient(this.regionCode)
     }
 
-    private async handleStartSessionError(err: AWS.AWSError): Promise<void> {
-        const failureMessage =
-            "SSM: Failed to start session with target instance. Common reasons include: \n 1. SSM Agent not installed on instance. \n 2. The required IAM instance profile isn't attached to the instance.  \n 3. Session manager setup is incomplete."
-        await vscode.window.showErrorMessage(failureMessage)
+    protected createEc2SdkClient(): Ec2Client {
+        return new Ec2Client(this.regionCode)
+    }
 
-        throw new ToolkitError('Start Session Failed. ')
+    protected createIamSdkClient(): DefaultIamClient {
+        return new DefaultIamClient(this.regionCode)
+    }
+
+    protected async getAttachedPolicies(instanceId: string): Promise<IAM.attachedPoliciesListType> {
+        try {
+            const IamRole = await this.ec2Client.getAttachedIamRole(instanceId)
+            const iamResponse = await this.iamClient.listAttachedRolePolicies(IamRole!.Arn!)
+            return iamResponse.AttachedPolicies!
+        } catch (err) {
+            return []
+        }
+    }
+
+    public async hasProperPolicies(instanceId: string): Promise<boolean> {
+        const attachedPolicies = (await this.getAttachedPolicies(instanceId)).map(policy => policy.PolicyName!)
+        const requiredPolicies = ['AmazonSSMManagedInstanceCore', 'AmazonSSMManagedEC2InstanceDefaultPolicy']
+
+        return requiredPolicies.every(policy => attachedPolicies.includes(policy))
+    }
+
+    public async handleStartSessionError(err: AWSError, selection: Ec2Selection): Promise<Error> {
+        const isInstanceRunning = (await this.ec2Client.getInstanceStatus(selection.instanceId)) == 'running'
+        const generalErrorMessage = `Unable to connect to target instance ${selection.instanceId} on region ${selection.region}. `
+        const hasProperPolicies = await this.hasProperPolicies(selection.instanceId)
+
+        if (!isInstanceRunning) {
+            throw new ToolkitError(
+                generalErrorMessage +
+                    'Ensure the target instance is running and not currently starting, stopping, or stopped.',
+                { code: 'EC2SSMStatus' }
+            )
+        }
+
+        if (!hasProperPolicies) {
+            throw new ToolkitError(
+                generalErrorMessage + 'Ensure the IAM role attached to the instance has the required policies.',
+                {
+                    code: 'EC2SSMPermission',
+                    documentationUri: vscode.Uri.parse(
+                        'https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started-instance-profile.html'
+                    ),
+                }
+            )
+        }
+
+        throw new ToolkitError('Is SSM running on the target instance?', {
+            code: 'EC2SSMConnect',
+            documentationUri: vscode.Uri.parse(
+                'https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started.html'
+            ),
+        })
     }
 
     private async openSessionInTerminal(session: Session, selection: Ec2Selection) {
@@ -49,7 +110,7 @@ export class Ec2ConnectionManager {
             await this.openSessionInTerminal(response, selection)
         } catch (err) {
             if (isAwsError(err)) {
-                await this.handleStartSessionError(err)
+                await this.handleStartSessionError(err, selection)
             } else {
                 throw err
             }

src/ec2/prompter.ts

@@ -25,7 +25,7 @@ export function createEc2ConnectPrompter(): RegionSubmenu<string> {
     return new RegionSubmenu(
         async region => (await getInstanceIdsFromRegion(region)).map(asQuickpickItem).promise(),
         { title: 'Select EC2 Instance Id' },
-        { title: 'Select Region for EC2 Instance' }, 
-        "Instances"
+        { title: 'Select Region for EC2 Instance' },
+        'Instances'
     )
 }

src/ec2/utils.ts

@@ -13,5 +13,5 @@ export interface Ec2Selection {
 
 export async function getInstanceIdsFromRegion(regionCode: string): Promise<AsyncCollection<string>> {
     const client = new Ec2Client(regionCode)
-    return client.getInstanceIds()
+    return await client.getInstanceIds()
 }

src/extension.ts

@@ -63,12 +63,13 @@ import { join } from 'path'
 import { Experiments, Settings } from './shared/settings'
 import { isReleaseVersion } from './shared/vscode/env'
 import { Commands, registerErrorHandler } from './shared/vscode/commands2'
-import { isUserCancelledError, resolveErrorMessageToDisplay } from './shared/errors'
+import { ToolkitError, isUserCancelledError, resolveErrorMessageToDisplay } from './shared/errors'
 import { Logging } from './shared/logger/commands'
 import { UriHandler } from './shared/vscode/uriHandler'
 import { telemetry } from './shared/telemetry/telemetry'
 import { Auth } from './auth/auth'
 import { openUrl } from './shared/utilities/vsCodeUtils'
+import { showMessageWithUrl } from './shared/utilities/messages'
 
 let localize: nls.LocalizeFunc
 
@@ -280,16 +281,19 @@ async function handleError(error: unknown, topic: string, defaultMessage: string
         getLogger().verbose(`${topic}: user cancelled`)
         return
     }
-
     const logsItem = localize('AWS.generic.message.viewLogs', 'View Logs...')
     const logId = getLogger().error(`${topic}: %s`, error)
     const message = resolveErrorMessageToDisplay(error, defaultMessage)
 
-    await vscode.window.showErrorMessage(message, logsItem).then(async resp => {
-        if (resp === logsItem) {
-            await Logging.declared.viewLogsAtMessage.execute(logId)
-        }
-    })
+    if (error instanceof ToolkitError && error.documentationUri) {
+        await showMessageWithUrl(message, error.documentationUri, 'View Documentation', 'error')
+    } else {
+        await vscode.window.showErrorMessage(message, logsItem).then(async resp => {
+            if (resp === logsItem) {
+                await Logging.declared.viewLogsAtMessage.execute(logId)
+            }
+        })
+    }
 }
 
 export async function deactivate() {

src/shared/clients/ec2Client.ts

@@ -7,6 +7,7 @@ import { EC2 } from 'aws-sdk'
 import globals from '../extensionGlobals'
 import { AsyncCollection } from '../utilities/asyncCollection'
 import { pageableToCollection } from '../utilities/collectionUtils'
+import { IamInstanceProfile } from 'aws-sdk/clients/ec2'
 
 export class Ec2Client {
     public constructor(public readonly regionCode: string) {}
@@ -34,4 +35,50 @@ export class Ec2Client {
             .map(instance => instance?.InstanceId)
             .filter(instanceId => instanceId !== undefined)
     }
+
+    public async getInstanceStatus(instanceId: string): Promise<EC2.InstanceStateName> {
+        const client = await this.createSdkClient()
+        const requester = async (request: EC2.DescribeInstanceStatusRequest) =>
+            client.describeInstanceStatus(request).promise()
+
+        const response = await pageableToCollection(
+            requester,
+            { InstanceIds: [instanceId], IncludeAllInstances: true },
+            'NextToken',
+            'InstanceStatuses'
+        )
+            .flatten()
+            .map(instanceStatus => instanceStatus!.InstanceState!.Name!)
+            .promise()
+
+        return response[0]
+    }
+
+    /**
+     * Retrieve IAM role attached to given EC2 instance.
+     * @param instanceId target EC2 instance ID
+     * @returns IAM role associated with instance, or undefined if none exists.
+     */
+    public async getAttachedIamRole(instanceId: string): Promise<IamInstanceProfile | undefined> {
+        const client = await this.createSdkClient()
+        const instanceFilter: EC2.Filter[] = [
+            {
+                Name: 'instance-id',
+                Values: [instanceId],
+            },
+        ]
+        const requester = async (request: EC2.DescribeIamInstanceProfileAssociationsRequest) =>
+            client.describeIamInstanceProfileAssociations(request).promise()
+        const response = await pageableToCollection(
+            requester,
+            { Filters: instanceFilter },
+            'NextToken',
+            'IamInstanceProfileAssociations'
+        )
+            .flatten()
+            .map(val => val?.IamInstanceProfile)
+            .promise()
+
+        return response && response.length ? response[0] : undefined
+    }
 }

src/shared/clients/iamClient.ts

@@ -68,4 +68,22 @@ export class DefaultIamClient {
     private async createSdkClient(): Promise<IAM> {
         return await globals.sdkClientBuilder.createAwsService(IAM, undefined, this.regionCode)
     }
+
+    public getFriendlyName(arn: string): string {
+        const tokens = arn.split('/')
+        if (tokens.length < 2) {
+            throw new Error(
+                `Invalid IAM role ARN (expected format: arn:aws:iam::{id}/{name}): ${arn}`
+            )
+        }
+        return tokens[tokens.length - 1]
+    }
+
+    public async listAttachedRolePolicies(arn: string): Promise<IAM.ListAttachedRolePoliciesResponse> {
+        const client = await this.createSdkClient()
+        const roleName = this.getFriendlyName(arn)
+        const response = await client.listAttachedRolePolicies({ RoleName: roleName }).promise()
+
+        return response
+    }
 }

src/shared/errors.ts

@@ -155,6 +155,13 @@ export class ToolkitError extends Error implements ErrorInformation {
         return this.info.cancelled ?? isUserCancelledError(this.cause)
     }
 
+    /**
+     * The associated documentation, if it exists. Otherwise undefined.
+     */
+    public get documentationUri(): vscode.Uri | undefined {
+        return this.info.documentationUri
+    }
+
     /**
      * A formatted string that is analogous to a stack trace. While stack traces enumerate every
      * call site, this trace enumerates every throw site.