feat(ecs): show more context for missing permissions #3798

ref #3797

Author: justinmk3

.changes/next-release/Feature-b29743c8-4740-4e98-a965-204fe972a058.json

@@ -0,0 +1,4 @@
+{
+	"type": "Feature",
+	"description": "ECS: \"Insufficient permissions\" message shows more details about missing permissions"
+}

src/ecs/util.ts

@@ -8,7 +8,6 @@ import globals from '../shared/extensionGlobals'
 import * as nls from 'vscode-nls'
 const localize = nls.loadMessageBundle()
 
-import * as vscode from 'vscode'
 import { EcsClient } from '../shared/clients/ecsClient'
 import { IamClient } from '../shared/clients/iamClient'
 import { ToolkitError } from '../shared/errors'
@@ -18,29 +17,29 @@ import { TaskDefinition } from 'aws-sdk/clients/ecs'
 import { getLogger } from '../shared/logger'
 import { SSM } from 'aws-sdk'
 import { fromExtensionManifest } from '../shared/settings'
+import { ecsTaskPermissionsUrl } from '../shared/constants'
 
 interface EcsTaskIdentifer {
     readonly task: string
     readonly cluster: string
     readonly container: string
 }
 
-const permissionsDocumentation = vscode.Uri.parse(
-    'https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html#ecs-exec-enabling-and-using',
-    true
-)
-
+/**
+ * See also: https://github.com/aws-containers/amazon-ecs-exec-checker
+ */
 export async function checkPermissionsForSsm(
     client: IamClient,
     task: Pick<TaskDefinition, 'taskRoleArn'>
 ): Promise<void | never> {
     if (!task.taskRoleArn) {
         throw new ToolkitError('Containers must have a task role ARN', {
             code: 'NoTaskRoleArn',
-            documentationUri: permissionsDocumentation,
+            documentationUri: ecsTaskPermissionsUrl,
         })
     }
 
+    // https://github.com/aws-containers/amazon-ecs-exec-checker/blob/b1d163bd95c5b6f915e2bb3ad810e6f2aecae985/check-ecs-exec.sh#L536-L539
     const deniedActions = await client.getDeniedActions({
         PolicySourceArn: task.taskRoleArn,
         ActionNames: [
@@ -52,14 +51,18 @@ export async function checkPermissionsForSsm(
     })
 
     if (deniedActions.length !== 0) {
+        const deniedMsg = deniedActions.map(o => o.EvalActionName).join(', ')
         const message = localize(
             'AWS.command.ecs.runCommandInContainer.missingPermissions',
-            'Insufficient permissions to execute command. Configure a task role as described in the documentation.'
+            'Insufficient permissions to execute command, ensure the [task role is configured]({0}). Task role {1} is not authorized to perform: {2}',
+            ecsTaskPermissionsUrl.toString(),
+            task.taskRoleArn,
+            deniedMsg
         )
 
         throw new ToolkitError(message, {
             code: 'MissingPermissions',
-            documentationUri: permissionsDocumentation,
+            documentationUri: ecsTaskPermissionsUrl,
             details: { deniedActions: deniedActions.map(a => a.EvalActionName) },
         })
     }

src/shared/constants.ts

@@ -101,10 +101,12 @@ export const debugNewSamAppUrl: string = isCloud9()
 export const ecsDocumentationUrl: string = 'https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html'
 export const ecsExecToolkitGuideUrl: string =
     'https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/ecs-exec.html'
-export const ecsRequiredTaskPermissionsUrl: string =
+export const ecsTaskPermissionsUrl = vscode.Uri.parse(
     'https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html#ecs-exec-enabling-and-using'
-export const ecsRequiredIamPermissionsUrl: string =
+)
+export const ecsIamPermissionsUrl = vscode.Uri.parse(
     'https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html#ecs-exec-best-practices-limit-access-execute-command'
+)
 
 /**
  * Moment format for rendering readable dates.