Customization guide for the AWS Well Architected Mod: Part 1

The v0.8 release of the AWS Well-Architected mod includes support for three of the six pillars of the AWS Well-Architected Framework: Operational Excellence, Reliability and Security. In this post we'll show how you can extend the Well-Architected mod with a benchmark that helps you assess your infrastructure for enviromental impacts targeted by the Sustainability pillar.

The AWS Well-Architected mod is an example of how to reuse and remix existing benchmarks and dashboards: it cherrypicks controls from AWS Compliance which provides more than 780 controls. The Sustainability benchmark we'll add here will, similarly, reuse controls from AWS Thrifty which provides 46 controls. Other sources include AWS Perimeter (52 controls) and AWS Tags (350 controls).

Fork and clone the AWS Well-Architected mod

To get started, create a fork of the mod in your GitHub account. Then clone it.

git clone https://github.com/judell/steampipe-mod-aws-well-architected
cd steampipe-mod-aws-well-architected

If you do nothing else at this point, running steampipe dashboard will display both AWS Compliance and AWS Well-Architected just as happens when you use the AWS Well-Architected mod directly.

Define a new second-level benchmark for the Sustainability pillar

The existing pillars live in subdirectories of well-architected-framework. Create a new subdirectory there, called sustainability.

There we'll create a new file, sustainability.sp:

locals {
  well_architected_framework_sustainability_common_tags = merge(local.well_architected_framework_common_tags, {
    pillar_id = "sustainability"
  })
}

benchmark "well_architected_framework_sustainability" {
  title       = "sustainability"
  description = "The Sustainability pillar addresses the long-term environmental, economic, and societal impact of your business activities."
  children = [
    // tbd
  ]

  tags = local.well_architected_framework_sustainability_common_tags
}

And refer to the new benchmark from the top-level well_architected_framework.sp:

benchmark "well_architected_framework" {
  title       = "AWS Well-Architected Framework"
  description = "The AWS Well-Architected Framework describes key concepts, design principles, and architectural best practices for designing and running workloads in the cloud. By answering a few foundational questions, learn how well your architecture aligns with cloud best practices and gain guidance for making improvements."
  documentation = file("./well_architected_framework/docs/well_architected_framework_overview.md")

  children = [
    benchmark.well_architected_framework_operational_excellence,
    benchmark.well_architected_framework_reliability,
    benchmark.well_architected_framework_security,
    benchmark.well_architected_framework_sustainability
  ]

  tags = local.well_architected_framework_common_tags
}

Define a third-level benchmark for a topic

The Sustainability pillar covers six topics. Here we'll focus on SUS02: Alignment to demand. Create a new file, sus02.sp:

locals {
  well_architected_framework_sus02_common_tags = merge(local.well_architected_framework_sustainability_common_tags, {
    question_id = "sus_user"
  })
}

benchmark "well_architected_framework_sus02" {
  title       = "SUS02 How do you align cloud resources to your demand?"
  description = "Scale infrastructure to continually match demand and verify that you use only the minimum resources required to support your users."
  children = [
  ]

  tags = local.well_architected_framework_sus02_common_tags
}

Define a child benchmark for a best practice

We'll start with SUS02-BP03 Stop the creation and maintenance of unused assets. The children of this benchmark will be controls that identify underutilized resources. The relevant controls aren't in the AWS Compliance mod we're already using. But the tagline for AWS Thrifty is: "Be Thrifty on AWS! This mod checks for unused resources and opportunities to optimize your spend on AWS." Can we cherrypick controls that target unused assets? Let's search for likely candidates.

