Using Amazon ECS Windows containers with domainless gMSA using the Amazon CLI

Generate a Key Distribution Service root key

The KDS root key and gMSA permissions are configured with your Amazon managed Microsoft AD.

If you have not already created a gMSA Service Account in your domain, you’ll need to first generate a Key Distribution Service (KDS) root key. The KDS is responsible for creating, rotating, and releasing the gMSA password to authorized hosts. When the ccg.exe needs to retrieve gMSA credentials, it contact KDS to retrieve the current password.

To check if the KDS root key has already been created, run the following PowerShell cmdlet with domain admin privileges on a domain controller using the ActiveDirectory PowerShell module. For more information about the module, see ActiveDirectory Module on the Microsoft Learn website.

PS C:\> Get-KdsRootKey

If the command returns a key ID, you can skip the rest of this step. Otherwise, create the KDS root key by running the following command:

PS C:\> Add-KdsRootKey -EffectiveImmediately

Although the argument EffectiveImmediately to the command implies the key is effective immediately, you need to wait 10 hours before the KDS root key is replicated and available for use on all domain controllers.

Create the gMSA account

To create the gMSA account and allow the ccg.exe to retrieve the gMSA password, run the following PowerShell commands from a Windows Server or client with access to the domain. Replace ExampleAccount with the name that you want for your gMSA account.

1. PS C:\> Install-WindowsFeature RSAT-AD-PowerShell

2. PS C:\> New-ADGroup -Name "ExampleAccount Authorized Hosts" -SamAccountName "ExampleAccountHosts" -GroupScope DomainLocal

3. PS C:\> New-ADServiceAccount -Name "ExampleAccount" -DnsHostName "contoso" -ServicePrincipalNames "host/ExampleAccount", "host/contoso" -PrincipalsAllowedToRetrieveManagedPassword "ExampleAccountHosts"

4. Create a user with a permanent password that doesn't expire. These credentials are stored in Amazon Secrets Manager and used by each task to join the domain.

   PS C:\> New-ADUser -Name "ExampleAccount" -AccountPassword (ConvertTo-SecureString -AsPlainText "Test123" -Force) -Enabled 1 -PasswordNeverExpires 1

5. PS C:\> Add-ADGroupMember -Identity "ExampleAccountHosts" -Members "ExampleAccount"

6. Install the PowerShell module for creating CredSpec objects in Active Directory and output the CredSpec JSON.

   PS C:\> Install-PackageProvider -Name NuGet -Force

   PS C:\> Install-Module CredentialSpec

7. PS C:\> New-CredentialSpec -AccountName ExampleAccount

Copy the JSON output from the previous command into a file called gmsa-cred-spec.json. This is the CredSpec file. It is used in Step 3, Step 3: Modify your CredSpec JSON to include domainless gMSA information.

Add the following information to the CredSpec file inside the ActiveDirectoryConfig. Replace the ARN with the secret in Secrets Manager from the previous step.

Note that the PluginGUID value must match the GUID in the following example snippet and is required.

"HostAccountConfig": {
      "PortableCcgVersion": "1",
      "PluginGUID": "{859E1386-BDB4-49E8-85C7-3070B13920E1}",
      "PluginInput": "{\"credentialArn\": \"arn:aws:secretsmanager:aws-region:111122223333:secret:gmsa-plugin-input\"}"
    }

You can also use a secret in SSM Parameter Store by using the ARN in this format: \"arn:aws:ssm:aws-region:111122223333:parameter/gmsa-plugin-input\".

After you modify the CredSpec file, it should look like the following example:

{
  "CmsPlugins": [
    "ActiveDirectory"
  ],
  "DomainJoinConfig": {
    "Sid": "S-1-5-21-4066351383-705263209-1606769140",
    "MachineAccountName": "ExampleAccount",
    "Guid": "ac822f13-583e-49f7-aa7b-284f9a8c97b6",
    "DnsTreeName": "contoso",
    "DnsName": "contoso",
    "NetBiosName": "contoso"
  },
  "ActiveDirectoryConfig": {
    "GroupManagedServiceAccounts": [
      {
        "Name": "ExampleAccount",
        "Scope": "contoso"
      },
      {
        "Name": "ExampleAccount",
        "Scope": "contoso"
      }
    ],
    "HostAccountConfig": {
      "PortableCcgVersion": "1",
      "PluginGUID": "{859E1386-BDB4-49E8-85C7-3070B13920E1}",
      "PluginInput": "{\"credentialArn\": \"arn:aws:secretsmanager:aws-region:111122223333:secret:gmsa-plugin-input\"}"
    }
  }
}

Copy the CredSpec file to the computer or environment that you are running Amazon CLI commands in.

