Coloring your AWS accounts (at scale!) 🌈

Erlend Ekern — Mon, 27 Oct 2025 18:02:22 +0000

Back in August AWS announced a new feature that allows you to label your AWS accounts with a color that shows up when you're using the AWS Console. This is a tiny, but very welcome quality of life improvement that gives you a visual indicator of what type of account you're using (e.g., 🟩 for dev and 🟥 for prod) - reducing the chance of production accidents and giving each account a bit more pizzazz.

The feature came with API support on launch (yay!), but without CloudFormation and, somewhat surprisingly, any SDK support¹. So most people will probably end up manually configuring this through the AWS Console anyway (boo!)..

But where there's ~~a will~~ an endpoint there's a way. In this article I'll use the account coloring feature as a practical example to demonstrate different approaches to programmatic infrastructure provisioning across AWS accounts. Even if you're not interested in account colors, you might pick up a useful thing or two along the way.

Let's dive in!

The curl way

curl has for some time supported signing requests using AWS SigV4, so the most lo-fi, programmatic way to set the color for an account is something like this:

curl -X PUT \
  "https://uxc.us-east-1.api.aws/v1/account-color" \
  --aws-sigv4 "aws:amz:us-east-1:uxc" \
  --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
  -H "x-amz-security-token: $AWS_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"color":"green"}'

If you're using AWS Identity Center for managing access to your accounts, you can run the above command like this to spin up a subshell with credentials exposed through the expected environment variables:

( eval "$(aws --profile "<my-profile>" configure export-credentials --format "env")" \
    && curl -X PUT ...
;)

This works, but is not very IaC-y. Can we do better?

The CloudFormation way

Enter CloudFormation.

Since there's no CloudFormation support yet we'll need to create a Lambda-backed custom resource to fill in the gap. And since there's no SDK support either, we'll have to perform the request ourselves.

Luckily we can leverage a lower-level module in botocore to help sign our request.

For our custom resource we'll also be using the ServiceTimeout property introduced in 2024 to give us a saner developer experience, especially during development (goodbye 1-hour feedback loops - you won't be missed 🙃).

Bringing it all together, we get the following CloudFormation template:

AWSTemplateFormatVersion: "2010-09-09"
Description: Sets the color for an account in the AWS Console

Parameters:
  Color:
    Type: String
    Default: none
    AllowedValues:
      # From https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/PutAccountColor.html#put-account-color-response-elements
      - none
      - pink
      - purple
      - darkBlue
      - lightBlue
      - teal
      - green
      - yellow
      - orange
      - red
    Description: The color to apply for the account

