Adding the "Render Amazon ECS task definition" action - Amazon CodeCatalyst
When to use this actionHow it worksExample workflowAdding the "Render Amazon ECS task definition" actionViewing the updated task definition fileVariables produced by the "Render Amazon ECS task definition" action"Render Amazon ECS task definition" action definition

Adding the "Render Amazon ECS task definition" action

This section describes how to add the Render Amazon ECS task definition action to your workflow. This action updates the image field in an Amazon Elastic Container Service (Amazon ECS) task definition file with a Docker image name that is supplied by your workflow at runtime.

Note

You can also use this action to update the task definition’s environment field with environment variables.

When to use this action

Use this if you have a workflow that builds and tags a Docker image with dynamic content, such as a commit ID or timestamp.

Do not use this action if your task definition file contains an image value that always stays the same. In this case, you can manually enter the name of your image into the task definition file.

How it works

You must use the Render Amazon ECS task definition action with the build and Deploy to Amazon ECS actions in your workflow. Together, these actions work as follows:

  1. The build action builds your Docker image and tags it with a name, a commit ID, timestamp, or other dynamic content. For example, your build action might look like this:

    MyECSWorkflow
  Actions:
    BuildAction:
      Identifier: aws/build@v1
      ...
      Configuration:
        Steps:
        # Build, tag, and push the Docker image...
          - Run: docker build -t MyDockerImage:${WorkflowSource.CommitId} .
          ...

    In the preceding code, the docker build -t directive indicates to build the Docker image and tag it with the commit ID at action runtime. The generated image name might look like this:

    MyDockerImage:a37bd7e

  2. The Render Amazon ECS task definition action adds the dynamically generated image name, MyDockerImage:a37bd7e, to your task definition file, like this:

    {
    "executionRoleArn": "arn:aws:iam::account_ID:role/codecatalyst-ecs-task-execution-role",
    "containerDefinitions": [
        {
            "name": "codecatalyst-ecs-container",
            "image":  MyDockerImage:a37bd7e, 
            "essential": true,
            ...
            "portMappings": [
                {
                    "hostPort": 80,
                    "protocol": "tcp",
                    "containerPort": 80
                }
            ]
        }
    ],
...
}

    Optionally, you can also have the Render Amazon ECS task definition action add environment variables to the task definition, like this:

    {
  "executionRoleArn": "arn:aws:iam::account_ID:role/codecatalyst-ecs-task-execution-role",
  "containerDefinitions": [
    {
      "name": "codecatalyst-ecs-container",
      "image":  MyDockerImage:a37bd7e,
      ...
      "environment": [
        {
          name": "ECS_LOGLEVEL",
          value": "info"
        }
      ]
    }
  ],
...
}

    For more information about environment variables, see Specifying environment variables in the Amazon Elastic Container Service Developer Guide.

  3. The Deploy to Amazon ECS action registers the updated task definition file with Amazon ECS. Registering the updated task definition file deploys the new image, MyDockerImage:a37bd7e into Amazon ECS.

Example workflow

The following is an example of a full workflow that includes the Render Amazon ECS task definition action, along with build and deploy actions. The workflow’s purpose is to build and deploy a Docker image into your Amazon ECS cluster. The workflow consists of the following building blocks that run sequentially:

  • A trigger – This trigger starts the workflow run automatically when you push a change to your source repository. For more information about triggers, see Working with triggers.

  • A build action (BuildDocker) – On trigger, the action builds the Docker image using the Dockerfile, tags it with a commit ID, and pushes the image to Amazon ECR. For more information about the build action, see Building using workflows in CodeCatalyst.

  • A Render Amazon ECS task definition action (RenderTaskDef) – On completion of the build action, this action updates an existing taskdef.json located in the root of your source repository with an image field value that includes the correct commit ID. It saves the updated file with a new file name (task-definition-random-string.json) and then creates an output artifact that contains this file. The render action also generates a variable called task-definition and sets it to the name of the new task definition file. The artifact and variable will be used the deploy action, which is next.

  • A Deploy to Amazon ECS action (DeployToECS) – On completion of the Render Amazon ECS task definition action, the Deploy to Amazon ECS action looks for the output artifact generated by the render action (TaskDefArtifact), finds the task-definition-random-string.json file inside of it, and registers it with your Amazon ECS service. The Amazon ECS service then follows the instructions in the task-definition-random-string.json file to run Amazon ECS tasks—and associated Docker image containers—inside your Amazon ECS cluster. 

