Using gMSA for EC2 Linux containers on Amazon ECS

Decide if you want to join the instances to the domain, or use domainless gMSA.

• Join EC2 instances to the Active Directory domain

  • Join the instances by user data

    Add the steps to join the Active Directory domain to your EC2 user data in an EC2 launch template. Multiple Amazon EC2 Auto Scaling groups can use the same launch template.

    You can use these steps Joining an Active Directory or FreeIPA domain in the Fedora Docs.

• Make an Active Directory user for domainless gMSA

  The credentials-fetcher daemon has a feature that's called domainless gMSA. This feature requires a domain, but the EC2 instance doesn't need to be joined to the domain. By using domainless gMSA, the container instance isn't joined to the domain, other applications on the instance can't use the credentials to access the domain, and tasks that join different domains can run on the same instance. Instead, you provide the name of a secret in AWS Secrets Manager in the CredSpec file. The secret must contain a username, password, and the domain to log in to.

  This feature is supported and can be used with Linux and Windows containers.

  This feature is similar to the gMSA support for non-domain-joined container hosts feature. For more information about the Windows feature, see gMSA architecture and improvements on the Microsoft Learn website.

  1. Make a user in your Active Directory domain. The user in Active Directory must have permission to access the gMSA service accounts that you use in the tasks.

  2. Create a secret in AWS Secrets Manager, after you made the user in Active Directory. For more information, see Create an AWS Secrets Manager secret.

  3. Enter the user's username, password, and the domain into JSON key-value pairs called username, password and domainName, respectively.

     {"username":"username","password":"passw0rd", "domainName":"example.com"}

  4. Add configuration to the CredSpec file for the service account. The additional HostAccountConfig contains the Amazon Resource Name (ARN) of the secret in Secrets Manager.

     On Windows, the PluginGUID must match the GUID in the following example snippet. On Linux, the PluginGUID is ignored. Replace MySecret with example with the Amazon Resource Name (ARN) of your secret.

         "ActiveDirectoryConfig": {
             "HostAccountConfig": {
                 "PortableCcgVersion": "1",
                 "PluginGUID": "{859E1386-BDB4-49E8-85C7-3070B13920E1}",
                 "PluginInput": {
                     "CredentialArn": "arn:aws:secretsmanager:aws-region:111122223333:secret:MySecret"
                 }
             }

  5. The domainless gMSA feature needs additional permissions in the task execution role. Follow the step (Optional) domainless gMSA secret.

Configure instances and install credentials-fetcher daemon

You can install the credentials-fetcher daemon with a user data script in your EC2 Launch Template. The following examples demonstrate two types of user data, cloud-config YAML or bash script. These examples are for Amazon Linux 2023 (AL2023). Replace MyCluster with the name of the Amazon ECS cluster that you want these instances to join.

• cloud-config YAML

  Content-Type: text/cloud-config
  package_reboot_if_required: true
  packages:
    # prerequisites
    - dotnet
    - realmd
    - oddjob
    - oddjob-mkhomedir
    - sssd
    - adcli
    - krb5-workstation
    - samba-common-tools
    # https://github.com/aws/credentials-fetcher gMSA credentials management for containers
    - credentials-fetcher
  write_files:
  # configure the ECS Agent to join your cluster.
  # replace MyCluster with the name of your cluster.
  - path: /etc/ecs/ecs.config
    owner: root:root
    permissions: '0644'
    content: |
      ECS_CLUSTER=MyCluster
      ECS_GMSA_SUPPORTED=true
  runcmd:
  # start the credentials-fetcher daemon and if it succeeded, make it start after every reboot
  - "systemctl start credentials-fetcher"
  - "systemctl is-active credentials-fetcher && systemctl enable credentials-fetcher"

• bash script

  If you're more comfortable with bash scripts and have multiple variables to write to /etc/ecs/ecs.config, use the following heredoc format. This format writes everything between the lines beginning with cat and EOF to the configuration file.

  
  #!/usr/bin/env bash
  set -euxo pipefail
  
  # prerequisites
  timeout 30 dnf install -y dotnet realmd oddjob oddjob-mkhomedir sssd adcli krb5-workstation samba-common-tools
  # install https://github.com/aws/credentials-fetcher gMSA credentials management for containers
  timeout 30 dnf install -y credentials-fetcher
  
  # start credentials-fetcher
  systemctl start credentials-fetcher
  systemctl is-active credentials-fetcher && systemctl enable credentials-fetcher
  
  cat <<'EOF' >> /etc/ecs/ecs.config
  ECS_CLUSTER=MyCluster
  ECS_GMSA_SUPPORTED=true
  EOF

There are optional configuration variables for the credentials-fetcher daemon that you can set in /etc/ecs/ecs.config. We recommend that you set the variables in the user data in the YAML block or heredoc similar to the previous examples. Doing so prevents issues with partial configuration that can happen with editing a file multiple times. For more information about the ECS agent configuration, see Amazon ECS Container Agent on GitHub.

(Optional) domainless gMSA secret

If you use the domainless method where the instance isn't joined to the domain, follow this step.

You must add the following permissions as an inline policy to the task execution IAM role. Doing so gives the credentials-fetcher daemon access to the Secrets Manager secret. Replace the MySecret example with the Amazon Resource Name (ARN) of your secret in the Resource list.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue"
            ],
            "Resource": [
                "arn:aws:ssm:aws-region:111122223333:secret:MySecret"
            ]
        }
    ]
}

Decide if you're using SSM Parameter Store or S3 to store the CredSpec

Amazon ECS supports the following ways to reference the file path in the credentialSpecs field of the task definition.

If you join the instances to a single domain, use the prefix credentialspec: at the start of the ARN in the string. If you use domainless gMSA, then use credentialspecdomainless:.

For more information about the CredSpec, see Credential specification file.

• Amazon S3 Bucket

  Add the credential spec to an Amazon S3 bucket. Then, reference the Amazon Resource Name (ARN) of the Amazon S3 bucket in the credentialSpecs field of the task definition.

  {
      "family": "",
      "executionRoleArn": "",
      "containerDefinitions": [
          {
              "name": "",
              ...
              "credentialSpecs": [
                  "credentialspecdomainless:arn:aws:s3:::${BucketName}/${ObjectName}"
              ],
              ...
          }
      ],
      ...
  }

  To give your tasks access to the S3 bucket, add the following permissions as an inline policy to the Amazon ECS task execution IAM role.

  {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Sid": "VisualEditor",
              "Effect": "Allow",
              "Action": [
                  "s3:Get*",
                  "s3:List*"
              ],
              "Resource": [
                  "arn:aws:s3:::amzn-s3-demo-bucket",
                  "arn:aws:s3:::amzn-s3-demo-bucket/{object}"
              ]
          }
      ]
  }

• SSM Parameter Store parameter

  Add the credential spec to an SSM Parameter Store parameter. Then, reference the Amazon Resource Name (ARN) of the SSM Parameter Store parameter in the credentialSpecs field of the task definition.

  {
      "family": "",
      "executionRoleArn": "",
      "containerDefinitions": [
          {
              "name": "",
              ...
              "credentialSpecs": [
                  "credentialspecdomainless:arn:aws:ssm:aws-region:111122223333:parameter/parameter_name"
              ],
              ...
          }
      ],
      ...
  }

  To give your tasks access to the SSM Parameter Store parameter, add the following permissions as an inline policy to the Amazon ECS task execution IAM role.

  {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Effect": "Allow",
              "Action": [
                  "ssm:GetParameters"
              ],
              "Resource": [
                  "arn:aws:ssm:aws-region:111122223333:parameter/parameter_name"
              ]
          }
      ]
  }