Resources:
  Role:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: lambda.amazonaws.com
            Action: sts:AssumeRole
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
      Policies:
        - PolicyName: AllowPutAccountColor
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action: uxc:PutAccountColor
                Resource: "*"

  Function:
    Type: AWS::Lambda::Function
    Properties:
      Runtime: python3.13
      Handler: index.lambda_handler
      Role: !GetAtt Role.Arn
      Timeout: 10
      Code:
        ZipFile: |
          import json
          import logging
          import typing as t
          import urllib.request
          from dataclasses import asdict, dataclass, field

          from botocore.auth import SigV4Auth
          from botocore.awsrequest import AWSRequest
          from botocore.session import Session

          logger = logging.getLogger(__name__)
          logger.setLevel(logging.INFO)


          @dataclass
          class CfnResponse:
              PhysicalResourceId: str
              StackId: str
              RequestId: str
              LogicalResourceId: str
              Status: t.Literal["SUCCESS", "FAILED"]
              Reason: t.Optional[str] = ""
              Data: t.Optional[t.Dict] = field(default_factory=dict)


          def send_cfn_response(url: str, cfn_response: CfnResponse):
              """Send minimal CloudFormation custom-resource response (pure stdlib)."""
              payload = json.dumps(asdict(cfn_response)).encode("utf-8")
              req = urllib.request.Request(
                  url,
                  data=payload,
                  method="PUT",
                  headers={
                      "content-length": str(len(payload)),
                  },
              )

              with urllib.request.urlopen(req) as f:
                  f.read()


          def put_account_color(color: str):
              """Update the color of the current account"""
              service = "uxc"
              # There's currently only an endpoint for us-east-1
              region = "us-east-1"
              url = f"https://{service}.{region}.api.aws/v1/account-color"
              payload = json.dumps({"color": color}).encode("utf-8")

              # There's currently no SDK support for this endpoint, so we create and sign the request ourselves
              credentials = Session().get_credentials().get_frozen_credentials()

              aws_request = AWSRequest(
                  method="PUT",
                  url=url,
                  data=payload,
                  headers={"Content-Type": "application/json"},
              )

              SigV4Auth(credentials, service, region).add_auth(aws_request)

              req = urllib.request.Request(
                  url=url, method="PUT", headers=dict(aws_request.headers), data=payload
              )

              with urllib.request.urlopen(req) as res:
                  status_code = res.status
                  res_body = res.read().decode("utf-8")

              return status_code, res_body


          def lambda_handler(event, context):
              logger.info("Triggered with event: %s", json.dumps(event, indent=2))
              color = event.get("ResourceProperties", {}).get("Color", "none")

              cfn_response_url = event["ResponseURL"]
              cfn_response = CfnResponse(
                  Status="SUCCESS",
                  PhysicalResourceId="AccountColor",
                  StackId=event["StackId"],
                  RequestId=event["RequestId"],
                  LogicalResourceId=event["LogicalResourceId"],
              )

              try:
                  if event["RequestType"] in ["Create", "Update"]:
                      status_code, res_body = put_account_color(color)
                      if status_code not in (200, 204):
                          cfn_response.Status = "FAILED"
                          cfn_response.Reason = (
                              f"Request failed with status {status_code}: {res_body}"
                          )
                  send_cfn_response(cfn_response_url, cfn_response)
              except Exception as e:
                  logger.exception("An unexpected error occurred")
                  cfn_response.Status = "FAILED"
                  cfn_response.Reason = f"See logs for more details '{context.log_group_name}/{context.log_stream_name}':\n{str(e)}"
                  send_cfn_response(
                      cfn_response_url,
                      cfn_response,
                  )

  LogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Sub /aws/lambda/${Function}
      RetentionInDays: 7

  AccountColor:
    Type: Custom::AccountColor
    DependsOn:
      - LogGroup
    DeletionPolicy: Retain
    UpdateReplacePolicy: Retain
    Properties:
      ServiceTimeout: 10
      ServiceToken: !GetAtt Function.Arn
      Color: !Ref Color

Let's store this template in cfn-templates/account-color.yml.

Cool. Now we have a template we can easily deploy using the AWS CLI to set the color for an account:

aws cloudformation deploy \
  --stack-name "example-cli-account-color" \
  --template-file "cfn-templates/account-color.yml" \
  --capabilities "CAPABILITY_IAM" \
  --parameter-overrides "Color=green"

This works well for one account, but what about a handful? And what if we want to use a different color for each account?

The shell-scripted CloudFormation way

Let's bring in the lingua franca of the cloud: Bash.

If we have a naming convention for our AWS CLI profiles, we could do something like this to provision our template across accounts:

#!/usr/bin/env bash
set -euo pipefail

main() {
  local color profile
  # Loop over a set of AWS CLI profiles
  for profile in "foo-dev" "bar-staging" "baz-prod"; do
    # Determine the color based on the suffix of the profile
    case "$profile" in
      *-dev)     color="green" ;;
      *-staging) color="orange" ;;
      *-prod)    color="red" ;;
      *)         color="none" ;;
    esac

    aws cloudformation deploy \
      --profile "$profile" \
      --stack-name "example-cli-account-color" \
      --template-file "cfn-templates/account-color.yml" \
      --capabilities "CAPABILITY_IAM" \
      --parameter-overrides "Color=$color" \
  done
}

main "$@"

