feat: Add ad-hoc task runs

Author: inhumantsar

README.md

@@ -222,6 +222,26 @@ The minimal permissions require access to CodeDeploy:
 }
 ```
 
+## Running Tasks
+
+For services which need an initialization task, such as database migrations, or ECS tasks that are run without a service, additional configuration can be added to trigger an ad-hoc task run. When combined with GitHub Action's `on: schedule` triggers, runs can also be scheduled without EventBridge.
+
+In the following example, the service would not be updated until the ad-hoc task exits successfully.
+
+```yaml
+    - name: Deploy to Amazon ECS
+      uses: aws-actions/amazon-ecs-deploy-task-definition@v1
+      with:
+        task-definition: task-definition.json
+        service: my-service
+        cluster: my-cluster
+        wait-for-service-stability: true
+        run-task: true
+        wait-for-task-stopped: true
+```
+
+Overrides and VPC networking options are available as well. See [actions.yml](actions.yml) for more details.
+
 ## Troubleshooting
 
 This action emits debug logs to help troubleshoot deployment failures.  To see the debug logs, create a secret named `ACTIONS_STEP_DEBUG` with value `true` in your repository.

action.yml

@@ -34,6 +34,27 @@ inputs:
   force-new-deployment:
     description: 'Whether to force a new deployment of the service. Valid value is "true". Will default to not force a new deployment.'
     required: false
+  run-task:
+    description: 'Whether to run the task outside of an ECS service. Task will run before the service is updated if both are provided. Will default to not run.'
+    required: false
+  run-task-container-overrides:
+    description: 'A JSON array of container override objects which should applied when running a task outside of a service. Warning: Do not expose this field to untrusted inputs. More details: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerOverride.html'
+    required: false
+  run-task-security-groups:
+    description: 'A comma-separated list of security group IDs to assign to a task when run outside of a service. Will default to none.'
+    required: false
+  run-task-subnets:
+    description: 'A comma-separated list of subnet IDs to assign to a task when run outside of a service. Will default to none.'
+    required: false
+  run-task-launch-type:
+    description: "ECS launch type for tasks run outside of a service. Valid values are 'FARGATE' or 'EC2'. Will default to 'FARGATE'."
+    required: false
+  run-task-started-by:
+    description: 'A name to use for the startedBy tag when running a task outside of a service. Will default to 'GitHub-Actions'.'
+    required: false
+  wait-for-task-stopped:
+    description: 'Whether to wait for the task to stop when running it outside of a service. Will default to not wait.'
+    required: false
 outputs:
   task-definition-arn:
     description: 'The ARN of the registered ECS task definition'

index.js

@@ -20,6 +20,107 @@ const IGNORED_TASK_DEFINITION_ATTRIBUTES = [
   'registeredBy'
 ];
 
+// Run task outside of a service
+async function runTask(ecs, clusterName, taskDefArn, waitForMinutes) {
+  core.info('Running task')
+
+  const waitForTask = core.getInput('wait-for-task-stopped', { required: false }) || 'false';
+  const startedBy = core.getInput('run-task-started-by', { required: false }) || 'GitHub-Actions';
+  const launchType = core.getInput('run-task-launch-type', { required: false }) || 'FARGATE';
+  const subnetIds = core.getInput('run-task-subnet-ids', { required: false }) || '';
+  const securityGroupIds = core.getInput('run-task-security-group-ids', { required: false }) || '';
+  const containerOverrides = JSON.parse(core.getInput('run-task-container-overrides', { required: false }) || '[]');
+  let awsVpcNetworkConfiguration = {}
+
+  if (subnetIds != "") {
+    awsVpcNetworkConfiguration["subnets"] = subnetIds.split(',')
+  }
+
+  if (securityGroupIds != "") {
+    awsVpcNetworkConfiguration["securityGroups"] = securityGroupIds.split(',')
+  }
+
+  const runTaskResponse = await ecs.runTask({
+    startedBy: startedBy,
+    cluster: clusterName,
+    taskDefinition: taskDefArn,
+    overrides: {
+      containerOverrides: containerOverrides
+    },
+    launchType: launchType,
+    networkConfiguration: awsVpcNetworkConfiguration === {} ? {} : { awsVpcNetworkConfiguration: awsVpcNetworkConfiguration }
+  }).promise();
+
+  core.debug(`Run task response ${JSON.stringify(runTaskResponse)}`)
+
+  const taskArns = runTaskResponse.tasks.map(task => task.taskArn);
+  core.setOutput('run-task-arn', taskArns);
+
+  taskArns.map(taskArn => {
+    let taskId = taskArn.split('/').pop();
+    core.info(`Task running: https://console.aws.amazon.com/ecs/home?region=${aws.config.region}#/clusters/${clusterName}/tasks`)
+  });
+
+  if (runTaskResponse.failures && runTaskResponse.failures.length > 0) {
+    const failure = runTaskResponse.failures[0];
+    throw new Error(`${failure.arn} is ${failure.reason}`);
+  }
+
+  // Wait for task to end
+  if (waitForTask && waitForTask.toLowerCase() === "true") {
+    await waitForTasksStopped(ecs, clusterName, taskArns, waitForMinutes)
+    await tasksExitCode(ecs, clusterName, taskArns)
+  } else {
+    core.debug('Not waiting for the task to stop');
+  }
+}
+
+// Poll tasks until they enter a stopped state
+async function waitForTasksStopped(ecs, clusterName, taskArns, waitForMinutes) {
+  if (waitForMinutes > MAX_WAIT_MINUTES) {
+    waitForMinutes = MAX_WAIT_MINUTES;
+  }
+
+  core.info(`Waiting for tasks to stop. Will wait for ${waitForMinutes} minutes`);
+
+  const waitTaskResponse = await ecs.waitFor('tasksStopped', {
+    cluster: clusterName,
+    tasks: taskArns,
+    $waiter: {
+      delay: WAIT_DEFAULT_DELAY_SEC,
+      maxAttempts: (waitForMinutes * 60) / WAIT_DEFAULT_DELAY_SEC
+    }
+  }).promise();
+
+  core.debug(`Run task response ${JSON.stringify(waitTaskResponse)}`);
+  core.info('All tasks have stopped.');
+}
+
+// Check a task's exit code and fail the job on error
+async function tasksExitCode(ecs, clusterName, taskArns) {
+  const describeResponse = await ecs.describeTasks({
+    cluster: clusterName,
+    tasks: taskArns
+  }).promise();
+
+  const containers = [].concat(...describeResponse.tasks.map(task => task.containers))
+  const exitCodes = containers.map(container => container.exitCode)
+  const reasons = containers.map(container => container.reason)
+
+  const failuresIdx = [];
+
+  exitCodes.filter((exitCode, index) => {
+    if (exitCode !== 0) {
+      failuresIdx.push(index)
+    }
+  })
+
+  const failures = reasons.filter((_, index) => failuresIdx.indexOf(index) !== -1)
+  if (failures.length > 0) {
+    throw new Error(`Run task failed: ${JSON.stringify(failures)}`);
+  }
+}
+
 // Deploy to a service that uses the 'ECS' deployment controller
 async function updateEcsService(ecs, clusterName, service, taskDefArn, waitForService, waitForMinutes, forceNewDeployment) {
   core.debug('Updating the service');
@@ -285,10 +386,18 @@ async function run() {
     const taskDefArn = registerResponse.taskDefinition.taskDefinitionArn;
     core.setOutput('task-definition-arn', taskDefArn);
 
+    // Run the task outside of the service
+    const clusterName = cluster ? cluster : 'default';
+    const shouldRunTaskInput = core.getInput('run-task', { required: false }) || 'false';
+    const shouldRunTask = shouldRunTaskInput.toLowerCase() === 'true';
+    if (shouldRunTask) {
+      await runTask(ecs, clusterName, taskDefArn, waitForMinutes);
+    } else {
+      core.debug('run-task is not true, skipping.')
+    }
+
     // Update the service with the new task definition
     if (service) {
-      const clusterName = cluster ? cluster : 'default';
-
       // Determine the deployment controller
       const describeResponse = await ecs.describeServices({
         services: [service],

index.test.js

@@ -13,6 +13,8 @@ const mockEcsWaiter = jest.fn();
 const mockCodeDeployCreateDeployment = jest.fn();
 const mockCodeDeployGetDeploymentGroup = jest.fn();
 const mockCodeDeployWaiter = jest.fn();
+const mockRunTask = jest.fn();
+const mockEcsDescribeTasks = jest.fn();
 jest.mock('aws-sdk', () => {
     return {
         config: {
@@ -22,7 +24,9 @@ jest.mock('aws-sdk', () => {
             registerTaskDefinition: mockEcsRegisterTaskDef,
             updateService: mockEcsUpdateService,
             describeServices: mockEcsDescribeServices,
-            waitFor: mockEcsWaiter
+            waitFor: mockEcsWaiter,
+            describeTasks: mockEcsDescribeTasks,
+            runTask: mockRunTask
         })),
         CodeDeploy: jest.fn(() => ({
             createDeployment: mockCodeDeployCreateDeployment,
@@ -144,6 +148,58 @@ describe('Deploy to ECS', () => {
                 }
             };
         });
+
+        mockRunTask.mockImplementation(() => {
+            return {
+                promise() {
+                    return Promise.resolve({
+                        failures: [],
+                        tasks: [
+                            {
+                                containers: [
+                                    {
+                                        lastStatus: "RUNNING",
+                                        exitCode: 0,
+                                        reason: '',
+                                        taskArn: "arn:aws:ecs:fake-region:account_id:task/arn"
+                                    }
+                                ],
+                                desiredStatus: "RUNNING",
+                                lastStatus: "RUNNING",
+                                taskArn: "arn:aws:ecs:fake-region:account_id:task/arn"
+                                // taskDefinitionArn: "arn:aws:ecs:<region>:<aws_account_id>:task-definition/amazon-ecs-sample:1"
+                            }
+                        ]
+                    });
+                }
+            };
+        });
+
+        mockEcsDescribeTasks.mockImplementation(() => {
+            return {
+                promise() {
+                    return Promise.resolve({
+                        failures: [],
+                        tasks: [
+                            {
+                                containers: [
+                                    {
+                                        lastStatus: "RUNNING",
+                                        exitCode: 0,
+                                        reason: '',
+                                        taskArn: "arn:aws:ecs:fake-region:account_id:task/arn"
+                                    }
+                                ],
+                                desiredStatus: "RUNNING",
+                                lastStatus: "RUNNING",
+                                taskArn: "arn:aws:ecs:fake-region:account_id:task/arn"
+                            }
+                        ]
+                    });
+                }
+            };
+        });
+
     });
 
      test('registers the task definition contents and updates the service', async () => {
@@ -641,6 +697,7 @@ describe('Deploy to ECS', () => {
             .mockReturnValueOnce('false')               // wait-for-service-stability
             .mockReturnValueOnce('')                    // wait-for-minutes
             .mockReturnValueOnce('')                    // force-new-deployment
+            .mockReturnValueOnce('')                    // run-task
             .mockReturnValueOnce('/hello/appspec.json') // codedeploy-appspec
             .mockReturnValueOnce('MyApplication')       // codedeploy-application
             .mockReturnValueOnce('MyDeploymentGroup');  // codedeploy-deployment-group
@@ -1022,6 +1079,88 @@ describe('Deploy to ECS', () => {
         expect(mockEcsUpdateService).toHaveBeenCalledTimes(0);
     });
 
+    test('run task', async () => {
+        core.getInput = jest
+            .fn()
+            .mockReturnValueOnce('task-definition.json')  // task-definition
+            .mockReturnValueOnce('')                      // service
+            .mockReturnValueOnce('')                      // cluster
+            .mockReturnValueOnce('')                      // wait-for-service-stability
+            .mockReturnValueOnce('')                      // wait-for-minutes
+            .mockReturnValueOnce('')                      // force-new-deployment
+            .mockReturnValueOnce('true');                 // run-task
+
+        await run();
+        expect(core.setFailed).toHaveBeenCalledTimes(0);
+
+        expect(mockEcsRegisterTaskDef).toHaveBeenNthCalledWith(1, { family: 'task-def-family' });
+        expect(core.setOutput).toHaveBeenNthCalledWith(1, 'task-definition-arn', 'task:def:arn');
+        expect(mockRunTask).toHaveBeenCalledTimes(1);
+        expect(core.setOutput).toHaveBeenNthCalledWith(2, 'run-task-arn', ["arn:aws:ecs:fake-region:account_id:task/arn"]);
+    });
+
+    test('run task with options', async () => {
+        core.getInput = jest
+            .fn()
+            .mockReturnValueOnce('task-definition.json')  // task-definition
+            .mockReturnValueOnce('')                      // service
+            .mockReturnValueOnce('somecluster')           // cluster
+            .mockReturnValueOnce('')                      // wait-for-service-stability
+            .mockReturnValueOnce('')                      // wait-for-minutes
+            .mockReturnValueOnce('')                      // force-new-deployment
+            .mockReturnValueOnce('true')                  // run-task
+            .mockReturnValueOnce('false')                 // wait-for-task-stopped
+            .mockReturnValueOnce('someJoe')               // run-task-started-by
+            .mockReturnValueOnce('EC2')                   // run-task-launch-type
+            .mockReturnValueOnce('a,b')                   // run-task-subnet-ids
+            .mockReturnValueOnce('c,d')                   // run-task-security-group-ids
+            .mockReturnValueOnce(JSON.stringify([{ name: 'someapp', command: 'somecmd' }])); // run-task-container-overrides
+
+        await run();
+        expect(core.setFailed).toHaveBeenCalledTimes(0);
+
+        expect(mockEcsRegisterTaskDef).toHaveBeenNthCalledWith(1, { family: 'task-def-family' });
+        expect(core.setOutput).toHaveBeenNthCalledWith(1, 'task-definition-arn', 'task:def:arn');
+        expect(mockRunTask).toHaveBeenCalledWith({
+            startedBy: 'someJoe',
+            cluster: 'somecluster',
+            launchType: "EC2",
+            taskDefinition: 'task:def:arn',
+            overrides: { containerOverrides: [{ name: 'someapp', command: 'somecmd' }] },
+            networkConfiguration: { awsVpcNetworkConfiguration: { subnets: ['a', 'b'], securityGroups: ['c', 'd'] } }
+        });
+        expect(core.setOutput).toHaveBeenNthCalledWith(2, 'run-task-arn', ["arn:aws:ecs:fake-region:account_id:task/arn"]);
+    });
+
+    test('run task and wait for it to stop', async () => {
+        core.getInput = jest
+            .fn()
+            .mockReturnValueOnce('task-definition.json')  // task-definition
+            .mockReturnValueOnce('')                      // service
+            .mockReturnValueOnce('somecluster')           // cluster
+            .mockReturnValueOnce('')                      // wait-for-service-stability
+            .mockReturnValueOnce('')                      // wait-for-minutes
+            .mockReturnValueOnce('')                      // force-new-deployment
+            .mockReturnValueOnce('true')                  // run-task
+            .mockReturnValueOnce('true');                 // wait-for-task-stopped
+
+        await run();
+        expect(core.setFailed).toHaveBeenCalledTimes(0);
+
+        expect(mockEcsRegisterTaskDef).toHaveBeenNthCalledWith(1, { family: 'task-def-family' });
+        expect(core.setOutput).toHaveBeenNthCalledWith(1, 'task-definition-arn', 'task:def:arn')
+        expect(mockRunTask).toHaveBeenCalledTimes(1);
+        expect(core.setOutput).toHaveBeenNthCalledWith(2, 'run-task-arn', ["arn:aws:ecs:fake-region:account_id:task/arn"])
+        expect(mockEcsWaiter).toHaveBeenNthCalledWith(1, 'tasksStopped', {
+            tasks: ['arn:aws:ecs:fake-region:account_id:task/arn'],
+            cluster: 'somecluster',
+            "$waiter": {
+                "delay": 15,
+                "maxAttempts": 120,
+            },
+        });
+    });
+
     test('error caught if AppSpec file is not formatted correctly', async () => {
         mockEcsDescribeServices.mockImplementation(() => {
             return {