Well-Architected Compliance Report - Executive Summary

Extensive reporting of Well-Architected Maturity

Table of contents

Introduction

In the post How to measure Well-Architected maturity we explored how extensive insight into cloud infrastructure posture could help accelerate the Measure phase, leaving more time to Learn and discuss opportunities for Improvement.

AWS WAFR process
Figure – Well-Architected Framework review cycle courtesy of AWS

A key factor was to make the data available while performing a review in the Well-Architected Tool. After discussing the solution with colleagues and customers I realized that the valuable data points weren’t exposed to their full potential within only the Notes field in the Well-Architected Tool. Key constraints are that the Notes field is limited to plain text and a maximum of 2000 characters. Valuable resource identifiers and tags had to be capped, which made it harder to easily identify the applicable resources. Could there be a better way?

I decided to develop an additional AWS Lambda function called well_architected_report_generator. The main purpose of this Lambda function is to collect all the available data points from various sources and generate a report in HTML format stored in Amazon Simple Storage Service (S3). When performing Well-Architected Framework Reviews, you are most likely already logged in to the AWS Console to access the Well-Architected Tool, so opening an additional tab with S3 could be useful. Thanks to Amazon Q Developer the HTML and CSS came out pretty good, too!

Current data sources:

  • AWS Config Conformance Packs
  • AWS Trusted Advisor checks (available checks depends on active AWS Support Plan)
  • Resource Tag: Name

How to generate a Well-Architected Compliance report

Deploy the Terraform module as also described in How to measure Well-Architected Maturity.

    Please note that three new (optional) Terraform module variables have been introduced:

    variable "deploy_aws_config_recorder" {
      description = "Set to true to deploy an AWS Config Recorder. If you already have a customer managed AWS Config recorder in the desired region, set to false. AWS supports only one customer managed configuration recorder for each account for each AWS Region."
      type        = bool
      default     = true
    }
    
    variable "reports_bucket_name_prefix" {
      description = "Prefix for the S3 bucket name that stores Well-Architected compliance reports"
      type        = string
      default     = "well-architected-compliance-reports"
    }
    
    variable "reports_retention_days" {
      description = "Number of days to retain non-current versions of reports in the S3 bucket"
      type        = number
      default     = 90
    }

    At the time of writing AWS only supports one customer managed AWS Config recorder in each region. If you already have one, set this value to false, for re-use.

    If you would like to retain the reports for longer than the default value of 90 days you may set the desired value accordingly.

    A minimal example module call if you already have a customer managed AWS Config recorder in your region and you prefer to retain the report files for 400 days may look like this:

    module "well_architected_config_conformance_pack" {
      source = "git::https://github.com/soprasteria/terraform-aws-wellarchitected-conformance.git?ref=<DESIRED-COMMIT-SHA>"
      deploy_aws_config_recorder = false
      reports_retention_days = 400
    }

    Wait 24 hours for data to be collected and aggregated.

    Then, in the AWS Console, go to AWS Lambda and locate the function well_architected_report_generator.

    Create a new Test function with a JSON payload of workload_id for the Well-Architected Tool (not the complete ARN, just the last part) and dry_run. Example payload:

    {
      "workload_id": "141970ea95fd5b4329cyh05502659f39",
      "dry_run": 0
    }

    Hit Test. Execution may take a minute or two, depending on the amount of AWS infrastructure resources deployed in the AWS account.

    The Cloud Watch Logs output will let you know which AWS Support plan is detected and where you can find the produced report.
    Starting Well-Architected Report Generator
    Collecting compliance data from AWS Config
    Trusted Advisor compliance status mapping
    AWS Business or Enterprise Support is/is not enabled
    Successfully uploaded report to s3://well-architected-compliance-reports-123456789012/Reports/well_architected_compliance_report_%timestamp%.html

    Navigate to Amazon S3, find the most recent report by sorting on the Last modified column, check the box to the left of Name and click Open to access the report in a new browser tab.

      What a Well-Architected Framework Compliance report looks like

      The produced report contains information about the time of generation, the AWS Account ID, region and detected AWS Support plan.

      Example report 1, an AWS account with Basic Support:

      Example report 2, an AWS account with Enterprise Support:

      The report may contain a lot of detailed information, so an Executive Summary is provided as a high-level overview.

      Example report 1:

      Example report 2:

      Next a Table of Contents is provided which includes an overview of the available Well-Architected Framework pillars and questions.

      Each question includes relevant context information from the Well-Architected Framework and link to further guidance.

      Here is the second question in the Security pillar: “How do you manage identifies for people and machines?”

      For AWS Accounts with available AWS Premium Support, relevant Trusted Advisor check information is included.

      Relevant AWS Config checks and their status are displayed, along with the detected Resource Type, Resource ID and Tag Name, if available, for easy identification and discussion.

      For Reliability Pillar question number 9, Trusted Advisor checks indicates that RDS backups are enabled for all clusters, but there is at least one S3 bucket where replication is not configured.

      The next section lists all detected AWS resources, including Resource ID, Status and Tag Name, as available (certain information has been obfuscated on purpose).

      Moving to Cost Optimization pillar question number three: “How do you monitor cost and usage?” actually has no official Trusted Advisor checks associated, but the Terraform module fills the gap with custom AWS Config checks.

      Based on this we can easily see that:

      1. Cost Anomaly Detection is configured with a Cost monitor.
      2. There is at least one AWS Budget configured with alert subscriptions.
      3. There are no EC2 instances not in any Auto Scaling Groups.
      4. The AWS account is a member of AWS Organizations and a Tag Policy is in effect.

      How the reporting feature works

      Let’s take a closer look into the underlying logic of the well_architected_report_generator Lambda function.

      Diagram created by the help of AWS Diagram and Documentation MCP Servers

      After the Terraform module is deployed AWS Config needs 24 hours to collect and aggregate all data points. Then when the Lambda function is triggered, the following happens:

      1. The starting point is a Workload in the Well-Architected Tool. It’s not necessary to answer all questions first, you can do that with your team after the initial report has been generated. Every question in each pillar will then be mapped to relevant AWS Config and Trusted Advisor checks. Note: There is currently not a 100% 1-1 mapping with AWS Config and Trusted Advisor checks, but the availability may increase going forward as more custom checks are added to the Terraform module (contributions are welcome) and AWS Trusted Advisor.
      2. Compliance status and information for all mapped checks are collected and aggregated.
        Resources in scope are fetched along with Tag Name, as available.
        Contextual information and further guidance is retrieved.
      3. Scores and percentages are calculated.
      4. Data and information are grouped by pillar.
      5. The Executive Summary is generated.
      6. The report is produced based on Python Jinja2 templating functionality and uploaded to a dedicated bucket on Amazon S3.

      This functionality is part of the Terraform module in the file wa_report_generator.tf which includes the AWS Lambda function, a dedicated AWS KMS Key for encrypting the compliance reports (as resource and account information may be considered as sensitive) and a dedicated Amazon S3 bucket.

      Conclusion

      The solution now provides even more valuable insight to accelerate Well-Architected Framework Review conversations, providing more time to discuss opportunities for improvement. It fills some gaps if you don’t have AWS Premium Support available, and adds additional value otherwise. It can easily be deployed in existing Terraform pipelines. Please note that all resources will be cleaned up and deleted upon module call removal, including the reports, so make sure you remember REL09 and back up relevant reports accordingly.

      Feedback and contributions

      If you have any feedback please let me know through your preferred medium of contact.

      If you would like to contribute with bugfixes, additional functionality or check coverage, pull requests are welcome!

      Resources


      Posted

      in

      by