This is decent, but still not ideal. How do we manage permissions to all of these accounts? Where do we run this? How do we handle parallelism and errors?

If only there was an AWS-native mechanism for managing infrastructure across accounts at scale..

✨ The CloudFormation StackSets way ✨

I've written about CloudFormation StackSets before, and I think it's a useful and powerful tool, especially for managing baseline infrastructure across accounts and regions. As I mentioned in that post:

If you need to deploy across AWS organizations, want to have granular control over which accounts are deployed to, or you think you’ll need account-specific parameter values in your stacks, you probably want to go with the self-managed model!

Since colors are more likely to be specific per account, not per Organizational Unit (OU), the self-managed permission model is probably the way to go here because it allows us to set different values of the Color parameter per account ².

The main drawback of the self-managed permission model is - as the name implies - that you need to manage the permissions. This includes setting up an IAM role (the "administration role") in the StackSet administration account, and an IAM role (the "execution role") in each target account that you want StackSets to deploy to.

Getting started

Below is an example of how to provision our CloudFormation template and set the color for an account using CloudFormation StackSets. Here we're using Terraform to manage the stack set itself, but it should be fairly straight-forward to adapt this to your IaC tool of choice.

To make it easy to try out yourself, everything is isolated to one AWS account - we use the current account as both the stack set administrator and the target account. While you normally wouldn't use StackSets like this (instead you'd just create the CloudFormation stack directly), it demonstrates the important bits and allows you to test in a non-critical account.

⚠️ Note: We will be attaching the AdministratorAccess managed policy to the execution role in the following examples. While you could attempt to scope this down to only the specific permissions needed, doing so for a service like CloudFormation StackSets can be impractical - overly restrictive permissions can lead to deployment failures and debugging headaches. But at the very least, consider the implications of this before production use.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6"
    }
  }
  required_version = ">= 1.0"
}

provider "aws" {
  region = "eu-west-1"
}

data "aws_caller_identity" "this" {}

locals {
  name_prefix                  = "example-tf"
  stackset_execution_role_name = "${local.name_prefix}-cfn-stackset-execution"
  current_account_id           = data.aws_caller_identity.this.account_id
}

# The admin role is used by CloudFormation StackSets to assume execution roles
# in target accounts.
resource "aws_iam_role" "stackset_admin" {
  name = "${local.name_prefix}-cfn-stackset-admin"
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Action = "sts:AssumeRole"
        Effect = "Allow"
        Principal = {
          Service = "cloudformation.amazonaws.com"
        }
      }
    ]
  })
}

resource "aws_iam_role_policy" "assume_to_stackset_admin" {
  role = aws_iam_role.stackset_admin.name
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = "sts:AssumeRole"
        Resource = "arn:aws:iam::*:role/${local.stackset_execution_role_name}"
      }
    ]
  })
}