Run the following Amazon CLI command to upload the CredSpec to Amazon S3. Replace MyBucket with the name of your Amazon S3 bucket. You can store the file as an object in any bucket and location, but you must allow access to that bucket and location in the policy that you attach to the task execution role.

The following command uses backslash continuation characters that are used by sh and compatible shells. This command isn't compatible with PowerShell. You must modify the command to use it with PowerShell.

$ aws s3 cp gmsa-cred-spec.json \
s3://MyBucket/ecs-domainless-gmsa-credspec

To create a task execution role, see Creating the task execution role. The default permissions allow the container instance to pull container images from Amazon Elastic Container Registry and stdout and stderr from your applications to be logged to Amazon CloudWatch Logs.

Because the role needs custom permissions for this tutorial, you can give the role a different name than ecsTaskExecutionRole. This tutorial uses ecsTaskExecutionRole in further steps.

Add the following permissions by creating a custom policy, either an inline policy that only exists in for this role, or a policy that you can reuse. Replace the ARN for the Resource in the first statement with the Amazon S3 bucket and location, and the second Resource with the ARN of the secret in Secrets Manager.

If you encrypt the secret in Secrets Manager with a custom key, you must also allow kms:Decrypt for the key.

If you use SSM Parameter Store instead of Secrets Manager, you must allow ssm:GetParameter for the parameter, instead of secretsmanager:GetSecretValue.

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": "arn:aws:s3:::MyBucket/ecs-domainless-gmsa-credspec/gmsa-cred-spec.json"
    },
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue"
      ],
      "Resource": "arn:aws:secretsmanager:aws-region:111122223333:secret:gmsa-plugin-input"
    }
  ]
}

Create a file called ecs-tasks-trust-policy.json with the following contents:

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

Create an IAM role. You can replace the name ecs-exec-demo-task-role but keep the name for following steps.

The following command uses backslash continuation characters that are used by sh and compatible shells. This command isn't compatible with PowerShell. You must modify the command to use it with PowerShell.

$ aws iam create-role --role-name ecs-exec-demo-task-role \
--assume-role-policy-document file://ecs-tasks-trust-policy.json

You can delete the file ecs-tasks-trust-policy.json.

Create a file called ecs-exec-demo-task-role-policy.json with the following contents:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ssmmessages:CreateControlChannel",
                "ssmmessages:CreateDataChannel",
                "ssmmessages:OpenControlChannel",
                "ssmmessages:OpenDataChannel"
            ],
            "Resource": "*"
        }
    ]
}

Create an IAM policy and attach it to the role from the previous step.

The following command uses backslash continuation characters that are used by sh and compatible shells. This command isn't compatible with PowerShell. You must modify the command to use it with PowerShell.

$ aws iam put-role-policy \
    --role-name ecs-exec-demo-task-role \
    --policy-name ecs-exec-demo-task-role-policy \
    --policy-document file://ecs-exec-demo-task-role-policy.json

You can delete the file ecs-exec-demo-task-role-policy.json.

Create a file called windows-gmsa-domainless-task-def.json with the following contents:

{
  "family": "windows-gmsa-domainless-task",
  "containerDefinitions": [
    {
      "name": "windows_sample_app",
      "image": "mcr.microsoft.com/windows/servercore/iis",
      "cpu": 1024,
      "memory": 1024,
      "essential": true,
      "credentialSpecs": [
                "credentialspecdomainless:arn:aws:s3:::ecs-domainless-gmsa-credspec/gmsa-cred-spec.json"
      ],
      "entryPoint": [
        "powershell",
        "-Command"
      ],
      "command": [
        "New-Item -Path C:\\inetpub\\wwwroot\\index.html -ItemType file -Value '<html> <head> <title>Amazon ECS Sample App</title> <style>body {margin-top: 40px; background-color: #333;} </style> </head><body> <div style=color:white;text-align:center> <h1>Amazon ECS Sample App</h1> <h2>Congratulations!</h2> <p>Your application is now running on a container in Amazon ECS.</p>' -Force ; C:\\ServiceMonitor.exe w3svc"
      ],
      "portMappings": [
        {
          "protocol": "tcp",
          "containerPort": 80,
          "hostPort": 8080
        }
      ]
    }
  ],
  "taskRoleArn": "arn:aws:iam::111122223333:role/ecs-exec-demo-task-role",
  "executionRoleArn": "arn:aws:iam::111122223333:role/ecsTaskExecutionRole"
}

Register the task definition by running the following command:

The following command uses backslash continuation characters that are used by sh and compatible shells. This command isn't compatible with PowerShell. You must modify the command to use it with PowerShell.

$ aws ecs register-task-definition \
--cli-input-json file://windows-gmsa-domainless-task-def.json

