Announcing the preview of PSArm

Steve

Announcing PSArm preview

Today, we are pleased to announce the first preview of a new experimental module that make it easier than ever for PowerShell customers to create Azure Resource Manager (ARM) templates: [PSArm]((https://github.com/powershell/psarm).

This module enables users to author ARM templates using PowerShell. Similar to Azure Bicep, PSArm is an independent module that creates the necessary ARM JSON template to deploy and configure Azure infrastructure in a PowerShell context. PSArm allows PowerShell users who are familiar with ARM to write complex deployment templates by mixing the declarative syntax of ARM with the iterative syntax of PowerShell.

PSArm supports PowerShell concepts to be deployed when authoring ARM templates, such as: – Variables, looping, conditionals, and pipelines – Completion support – Object-orientation, with an object model for ARM templates – Parameter validation

The PSArm module is still in early preview and is intended both as a demonstration both of how PowerShell can be leveraged to make ARM authoring easier and as a proof of concept for domain-specific languages (DSL) in PowerShell. As a preview release, there may be breaking changes as development continues based on user feedback.

How can I start using this module?

PSArm has been published to the PowerShell Gallery. The module can also be built from source by following the instructions on the PSArm GitHub repository.

Once you have the module installed you can begin authoring ARM templates with PowerShell. To use PSArm, use the Arm keyword followed by a scriptblock. From within this scriptblock, PSArm provides contextual functionality. Note that the file name must end with the .psarm.ps1 extension, for example newStorageAccount.psarm.ps1.

The following example builds an ARM template to create a new storage account:

param(
    [Parameter(Mandatory)]
    [string]
    $storageAccountName,

    [Parameter(Mandatory)]
    [string]
    $location,

    [Parameter()]
    [string]
    $accountType = 'Standard_LRS',

    [Parameter()]
    [string]
    $kind = 'StorageV2',

    [Parameter()]
    [string]
    $accessTier = 'Hot',

    [Parameter()]
    [string]
    $minimumTLSVersion = 'TLS1_2',

    [Parameter()]
    [bool]
    $supportsHTTPSTrafficOnly = 1,

    [Parameter()]
    [bool]
    $allowBlobPublicAccess = 1,

    [Parameter()]
    [bool]
    $allowSharedKeyAccess = 1
)

Arm {

    Resource $storageAccountName -Namespace 'Microsoft.Storage' -Type 'storageAccounts' -apiVersion '2019-06-01' -kind $kind -Location $location {
        ArmSku $accountType
        Properties {
            accessTier $accessTier
            minimumTLSVersion $minimumTLSVersion
            supportsHTTPSTrafficOnly $supportsHTTPSTrafficOnly
            allowBlobPublicAccess $allowBlobPublicAccess
            allowSharedKeyAccess $allowSharedKeyAccess
        }
    }
}

Because PSArm scripts are just ordinary PowerShell scripts, you can use a param block at the top of a .psarm.ps1 script as always to declare parameters, give them default values, mark them as mandatory, apply validation attributes like [ValidateSet(...)], and so on.

ARM template properties like resources and outputs are available in PSArm via keywords like Resource and Output. These keywords instantiate one resource or output instance at a time. These keywords can be used in any order.

Within each resource are resource-level keywords specific to that resource type, which enable you to specify attributes available to that resource. For resources with properties, a properties keyword specifies a block in which each resource property can be configured with its corresponding PowerShell keyword. These keywords can be discovered with PowerShell completions.

While using PSArm, PowerShell variables can be used removing the need for many ARM variable expressions, but there are a few cases where the ARM expressions may be necessary: – When a built-in ARM function needs to evaluated at deployment time, as in resourceGroup() or utcNow() – A variable is needed to be evaluated only once, as in uniqueString() to provide a hash value – When a secure input is required, as in the securestring parameter

PSArm also provides ARM built-in expression functions as their own keywords. These functions allow users to use PowerShell syntax to express function application and member access.

For more a more detailed explanation of the features and mechanisms available in PSArm, take a look at the README on the PSArm GitHub repository.

With the above PSArm script saved to newStorageAccount.psarm.ps1, you can turn it into an ARM JSON template with the Publish-PSArmTemplate cmdlet:

Publish-PSArmTemplate -Path .newStorageAccount.psarm.ps1 -Parameters @{
    storageAccountName = 'storageName'
    location = 'location'
}

This will create the equivalent ARM template in .template.json. This file can then be deployed like any other ARM template, for example using Azure PowerShell:

New-AzResourceGroupDeployment -ResourceGroupName myRG -TemplateFile .template.json

The resulting ARM template can be viewed below:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "psarm",
      "version": "0.1.0.0",
      "psarm-psversion": "7.1.0",
      "templateHash": "15035725580591843956"
    }
  },
  "resources": [
    {
      "name": "test",
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2019-10-01",
      "properties": {
        "mode": "Incremental",
        "expressionEvaluationOptions": {
          "scope": "inner"
        },
        "template": {
          "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
          "contentVersion": "1.0.0.0",
          "resources": [
            {
              "name": "psarmtest",
              "apiVersion": "2019-06-01",
              "type": "Microsoft.Storage/storageAccounts",
              "kind": "StorageV2",
              "location": "westus2",
              "sku": {
                "name": "Standard_LRS"
              },
              "properties": {
                "accessTier": "Hot",
                "minimumTlsVersion": "TLS1_2",
                "supportsHttpsTrafficOnly": true,
                "allowBlobPublicAccess": true,
                "allowSharedKeyAccess": true
              }
            }
          ]
        }
      }
    }
  ]
}

For more PSArm examples, see the examples folder in the PSArm repository.

Feedback and Support

Community feedback is essential to the development of PSArm and future experimentation. Feedback specifically on the conversion cmdlets, ConvertFrom-ArmTemplate and ConvertTo-PSArm, is appreciated. While there are no committed dates going forward, this is a quality driven project. If significant changes come in based off of user feedback, a release will occur to verify the issues have been addressed. To file an issue or to contribute, please visit the PSArm GitHub repository.