DOCSEARCHbyAlgolia
Submit Docs

Azure Resource Manager Template Toolkit (arm-ttk)

repository·master·Indexed 19 days ago

https://github.com/azure/arm-ttk

A framework for testing and analyzing ARM templates to ensure they follow security, best practice, and structural standards. It provides the Test-AzTemplate command to validate templates against test groups like deploymentTemplate, deploymentParameters, and createUIDefinition. The toolkit supports JSON and createUiDefinition scenarios, utilizes a caching system for Azure data, and includes a regular expression engine for template validation. It is compatible with Windows, Linux, and macOS via PowerShell Core.

Tokens
5.2K
Snippets
15
Records
26
Agent score
66%

What's inside arm-ttk

  1. Overview of Azure Resource Manager Template Toolkit (arm-ttk)

    master

    The Azure Resource Manager Template Toolkit (arm-ttk) is used for analyzing and testing Azure Resource Manager (ARM) Templates. It checks templates or sets of templates for coding best practices, such as validating author intent (e.g., identifying unused parameters), enforcing security practices (e.g., preventing plain text secrets), and ensuring appropriate use of language constructs (e.g., using environmental functions instead of hard-coded values).

    Note on Bicep: Since version 0.10, many deploymentTemplate test cases have moved to the Bicep linter. The TTK continues to support JSON and createUiDefinition scenarios.

  2. How to use Regular Expression patterns in arm-ttk

    master

    arm-ttk uses regular expressions defined in the /Regex directory to validate ARM templates. You can use these patterns by calling a PowerShell ScriptBlock named after the pattern file within a filter command (like Where-Object or its alias ?).

    Patterns are available in two formats:

    1. *.regex.txt: Static regular expressions.
    2. *.regex.ps1: PowerShell script generators that produce regular expressions based on input parameters.

    To use a pattern, use the syntax <PatternName> inside a filter.

    # Using a static pattern (e.g., ARM_Template_Expression)
$templateText | ?<ARM_Template_Expression>

# Using a generator pattern with a parameter (e.g., ARM_Parameter)
$templateText | ?<ARM_Parameter> -Parameter 'VMSize'

  3. Understand the Allowed-Values-Should-Actually-Be-Allowed test case

    master
    This specific test case validates that values defined in the basics section of a CreateUIDefinition.json file are actually permitted by the parameters defined in the corresponding AzureDeploy.json file. It ensures consistency between the UI definition (which dictates what a user sees/selects in the portal) and the actual deployment template parameters.

  4. Configure Pass and Fail test cases

    master

    TTK unit tests use specific subfolders to determine expected outcomes:

    Pass Subfolder

    Contains positive test cases. The TTK rule runs against any .json file or subfolder containing templates within this directory.

    • Success condition: The rule must NOT produce an error. If an error is produced, the test fails.
    • Shared tests: A .txt file can be used as a pointer to another test file to allow sharing test cases across different rules.
    • Common use case: Ensuring marketplace sample templates do not throw errors.

    Fail Subfolder

    Contains negative test cases. The TTK rule runs against any .json file or subfolder containing templates within this directory.

    • Success condition: The rule MUST produce an error/violation. If no error is produced, the test fails.
    • Best Practice: Each negative test case should contain exactly one failure or violation to ensure cases are caught independently.

  5. How to use cached Azure information in TTK testcases

    master

    The cache/ directory contains cached Azure data used by tests to improve performance and availability. To access this data within a TTK testcase, include the $AllResources parameter.

    For a concrete implementation example, refer to the test case: [ApiVersions-Should-Be-Recent](../testcases/deploymentTemplate/apiVersions-Should-Be-Recent.test.ps1).

  6. Structure of a TTK Unit Test

    master

    TTK unit tests are located in the /unit-tests directory at the root of the repository. Each test is organized into a folder named after the specific rule it validates.

    To create a new unit test, create a folder matching the rule name and populate it with the following structure:

    • /Pass: Contains positive test cases (JSON templates that should NOT trigger the rule).
    • /Fail: Contains negative test cases (JSON templates that SHOULD trigger the rule).
    • /[folder-name].tests.ps1: The test execution script (boilerplate file).

    Example mapping: A rule named Parameters-Must-Be-Referenced will have its tests in /unit-tests/Parameters-Must-Be-Referenced/.

  7. Handle multiple mainTemplate.json or azuredeploy.json files

    master
    If a unit test requires running against a file named mainTemplate.json or azuredeploy.json, and you need multiple versions of these files for different test scenarios, do not attempt to use multiple files with the same name in the same directory. Instead, create a subfolder for each specific test case to isolate the files.

  9. Use .regex.ps1 pattern generators

    master

    Generators are PowerShell scripts defined in .regex.ps1 files. Unlike static text files, generators can accept input parameters to dynamically construct a regular expression.

    If a generator is called without parameters, it uses its defined default behavior. If parameters are provided, they are used to refine the resulting regex.

    # Find all references to a specific parameter using a generator
$templateText | ?<ARM_Parameter> -Parameter 'VMSize'

# Find all parameters (using the generator's default behavior)
$templateText | ?<ARM_Parameter>

  10. Structure of a TTK Test file

    master

    A TTK test is a PowerShell script that validates Azure Resource Manager (ARM) templates. To create a new test, follow this structure:

    1. Inline Help: Use PowerShell comment-based help (<# .Synopsis ... .Description #>) at the top of the file. This allows users to run Get-Help <path_to_test> to understand the validation logic.
    2. Test Parameters: Define a param() block to receive data from the ARM template. You should only include the parameters your test requires.
    3. Test Logic: Implement the validation logic using the provided template objects or text.

    Tests placed in ./testcases/deploymentTemplate/ will automatically run against any JSON object containing a $schema matching *deploymentTemplate*.

    <#
.Synopsis
    Ensures that parameters are referenced
.Description
    Ensures that all Azure Resource Manager Template
#>

param(
    # The Template Object
    [Parameter(Mandatory = $true, Position = 0)]
    [PSObject]
    $TemplateObject,

    # The Template JSON Text
    [Parameter(Mandatory = $true, Position = 0)]
    [PSObject]
    $TemplateText
)

  11. Test the TTK module locally

    master
    To verify the integrity of the Azure Resource Manager Template Toolkit (TTK) module, you can run the unit tests located in the unit-tests/_arm-ttk-module/ directory. Each .tests.ps1 file in this directory targets a specific subsection of the TTK's functionality. A successful test run should result in no failures or errors.

  12. Run arm-ttk in Azure DevOps Pipelines

    master

    To use arm-ttk in Azure DevOps, you have two primary options:

    1. Manual Installation: Clone the repository or download the latest build from https://aka.ms/arm-ttk-latest onto your build machine.
    2. Marketplace Extension: Use the ARMTTKExtension published by Sam Cogan.

    For custom pipeline implementations, refer to the Azure Quickstart Templates pipeline configuration for examples of downloading and running the tests.