We'll use ECS Clusters with Low Utilization for our example here. In order to cherrypick that control, we'll add Thrifty as another mod dependency. (If Thrifty were already a dependency, this step wouldn't be needed.)

steampipe mod install github.com/turbot/steampipe-mod-aws-thrifty

Installed 1 mod:

aws_well_architected
└── github.com/turbot/steampipe-mod-aws-thrifty@0.21.0

steampipe mod list

aws_well_architected
├── github.com/turbot/steampipe-mod-aws-compliance@v0.67.0
└── github.com/turbot/steampipe-mod-aws-thrifty@v0.21.0

On the hub page we discover the fully-qualified name of the control.

We'll add that as the first child of well_architected_framework_sus02.

benchmark "well_architected_framework_sus02" {
  title       = "SUS02 How do you align cloud resources to your demand?"
  description = "Scale infrastructure to continually match demand and verify that you use only the minimum resources required to support your users."
  children = [
    benchmark.well_architected_framework_sus02_bp03
  ]

  tags = local.well_architected_framework_sus02_common_tags
}

benchmark "well_architected_framework_sus02_bp03" {
  title       = "BP03 Stop the creation and maintenance of unused assets"
  description = "Decommission unused assets in your workload to reduce the number of cloud resources required to support your demand and minimize waste."
  children = [
    aws_thrifty.control.ecs_cluster_low_utilization,
  ]

  tags = merge(local.well_architected_framework_sus02_common_tags, {
    choice_id = "sus_sus_user_a4"
    severity = "low"
  })
}

And voilà! The new benchmark is up and running.

Aligning tags

If your goal is to use the AWS Well-Architected mod to gather answers that you'll post back to the AWS Well-Architected Tool, you'll want the values of these tags to align with nomenclature used by that tool. How to discover those values? Steampipe to the rescue! You can query aws_wellarchitected_answer, one of eight tables that we've added to the AWS plugin for support the AWS Well-Architected API.

To find question ids and titles:

select
  pillar_id,
  question_id,
  ltrim(question_title) as question_title
from
  aws_wellarchitected_answer
where
  workload_id = 'b560b72391f8ca6332186d6b61dfbfc2'
  and pillar_id = 'sustainability'

+----------------+--------------+------------------------------------------------------------------------------------------------------------------+
| pillar_id      | question_id  | question_title                                                                                                   |
+----------------+--------------+------------------------------------------------------------------------------------------------------------------+
| sustainability | sus_dev      | How do your organizational processes support your sustainability goals?                                          |
| sustainability | sus_region   | How do you select Regions for your workload?                                                                     |
| sustainability | sus_software | How do you take advantage of software and architecture patterns to support your sustainability goals?            |
| sustainability | sus_hardware | How do you select and use cloud hardware and services in your architecture to support your sustainability goals? |
| sustainability | sus_data     | How do you take advantage of data management policies and patterns to support your sustainability goals?         |
| sustainability | sus_user     | How do you align cloud resources to your demand?                                                                 |
+----------------+--------------+------------------------------------------------------------------------------------------------------------------+

To find choice ids and titles:

with info as (
  select
    question_id,
    jsonb_array_elements(choices) as choice
  from
    aws_wellarchitected_answer
  where
   workload_id = 'b560b72391f8ca6332186d6b61dfbfc2'
   and pillar_id = 'sustainability'
)
select
  question_id,
  choice ->> 'ChoiceId' as choice_id,
  choice ->> 'Title' as choice_title
from
  info
where
  question_id = 'sus_user'
order by
  question_id, choice_id

+-------------+-----------------+-----------------------------------------------------------------------------------+
| question_id | choice_id       | choice_title                                                                      |
+-------------+-----------------+-----------------------------------------------------------------------------------+
| sus_user    | sus_sus_user_a2 | Scale workload infrastructure dynamically                                         |
| sus_user    | sus_sus_user_a3 | Align SLAs with sustainability goals                                              |
| sus_user    | sus_sus_user_a4 | Stop the creation and maintenance of unused assets                                |
| sus_user    | sus_sus_user_a5 | Optimize geographic placement of workloads based on their networking requirements |
| sus_user    | sus_sus_user_a6 | Optimize team member resources for activities performed                           |
| sus_user    | sus_sus_user_a7 | Implement buffering or throttling to flatten the demand curve                     |
| sus_user    | sus_sus_user_no | None of these                                                                     |
+-------------+-----------------+-----------------------------------------------------------------------------------+

The leaf benchmarks also include a severity tag. We take these from the documentation, which was also our source for the sus02-bp03 in the control's name.

Note that tags added this way will not appear in console or dashboard output, as do common dimensons like account_id and region. They will, however, appear in CSV and JSON exports.

Next steps

You can, of course, use your fork of the Well-Architected mod privately. But we hope you'll want to contribute new mappings that improve the Well-Architected mod for everyone. For example, here's a pull request for the changes we've shown here. To build on it, you can look for other controls that mention "low utilization" or "unused assets" and add them as additional children.

Note that you're not limited to existing controls. You can write your own controls, driven by your own queries, and we'll explore that topic in part 2 of this series. Meanwhile, give this approach a try and let us know how it goes!