/review-checklists

This repo contains code and examples to operationalize Azure review checklists.

Primary LanguagePythonMIT LicenseMIT

GitHub Super-Linter

Azure Review Checklists

Quick links for using the checklists in this repo:

Summary of checklists supported and the respective responsible owners:

Checklist Status CodeOwners
ALZ GA FTA-ALZ-vTeam, ALZ-checklist-contributors
AKS GA @msftnadavbh @seenu433 @erjosito
ARO Preview @msftnadavbh @naioja @erjosito
AVD GA @igorpag @mikewarr @bagwyth
Cost GA @brmoreir @pea-ms
Multitenancy GA @arsenvlad @cherchyk
Security GA @mgodfrey50 @rudneir2
Application Delivery Networking GA @erjosito @andredewes
AVS design Preview @fskelly @mgodfrey50 @robinher
AVS implementation Preview @fskelly @mgodfrey50 @robinher
SAP Preview @AlastairMorrison @mottach @NaokiIgarashi
API Management Preview @andredewes @seenu433
Stack HCI Preview @mbrat2005 @steveswalwell @igomaa
Spring Apps Preview @bappadityams @vermegi @fmustaf
Azure DevOps Preview @roshair
SQL Migration Preview @karthikyella @dbabulldog-repo

What is an Azure Design Review?

A common request of many organisations, starting with the public cloud, is to have their design double-checked to make sure that best practices are being followed. The scope of this exercise could vary, from generic Azure landing zones to workload-specific deployments.

When doing Azure design reviews (or any review for that matter), Microsoft employees and Microsoft partners often leverage Excel spreadsheets as the medium of choice to document findings and track design improvements and recommendations. A problem with Excel spreadsheets is that they are not easily subject to revision control. Additionally, team collaboration with branching, issues, pull requests, reviews, and others is difficult at best—impossible in most cases.

Why this repository?

This repo separates the actual review checklist content from the presentation layer so that the JSON-formatted checklist can be subject to version control, and it can then be imported into an Excel spreadsheet by means of Visual Basic for Applications (VBA) macros for easier handling (not all of us like working natively with JSON). The provided Checklist Review Spreadsheet leverages code to interpret JSON from the VBA module in https://github.com/VBA-tools/VBA-JSON/, from which there is a copy in this repo to be self-contained (make sure you use the latest version though). The Checklist Review Spreadsheet includes some macros (find the source code both in the spreadsheet as well as here), which are accessible from control buttons in the main sheet.

Note: the VBA code in the spreadsheet does not work on Excel for Mac, due to some critical missing libraries.

Additionally, a Github action in this repository translates after every commit the English version of the checklist to additional languages (Japanese, Korean, Spanish, and Brazilian Portuguese), using the cognitive service Azure Translator. See an example of a translated checklist in aks_checklist.ja.json

Reporting errors and contributing

Please feel free to open an issue or create a PR if you find any error or missing information in the checklists, following the Contributing guidelines

Using the spreadsheet for Azure reviews

  1. Download the Excel spreadsheet from the latest release to your PC

  2. Use the dropdown lists to select the technology and language you would like to do your review

  1. Click the control button "Import latest checklist". After you accept the verification message, the spreadsheet will load the latest version of the selected technology and language

  2. (Optional) If you are going to distribute the spreadsheet to users who cannot work with macros (for example, either because of security reasons or because they use Office for Mac), save a version of the spreadsheet in xlsx format (instead of xlsm). Note that disabling macros will result in the spreadsheet losing its ability to import updated versions of the checklist or JSON-based Azure Resource Graph query results

  3. Go row by row, set the "Status" field to one of the available options, and write any remarks in the "Comments" field (such as why a recommendation is not relevant, or who will fix the open item)

    1. Since there are many rows in a review, it is recommended to proceed in chunks: either going area after area (first "Networking", then "Security", etc) or starting with the "High" priority elements and afterward moving down to "Medium" and "Low"
    2. If any recommendation is not clear, there is a "More Info" link with more context information.
    3. IMPORTANT: design decisions are not a checkbox exercise, but a series of compromises. It is OK to deviate from certain recommendations if the implications are clear (for example, sacrificing security with operational simplicity or lower cost for non-critical applications)

  4. Check the "Dashboard" worksheet for a graphical representation of the review progress

Security settings running macros

There are some settings that you might need to change in your system to run macro-enabled Excel spreadsheets. When initially opening the file you may see the following error, which prevents Excel from loading:

Excel cannot open the file 'review_checklist.xlsm' because the file format or file extension is not valid. Verify that the file has not been corrupted and that the file extension matches the format of the file.

In other cases, the file opens with the following message, which prevents you from being able to load the checklist items:

macro warning in excel

Unblock the file or add an exception to Windows Security

  1. You might need to unblock the file from the file properties in the Windows File Explorer so that you can use the macros required to import the checklist content from github.com:

how to unblock a file to run macros

  1. Additionally, you might want to add the macro-enabled spreadsheet file to the list of exceptions in Windows Security (in the Virus & Threat Protection section):

how to add an exception to windows security 1 how to add an exception to windows security 2 how to add an exception to windows security 3 how to add an exception to windows security 4

Using the spreadsheet to generate JSON checklist files (advanced)

If you wish to do contributions to the checklists, one option is the following:

  1. Load up the latest version of the checklist you want to modify
  2. Do the required modifications to the checklist items
  3. Push the button "Export checklist to JSON" in the "Advanced" section of controls in the checklist. Store your file in your local file system, and upload it to the checklists folder of this Github repo (use the format <technology>_checklist.en.json, for example, lz_checklist.en.json)
  4. This will create a PR and will be reviewed by the corresponding approvers.

Using Azure Resource Graph to verify Azure environments (advanced)

Some of the checks have associated Azure Resource Graph queries, which return a list of related resources and a compliance status for each. Resource Graph queries enable objective verification of the associated checks and make filling out the spreadsheet easier by collecting some environment details for you.

Along with the spreadsheet, this repo includes the script checklist_graph.sh. This script will run the graph queries stored in the JSON checklists and produce an output that can easily be copied and pasted into the spreadsheet, or alternatively generate a JSON file that can then be imported to the spreadsheet.

See the checklist_graph.sh README file for more information about how to use checklist_graph.sh.

Disclaimer

  • This is not official Microsoft documentation or software.
  • This is not an endorsement or a sign-off of an architecture or a design.
  • This code sample is provided "AS IT IS" without warranty of any kind, either expressed or implied, including but not limited to the implied warranties of merchantability and/or fitness for a particular purpose.
  • This sample is not supported under any Microsoft standard support program or service.
  • Microsoft further disclaims all implied warranties, including, without limitation, any implied warranties of merchantability or fitness for a particular purpose.
  • The entire risk arising out of the use or performance of the sample and documentation remains with you.
  • In no event shall Microsoft, its authors, or anyone else involved in the creation, production, or delivery of the script be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the sample or documentation, even if Microsoft has been advised of the possibility of such damages