Maia runner installation using a CloudFormation quick-create link

This article details how to install a Maia runner on Amazon ECS Fargate using a CloudFormation template quick-create link. The quick-create CloudFormation link will pre-fill values into the template for you.

Alternatively, you can download the CloudFormation template and edit as needed.

Expand this box to watch our video about how to install the AWS ECS/Fargate hybrid runner for Maia.

Video: How to Install the AWS ECS/Fargate Hybrid Runner for Maia

---

Prerequisites

To get started, you’ll need:

• A Maia account. To register, read Registration.
• Access to AWS, with the permissions to create a stack on a billable account. You may need an administrator from your organization to either give access or perform this process with you.
• Permissions to provision cloud resources in the AWS environment that the source database is running in.
• An IAM role that has suitable permissions for Maia. If you’re using the same IAM role, you might need to add cloudformation.amazonaws.com to the Service section in the Trust Relationship section of your IAM role to allow the role to work with the ECS service. An example trusted entity can be found below. Read AWS IAM roles for more information about creating IAM roles.

You’ll also need to allow the IP addresses listed in Network access and IP AllowList requirements.

Example trusted entity:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "",
            "Effect": "Allow",
            "Principal": {
                "Service": "cloudformation.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

To learn more about the trust relationship IAM policies, read trust policies.

We recommend that you read the documentation and prerequisites before beginning this process. You may require input from your organization’s cloud administrator for access and permissions.

For detailed AWS permission information about deploying a Maia runner in Maia, read AWS IAM permissions for runner deployment.

---

Created resources

This template will create the following resources in your AWS account:

• ECS task definition.
• ECS Fargate cluster.
• CloudWatch log group.
• An entry in AWS Secrets Manager.
• IAM roles with permissions for the following:
  • Task roles to your ECS, EC2, and Secrets Manager.
  • Task execution roles to pull from ECR Public repositories.

Each Maia runner requires its own separate ECS cluster. Deploying this template for a new Maia runner creates a new, dedicated cluster—don’t reuse an existing cluster from another Maia runner.

---

Visualization

---

Using the CloudFormation link

1. Create a Maia runner in Maia.

2. On the Runner details page, note the Credentials: client_id and client secret.

3. On the Deployment tab of the Runner details page, click the Launch button. This will launch the CloudFormation stack in the AWS Console with pre-filled values for most parameters.

4. Complete the remaining parameters as follows:

   • Stack name: An arbitrary name given to the created stack. Must be unique. This will be pre-filled, but if you are reinstalling a Maia runner you will need to change the stack name. Consider increasing the number that is added to the end of the stack name.
   • OAuth Client ID: Copy the retrieved client_id from the Runner details page.
   • OAuth Client Secret: Copy the retrieved client_secret from the Runner details page.
   • VPC ID: Select the ID of an existing VPC. For more information, read VPCs.
   • VPC Subnet IDs: Select at least one VPC subnet to use.

5. Click Create stack.

Once your stack is ready, this means the ECS service has now successfully deployed. The Maia runner will then start. You can return to the Maia runner dashboard and view the Maia runners list. Your new Maia runner will be on the list and will have a Running status.

---

Troubleshoot Maia runner

ECS Execute Command lets you open an interactive terminal session inside a running Fargate container directly from the AWS CLI. It isn’t enabled by default in the CloudFormation template and isn’t generally recommended for troubleshooting, because the Maia runner behaves differently in an interactive terminal session than during actual pipeline execution. In some specific situations, Matillion Support or engineering may guide you to enable it. Only do so under their direction.