Create an AWS Task Definition to Run Liquibase Commands

There are multiple ways to operate Liquibase container within AWS. The example provided is specific to containers in ECS, and is one of several solutions. A task definition is a JSON text file that outlines how your containers operate in ECS. In the context of Liquibase, you write task definitions to run Liquibase commands on AWS. Follow the guide below to learn how to create Liquibase specific task definitions.

Prerequistes

  • Be familiar with AWS Task Definitions. Learn more about AWS from this guide: Creating an Amazon ECS task definition using the console
  • Create an S3 bucket or a GitHub repository to store configuration files
    • It is important to know the changelog, liquibase.properties file, JDBC drivers, and any file associated with your AWS project can be placed in the S3 bucket or GitHub repository.
  • If you are using S3, create an IAM user which has access to the S3 bucket.
  • Required additional AWS Resources:
    • MySQL RDS Instance - If you are using MySQL DB
    • AWS Fargate ECS cluster
    • IAM role to access the CloudWatch Logs, create Task Definitions, etc.

Step-by-step

Create a task definition for Liquibase commands in AWS Fargate

  1. Navigate to your Amazon Elastic Container Service console.
  2. Select Task definitions from the left side navigation.
  3. Click the Create a new task definition button. 

    Note: Use this example task definition below to build a new task by replacing the placeholder values of <PRO CONTAINER IMAGE LINK> and <S3 BUCKET NAME> with your values.


    • Copy

      Task Definition Example

      {
          "taskDefinitionArn": "arn:aws:ecs:us-east-1:{account_number}:task-definition/connect-command",
          "containerDefinitions": [
              {
                  "name": "Liquibase-Pro",
                  "image": "<PRO CONTAINER IMAGE LINK>",
                  "cpu": 0,
                  "portMappings": [],
                  "essential": true,
                  "command": [
                      "--defaults-file=s3://<s3 BUCKET NAME>/liquibase.properties",
                      "connect"
                  ],
                  "environment": [],
                  "mountPoints": [],
                  "volumesFrom": [],
                  "logConfiguration": {
                      "logDriver": "awslogs",
                      "options": {
                          "awslogs-group": "/ecs/connect-command",
                          "awslogs-create-group": "true",
                          "awslogs-region": "us-east-1",
                          "awslogs-stream-prefix": "ecs"
                      }
                  },
                  "systemControls": []
              }
          ],
          "family": "connect-command",
          "taskRoleArn": "arn:aws:iam::{account_number}:role/ecsTaskExecutionRole",
          "executionRoleArn": "arn:aws:iam::{account_number}:role/ecsTaskExecutionRole",
          "networkMode": "awsvpc",
          "revision": 1,
          "volumes": [],
          "status": "ACTIVE",
          "requiresAttributes": [
              {
                  "name": "com.amazonaws.ecs.capability.logging-driver.awslogs"
              },
              {
                  "name": "ecs.capability.execution-role-awslogs"
              },
              {
                  "name": "com.amazonaws.ecs.capability.ecr-auth"
              },
              {
                  "name": "com.amazonaws.ecs.capability.docker-remote-api.1.19"
              },
              {
                  "name": "com.amazonaws.ecs.capability.task-iam-role"
              },
              {
                  "name": "ecs.capability.execution-role-ecr-pull"
              },
              {
                  "name": "com.amazonaws.ecs.capability.docker-remote-api.1.18"
              },
              {
                  "name": "ecs.capability.task-eni"
              },
              {
                  "name": "com.amazonaws.ecs.capability.docker-remote-api.1.29"
              }
          ],
          "placementConstraints": [],
          "compatibilities": [
              "EC2",
              "FARGATE"
          ],
          "requiresCompatibilities": [
              "FARGATE"
          ],
          "cpu": "1024",
          "memory": "3072",
          "runtimePlatform": {
              "cpuArchitecture": "ARM64",
              "operatingSystemFamily": "LINUX"
          },
          "registeredAt": "2024-10-29T15:37:24.193Z",
          "registeredBy": "arn:aws:sts::{account_number}:assumed-role/AWSReservedSSO_MarketplaceLimitedPermissions_1c0e25eeb793d12a/{username}",
          "enableFaultInjection": false,
          "tags": []
      }

      • Note: In this example, task definitions are arranged as individual Liquibase commands. You can create batch task definitions that contain multiple Liquibase commands by following AWS best practices.

  4. Ensure that the Launch type selected is AWS Fargate.
  5. Set both the Task role and execution role to ecsTaskExecutionRole. This role is created by default when we create a ECS Fargate cluster.
  6. This is the container you may want to extend the Docker container to use SQL, mySQL, NoSQL, or any other type of extension.
    Ensure that Container has this Image URI: 709825985650.dkr.ecr.us-east-1.amazonaws.com/liquibase/liquibase/liquibase-pro:<insert_image_tag>
  7. If you work with MySQL DB, add INSTALL_MYSQL with a value of true.

    Note: INSTALL_MYSQL is our required Docker entrypoint.

  8. Click the Create button at the bottom of the page to complete mounting the files in Fargate.

Run Liquibase commands

Once the task definition is configured, you can begin running Liquibase commands as task definitions.

  1. Navigate to the Task definitions section on the left side navigation. Here you can define the Task definitions for the Liquibase commands you wish to run.
  2. Optional: Place the full image URL in a task definition to extend the Docker image
    You may want to extend your Docker image if you have several services that reuse a common set of configuration options or you use external tools like SQL Plus or SQLCMD. To extend our docker image and add other databases for a specific task definition, you must use the image URL that displays the ECR repository.

    Here is the repository URL that can be extended: 709825985650.dkr.ecr.us-east-1.amazonaws.com/liquibase/liquibase/liquibase-pro:4.30.0

    Note: You must use the ECR image URL displayed in the task definition to extend our docker image.

  3. Check the box next to the specific definition you want to revise.

  4. Click the Create new revision drop down menu and select Create new revision with JSON.

  5. From the Create new revision page you will see the line that starts with image; place the URL here to extend the docker image.

  6. Run a task definition by selecting the radio button next to the desired definition. In this example we will use connect-command.
  7. Select the Deploy button at the top of the screen.
  8. From the drop-down menu, select run task.
  9. Select the Compute options that you desire. In this example we will toggle Launch type on.
  10. Click the Create button.
  11. AWS will bring you to the tasks in your cluster. You will be able to see the task that is running in the Tasks tab below the Cluster Overview.
  12. Click on the task that is running in the Tasks tab.
  13. Click on the Logs tab to see all log events on any container you have specified in the Task Definition.

    This message will display if you have a license: Liquibase Pro 4.30.0 (license through AWS License Manager)

You have successfully run and viewed the logs of a Liquibase command on AWS.