Name: codecatalyst-ecs-workflow
SchemaVersion: 1.0

Triggers:
  - Type: PUSH
    Branches:
      - main
Actions:
  BuildDocker:
    Identifier: aws/build@v1
    Environment:
      Name: codecatalyst-ecs-environment
      Connections:
        - Name: codecatalyst-account-connection
          Role: codecatalyst-ecs-build-role
    Inputs:
      Variables:
        - Name: REPOSITORY_URI
          Value: 111122223333.dkr.ecr.us-east-2.amazonaws.com/codecatalyst-ecs-image-repo
        - Name: IMAGE_TAG
          Value: ${WorkflowSource.CommitId}
    Configuration:
      Steps:
        #pre_build:
        - Run: echo Logging in to Amazon ECR...
        - Run: aws --version
        - Run: aws ecr get-login-password --region us-east-2 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-east-2.amazonaws.com
        #build:
        - Run: echo Build started on `date`
        - Run: echo Building the Docker image...
        - Run: docker build -t $REPOSITORY_URI:latest .
        - Run: docker tag $REPOSITORY_URI:latest $REPOSITORY_URI:$IMAGE_TAG
        #post_build:
        - Run: echo Build completed on `date`
        - Run: echo Pushing the Docker images...
        - Run: docker push $REPOSITORY_URI:latest
        - Run: docker push $REPOSITORY_URI:$IMAGE_TAG
        
  RenderTaskDef:
    DependsOn: 
      - BuildDocker
    Identifier: aws/ecs-render-task-definition@v1
    Inputs:
      Variables:
        - Name: REPOSITORY_URI
          Value: 111122223333.dkr.ecr.us-east-2.amazonaws.com/codecatalyst-ecs-image-repo
        - Name: IMAGE_TAG
          Value: ${WorkflowSource.CommitId}
    Configuration:      
      task-definition: taskdef.json
      container-definition-name: codecatalyst-ecs-container
      image: $REPOSITORY_URI:$IMAGE_TAG 
    # The output artifact contains the updated task definition file. 
    # The new file is prefixed with 'task-definition'.
    # The output variable is set to the name of the updated task definition file. 
    Outputs:
      Artifacts:
        - Name: TaskDefArtifact
          Files: 
            - "task-definition*"
      Variables:
        - task-definition
        
  DeployToECS:
    Identifier: aws/ecs-deploy@v1
    Environment:
      Name: codecatalyst-ecs-environment
      Connections:
        - Name: codecatalyst-account-connection
          Role: codecatalyst-ecs-deploy-role
    #Input artifact contains the updated task definition file.
    Inputs:
      Sources: []
      Artifacts:
        - TaskDefArtifact
    Configuration:
      region: us-east-2
      cluster: codecatalyst-ecs-cluster
      service: codecatalyst-ecs-service
      task-definition: ${RenderTaskDef.task-definition}

Adding the "Render Amazon ECS task definition" action

Use the following instructions to add the Render Amazon ECS task definition action to your workflow.

Prerequisite

Before you begin, make sure you have a workflow that includes a build action that dynamically generates a Docker image. See the preceding example workflow for details.

Visual
To add the "Render Amazon ECS task definition" action using the visual editor

  1. Open the CodeCatalyst console at https://codecatalyst.aws/.

  2. Choose your project.

  3. In the navigation pane, choose CI/CD, and then choose Workflows.

  4. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name.

  5. Choose Edit.

  6. Choose Visual.

  7. At the top-left, choose + Actions to open the action catalog.

  8. From the drop-down list, choose Amazon CodeCatalyst.

  9. Search for the Render Amazon ECS task definition action, and do one of the following:

    • Choose the plus sign (+) to add the action to the workflow diagram and open its configuration pane.

      Or

    • Choose Render Amazon ECS task definition. The action details dialog box appears. On this dialog box:

      • (Optional) Choose View source to view the action's source code.

      • Choose Add to workflow to add the action to the workflow diagram and open its configuration pane.

  10. In the Inputs and Configuration tabs, complete the fields according to your needs. For a description of each field, see the "Render Amazon ECS task definition" action reference. This reference provides detailed information about each field (and corresponding YAML property value) as it appears in both the YAML and visual editors.

  11. (Optional) Choose Validate to validate the workflow's YAML code before committing.

  12. Choose Commit, enter a commit message, and choose Commit again.