# The execution role is used by CloudFormation StackSets to create stack instances
# (i.e. CloudFormation stacks) in target accounts.
resource "aws_iam_role" "stackset_execution" {
  name = local.stackset_execution_role_name
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Principal = {
          AWS = ["arn:aws:iam::${local.current_account_id}:root"]
        }
        Effect = "Allow"
        Action = "sts:AssumeRole"
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "stackset_execution" {
  role       = aws_iam_role.stackset_execution.name
  policy_arn = "arn:aws:iam::aws:policy/AdministratorAccess"
}

locals {
  accounts = [
    {
      id          = local.current_account_id
      environment = "development"
    },
    # NOTE: Add more accounts here
  ]
  environment_colors = {
    development = "green"
    staging     = "orange"
    production  = "red"
  }
}

resource "aws_cloudformation_stack_set" "account_color" {
  name                    = "${local.name_prefix}-account-color"
  permission_model        = "SELF_MANAGED"
  administration_role_arn = aws_iam_role.stackset_admin.arn
  execution_role_name     = aws_iam_role.stackset_execution.name
  template_body           = file("${path.root}/cfn-templates/account-color.yml")
  capabilities            = ["CAPABILITY_IAM"]
  depends_on = [
    aws_iam_role_policy.assume_to_stackset_admin,
    aws_iam_role_policy_attachment.stackset_execution
  ]
}

resource "aws_cloudformation_stack_set_instance" "account_color" {
  for_each                  = { for account in local.accounts : account.id => account }
  stack_set_name            = aws_cloudformation_stack_set.account_color.name
  account_id                = each.key
  stack_set_instance_region = "eu-west-1"
  parameter_overrides = {
    "Color" = lookup(local.environment_colors, each.value.environment, "none")
  }
}

Store this in a file main.tf alongside your cfn-templates directory, authenticate to AWS in an experimental account, and run terraform init and terraform apply.

Scaling up

For provisioning across accounts we can adapt the example from my previous blog post that shows us how to create a service-managed stack set that auto-deploys an IAM role to all accounts in an organization. We can leverage this pattern to easily and automatically create an execution role in all target accounts.

Our final code snippet will create two stack sets:

A service-managed stack set that deploys an execution role to all accounts in a target OU.
A self-managed stack set that deploys our CloudFormation template for account coloring to a set predefined accounts.

Note that in order to use service-managed stack sets you need to:

Use AWS Organizations.
Enable trusted access for StackSets in the organization.
Create the stack set through the management account or through a delegated administrator.

The resulting Terraform code can look something like this:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6"
    }
  }
  required_version = ">= 1.0"
}

provider "aws" {
  region = "eu-west-1"
}

data "aws_caller_identity" "this" {}
data "aws_organizations_organization" "this" {}

locals {
  name_prefix                  = "example-tf"
  stackset_execution_role_name = "${local.name_prefix}-cfn-stackset-execution"
  current_account_id           = data.aws_caller_identity.this.account_id
  stack_set_admin_account_id   = local.current_account_id
  management_account_id        = data.aws_organizations_organization.this.master_account_id
  call_as                      = local.current_account_id == local.management_account_id ? "SELF" : "DELEGATED_ADMIN"
  target_ou_id                 = "" # TODO: Add a non-critical OU here for initial testing
}

# A service-managed stack set that creates the required execution role
# for using self-managed stack sets
resource "aws_cloudformation_stack_set" "execution_role" {
  name             = "${local.name_prefix}-execution-role"
  permission_model = "SERVICE_MANAGED"
  capabilities     = ["CAPABILITY_NAMED_IAM"]
  call_as          = local.call_as
  auto_deployment {
    enabled = true
  }
  parameters = {
    TrustedAccountId = local.stack_set_admin_account_id
    RoleName         = local.stackset_execution_role_name
  }
  template_body = <<-EOF
  AWSTemplateFormatVersion: "2010-09-09"

  Parameters:
    TrustedAccountId:
      Type: String
    RoleName:
      Type: String

  Resources:
    Role:
      Type: AWS::IAM::Role
      Properties:
        RoleName: !Ref RoleName
        AssumeRolePolicyDocument:
          Version: "2012-10-17"
          Statement:
            - Effect: Allow
              Principal:
                AWS: !Sub "arn:aws:iam::$${TrustedAccountId}:root"
              Action: sts:AssumeRole
        ManagedPolicyArns:
          - arn:aws:iam::aws:policy/AdministratorAccess
  EOF
}

resource "aws_cloudformation_stack_set_instance" "execution_role" {
  stack_set_name            = aws_cloudformation_stack_set.execution_role.name
  call_as                   = local.call_as
  stack_set_instance_region = "eu-west-1"
  deployment_targets {
    organizational_unit_ids = [local.target_ou_id]
  }
}

# The admin role is used by CloudFormation StackSets to assume execution roles
# in target accounts when using self-managed stack sets.
resource "aws_iam_role" "stackset_admin" {
  name = "${local.name_prefix}-cfn-stackset-admin"
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Action = "sts:AssumeRole"
        Effect = "Allow"
        Principal = {
          Service = "cloudformation.amazonaws.com"
        }
      }
    ]
  })
}

