How to Run ECS Windows Task with group Managed Service Account (gMSA)

Amazon Elastic Container Service(ECS) recently announced gMSA support, and the focus of this blog post is to show you how to deploy a Windows Task with gMSA credentials. Though the main focus is on ECS Task, I will also show you how to set up an AWS managed Active Directory with a gMSA account, and enable an EC2 Auto Scaling group to automatically join newly launched ECS Windows instances to a target domain.

First, here is a brief introduction to gMSA

Windows-based networks commonly use Active Directory to facilitate authentication and authorization between users, computers, and other computer network resources. Traditionally, enterprise applications running on Windows platforms use either service accounts or Managed Service Accounts (MSA) for authentication and authorization. The use of service accounts brings with it the overhead of service account password management. In contrast, Managed Service Accounts don’t have any password management overhead. They are limited to a single computer account; they can’t be used on more than one computer. Group Managed Service Account (gMSA) is a special type of service account; its identity can be shared across multiple computers without needing to know the password. Computers should be part of an Active Directory domain, which manages these service accounts to make use of them. Although Windows containers cannot join a domain like an instance, they can still use gMSA identity for authentication and authorization.

Prerequisites and Assumptions

• You have properly installed and configured the AWS CLI and PowerShell core on your computer.
• This blog post applies to ECS Windows instances only.
• This blog post talks about managed Active Directory, but it should also work with other Active Directory scenarios as long as the ECS Windows instances can join the domain.
• Configuring instances to join a domain and creating an Active Directory security group require Active Directory credentials, and this blog post uses SSM Parameter Store to store Active Directory related information.
• You have cloned the artifacts from this repo.
• I chose to use the AWS CLI for these steps, so that end-to-end workflow can be demonstrated, but you can use AWS Management Console as well.
• You have an ECS Cluster setup with Windows instances and autoscaling is enabled.

I’ve divided this blog post into six parts. The first three parts discusses required infrastructure setup, the fourth and fifth part talks about sample two tier application and gMSA account creation and the last part discusses deployment of ECS Tasks with gMSA.

Part 1: Infrastructure Setup

Follow the instructions in GitHub to complete the infrastructure setup up, such as setting up AWS managed Active Directory, SSM documents to join domain, and to generate new gMSA account. If you’ve an existing Active Directory, update SSM parameters to use your Active Directory information.
Please note that the blog assumes that Active Directory is created in the same VPC as your ECS Worker node VPC. Otherwise you should have established the cross VPC Active Directory communication.

Part 2: Launch ECS Windows instances

You can launch ECS Windows instance either from ECS console or from EC2 console. For getting started please refer here. The gMSA feature has started support from ECS agent version 1.34, so when you launch the ECS Windows instance, make sure you’ve agent version 1.34 or latest. By default, gMSA capability is enabled in all ECS Windows instances, provided they are member of an Active Directory.

Part 3: Attach DomainJoin SSM document to ECS Windows instances

Once ECS Windows instances are created, instances need to join the Active Directory domain and part of an Active Directory security group to allow gMSA authentication and authorization. We are going to use SSM document to achieve this. The SSM document can be executed on-demand or can be specified in user data section or can be associated based on instance tag. This way when an autoscaling group scales up, the SSM document will be executed automatically. For more details about SSM associations please refer here.

Whenever an autoscaling group scales up an instance, it creates an instance tag “aws:autoscaling:groupName”. We are going to use this tag and attach the SSM document. Follow the instructions in GitHub to attach a SSM document that will join the instance to the domain and give required IAM policies for the node instance role. Once the SSM document is attached, the instances will start executing the document once and whenever the Auto Scaling group launches a new instance with this tag.

At this point, we should have an Active Directory setup, ECS cluster and ECS instances running that have joined the Active Directory and are associated with an Active Directory security group. The next section will talk about the gMSA account setup and ECS Task deployments.

Part 4: Create Sample Application containers

A sample two-tier application is developed to demonstrate the gMSA authentication. The ASP .NET Core web application authenticates with the backend SQL Server bookstore database using the gMSA account. The application performs basic add, edit, list, and delete operations.  Both the front end and database applications are running in containers and deployed with gMSA credential specifications.

The steps in GitHub will create the container images in all the instances part of autoscaling group.

Part 5: Create gMSA Account

A gMSA credential spec is a JSON file generated by Active Directory PowerShell module. The file contains metadata about one more gMSA accounts intended to be used with containers. Following the steps here will create a gMSA account and generate the spec file. Save the spec file content in SSM parameter store or in S3 or save it to locally in ECS Windows instances (under %programdata%\docker\credentialspecs path).

Part 6: ECS Task Definition with gMSA

The credential spec can be specified in “dockerSecurityOptions” field in Task definition. Though the field name is dockerSecurityOptions, as far as gMSA, it’s not a pass through docker security options. ECS supports three sources for the docker security options. Follow the instructions in Github to deploy the sample task definitions with gMSA.

1. File option: It’s your responsibility to have the credential spec file in the ECS Windows instance. The file specified here should be relative to the path “%programdata%\docker\credentialspecs”
2. SSM Parameter option: You can store the credentialspec content in SSM parameter and reference the SSM ARN in task definition. "credentialspec:arn:aws:ssm:${Region}:$(Account}:parameter/${ParameterName}”
3. S3 option: You can store the credentialspec file in S3 and reference the S3 ARN in task definition.  "credentialspec:arn:aws:s3:::${BucketName}/${ObjectName}"

Sample Task definition:

  "containerDefinitions": [
    {
      "name": "containermvc-app",
      "image": "containermvc-web:latest",
      "cpu": 512,
      "entryPoint":["powershell"],
      "dockerSecurityOptions": [
            "credentialspec:file://gmsa_foouser1.json"
      ]
    }
]

To show the difference between SQL authentication and gMSA authentication, I’ve included a CreatedBy column in the list. The initial ones are populated by SQL account (sa) during database setup. If you add a new book, it is created by gMSA account.

Conclusion

In this blog post, I showed you how to deploy Windows tasks with gMSA credential spec to an ECS cluster. I also explained how ECS Windows instances in Auto Scaling groups can be automatically joined to an Active Directory domain upon launch.

If you have comments about this blog post, submit them in the “Comments” section below. If you have questions, please start a new forum thread on the EC2 forum.