YAML
To add the "Render Amazon ECS task definition" action using the YAML editor

  1. Open the CodeCatalyst console at https://codecatalyst.aws/.

  2. Choose your project.

  3. In the navigation pane, choose CI/CD, and then choose Workflows.

  4. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name.

  5. Choose Edit.

  6. Choose YAML.

  7. At the top-left, choose + Actions to open the action catalog.

  8. From the drop-down list, choose Amazon CodeCatalyst.

  9. Search for the Render Amazon ECS task definition action, and do one of the following:

    • Choose the plus sign (+) to add the action to the workflow diagram and open its configuration pane.

      Or

    • Choose Render Amazon ECS task definition. The action details dialog box appears. On this dialog box:

      • (Optional) Choose View source to view the action's source code.

      • Choose Add to workflow to add the action to the workflow diagram and open its configuration pane.

  10. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the "Render Amazon ECS task definition" action reference.

  11. (Optional) Choose Validate to validate the workflow's YAML code before committing.

  12. Choose Commit, enter a commit message, and choose Commit again.
Next steps

After adding the render action, add the Deploy to Amazon ECS action to your workflow following the instructions in Adding the "Deploy to Amazon ECS" action. While adding the deploy action, do the following:

  1. In the Inputs tab of the deploy action, in Artifacts - optional, select the artifact that was generated by the render action. It contains the updated task definition file.

    For more information about artifacts, see Working with artifacts.

  2. In the Configuration tab of the deploy action, in the Task definition field, specify the following action variable: ${action-name.task-definition} where action-name is the name of your render action, for example, RenderTaskDef. The render action sets this variable to the new name of the task definition file.

    For more information about variables, see Working with variables.

    For more information about how to configure the deploy action, see the preceding example workflow.

Viewing the updated task definition file

You can view the name and contents of the updated task definition file.

To view the name of the updated task definition file, after the Render Amazon ECS task definition action has processed it.

  1. Find the run that includes a completed render action:

    1. Open the CodeCatalyst console at https://codecatalyst.aws/.

    2. Choose your project.

    3. In the navigation pane, choose CI/CD, and then choose Workflows.

    4. Choose the name of the workflow that contains the render action. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name.

    5. Choose a run that includes the completed render action.

  2. In the workflow diagram, choose the render action.

  3. Choose Outputs.

  4. Choose Variables.

  5. The task definition file name is displayed. It looks similar to task-definition--259-0a2r7gxlTF5X-.json.

To view the contents of the updated task definition file

  1. Find the run that includes a completed render action:

    1. Open the CodeCatalyst console at https://codecatalyst.aws/.

    2. Choose your project.

    3. In the navigation pane, choose CI/CD, and then choose Workflows.

    4. Choose the name of the workflow that contains the render action. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name.

    5. Choose a run that includes the completed render action.

  2. In the workflow run, at the top, next to Visual and YAML, choose Workflow outputs.

  3. In the Artifacts section, choose Download next to the artifact that contains the updated task definition file. This artifact will have a Produced by column set to the name of your render action.

  4. Open the .zip file to view the task definition .json file.

Variables produced by the "Render Amazon ECS task definition" action

When the Render Amazon ECS task definition action runs, it produces variables that you can use in subsequent workflow actions. For details, see "Render Amazon ECS task definition" action output variables in the Workflow output variable reference.

"Render Amazon ECS task definition" action definition

The Render Amazon ECS task definition action is defined as a set of YAML properties inside your workflow definition file. For information about these properties, see "Render Amazon ECS task definition" action reference in the Workflow definition reference.