To launch an Amazon EC2 Windows instance that is configured for Amazon ECS in the Amazon Web Services Management Console, see Launching an Amazon ECS Windows container instance. Stop at the step for user data.

For gMSA, the user data must set the environment variable ECS_GMSA_SUPPORTED before starting the ECS container agent.

For ECS Exec, the agent must start with the argument -EnableTaskIAMRole.

To secure the instance IAM role by preventing tasks from reaching the EC2 IMDS web service to retrieve the role credentials, add the argument -AwsvpcBlockIMDS. This only applies to tasks that use the awsvpc network mode.

<powershell>
[Environment]::SetEnvironmentVariable("ECS_GMSA_SUPPORTED", $TRUE, "Machine")
Import-Module ECSTools
Initialize-ECSAgent -Cluster windows-domainless-gmsa-cluster -EnableTaskIAMRole -AwsvpcBlockIMDS
</powershell>
    

Review a summary of your instance configuration in the Summary panel, and when you're ready, choose Launch instance.

List the container instances in the cluster. Container instances have an ID that is different from the ID of the EC2 instance.

$ aws ecs list-container-instances

Output:

{
    "containerInstanceArns": [
        "arn:aws:ecs:aws-region:111122223333:container-instance/default/MyContainerInstanceID"
    ]
}

For example, 526bd5d0ced448a788768334e79010fd is a valid container instance ID.

Use the container instance ID from the previous step to get the details for the container instance. Replace MyContainerInstanceID with the ID.

The following command uses backslash continuation characters that are used by sh and compatible shells. This command isn't compatible with PowerShell. You must modify the command to use it with PowerShell.

$ aws ecs describe-container-instances \
     ----container-instances MyContainerInstanceID

Note that the output is very long.

Verify that the attributes list has an object with the key called name and a value ecs.capability.gmsa-domainless. The following is an example of the object.

Output:

{
    "name": "ecs.capability.gmsa-domainless"
}

The following command uses backslash continuation characters that are used by sh and compatible shells. This command isn't compatible with PowerShell. You must modify the command to use it with PowerShell.

aws ecs run-task --task-definition windows-gmsa-domainless-task \
    --enable-execute-command --cluster windows-domainless-gmsa-cluster

Note the task ID that is returned by the command.

Run the following command to verify that the task has started. This command waits and doesn't return the shell prompt until the task starts. Replace MyTaskID with the task ID from the previous step.

$ aws ecs wait tasks-running --task MyTaskID

The following command uses backslash continuation characters that are used by sh and compatible shells. This command isn't compatible with PowerShell. You must modify the command to use it with PowerShell.

$ aws ecs execute-command \
--task MyTaskID \
--container windows_sample_app \
--interactive \
--command powershell.exe

The output will be a PowerShell prompt.

Run the following command in the PowerShell terminal inside the container.

PS C:\> klist get ExampleAccount$

In the output, note the Principal is the one that you created previously.

Stop the task. Replace MyTaskID with the task ID from step 12, Step 12: Run a Windows task.

$ aws ecs stop-task --task MyTaskID

Terminate the Amazon EC2 instance. Afterwards, the container instance in the cluster will be deleted automatically after one hour.

You can find and terminate the instance by using the Amazon EC2 console. Or, you can run the following command. To run the command, find the EC2 instance ID in the output of the aws ecs describe-container-instances command from step 1, Step 11: Verify the container instance. i-10a64379 is an example of an EC2 instance ID.

$ aws ec2 terminate-instances --instance-ids MyInstanceID

Delete the CredSpec file in Amazon S3. Replace MyBucket with the name of your Amazon S3 bucket.

$ aws s3api delete-object --bucket MyBucket --key ecs-domainless-gmsa-credspec/gmsa-cred-spec.json

Delete the secret from Secrets Manager. If you used SSM Parameter Store instead, delete the parameter.

The following command uses backslash continuation characters that are used by sh and compatible shells. This command isn't compatible with PowerShell. You must modify the command to use it with PowerShell.

$ aws secretsmanager delete-secret --secret-id gmsa-plugin-input \
     --force-delete-without-recovery

Deregister and delete the task definition. By deregistering the task definition, you mark it as inactive so it can't be used to start new tasks. Then, you can delete the task definition.

1. Deregister the task definition by specifying the version. ECS automatically makes versions of task definitions, that are numbered starting from 1. You refer to the versions in the same format as the labels on container images, such as :1.

   $ aws ecs deregister-task-definition --task-definition windows-gmsa-domainless-task:1

2. Delete the task definition.

   $ aws ecs delete-task-definitions --task-definition windows-gmsa-domainless-task:1

(Optional) Delete the ECS cluster, if you created a cluster.

$ aws ecs delete-cluster --cluster windows-domainless-gmsa-cluster