resource "aws_iam_role_policy" "assume_to_stackset_admin" {
  role = aws_iam_role.stackset_admin.name
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = "sts:AssumeRole"
        Resource = "arn:aws:iam::*:role/${local.stackset_execution_role_name}"
      }
    ]
  })
}

locals {
  accounts = [
    {
      id          = "" # TODO: Add the ID of an account in the target OU here
      environment = "development"
    },
  ]
  environment_colors = {
    development = "green"
    staging     = "orange"
    production  = "red"
  }
}

resource "aws_cloudformation_stack_set" "account_color" {
  name                    = "${local.name_prefix}-account-color"
  permission_model        = "SELF_MANAGED"
  administration_role_arn = aws_iam_role.stackset_admin.arn
  execution_role_name     = local.stackset_execution_role_name
  template_body           = file("${path.root}/cfn-templates/account-color.yml")
  capabilities            = ["CAPABILITY_IAM"]
  depends_on = [
    aws_iam_role_policy.assume_to_stackset_admin,
    aws_cloudformation_stack_set_instance.execution_role,
  ]
}

resource "aws_cloudformation_stack_set_instance" "account_color" {
  for_each                  = { for account in local.accounts : account.id => account }
  stack_set_name            = aws_cloudformation_stack_set.account_color.name
  account_id                = each.key
  stack_set_instance_region = "eu-west-1"
  parameter_overrides = {
    "Color" = lookup(local.environment_colors, each.value.environment, "none")
  }
}

You can try it out by storing the snippet above in a file main.tf, fixing the TODOs, running it against a non-critical OU, and verifying that the Terraform plan looks good.

Enjoy the colors 🌈

Summary

There you have it, folks. Colored AWS accounts. We're truly living in the future.

While I do expect that we'll get both SDK and CloudFormation support in the near-ish future (and if we're lucky the possibility to configure this centrally from the management account), you can still get started with the CloudFormation approach laid out here. Once something better and more native shows up, you should be able to delete the custom resource and associated resources without issues and replace it with a new mechanism - the custom resource is configured to be a no-op on deletion.

Note that managed policies typically used for read access (e.g., ViewOnlyAccess and ReadOnlyAccess) do not yet include permissions to fetch the color of an account. If you're using these and want your developers to experience the cloud in all its colorful glory, consider adding uxc:GetAccountColor to the relevant IAM roles.

What we've done here might seem a teeny-tiny tad overkill for this specific use case, but the overall approach and the patterns described can be applied when provisioning any baseline infrastructure across accounts.

Update (31 Oct '25 🎃):
Anders Bjørnestad was kind to point out that customers using Control Tower might have issues with account coloring as it currently only has an endpoint in us-east-1.

If us-east-1 isn't a governed region in Control Tower and you have enabled region deny controls (i.e., GRREGIONDENY or CTMULTISERVICEPV1), by default you won't be able to get or set an account color as it's not part of the default whitelist.. Unless colors are EXTREMELY IMPORTANT to you, your best course of action is likely to wait until the Control Tower service team fixes this on their end to avoid having to get your hands dirty with Control Tower, SCPs and the associated blast radius.

But not one to shy away from a practical lesson, here's how you probably could wrestle Control Tower to give you colors if you so desired:

If using CTMULTISERVICEPV1, you should be able to add uxc:* to the whitelist using the built-in exemptions feature for this control.
If using GRRREGIONDENY you could add us-east-1 as a governed region, and introduce a custom SCP that denies unwanted actions there - perhaps just an extension of the default SCP that includes uxc:*. Note that this is fair amount of work and comes with quite the blast radius.

But again, for this specific feature, you should probably just wait for official support in Control Tower to avoid any production incidents that can be tricky to explain to the management..

"[It] is something that would need to be implemented by the service team" ↩
If you really wanted to use a service-managed stack set instead of a self-managed one you could do so by updating the custom resource to determine the color (e.g., by looking up account name or alias, and introducing some rules for mapping to colors). Generally speaking I favor more explicit behavior than this though. ↩

DEV Community: Erlend Ekern