Skip to content

Using Bicep source#

PSRule for Azure discovers and analyzes Azure resources contained within Bicep files. To enable this feature, you need to:

  • Enable expansion.
  • For modules (if used):
    • Define a deployment or parameters file.
    • Configure path exclusions.

Abstract

This topic covers how you can validate Azure resources within .bicep files. To learn more about why this is important see Expanding source files.

Enabling expansion#

To expand Bicep deployments configure ps-rule.yaml with the AZURE_BICEP_FILE_EXPANSION option.

ps-rule.yaml
# YAML: Enable expansion for Bicep source files.
configuration:
  AZURE_BICEP_FILE_EXPANSION: true

Note

If you are using JSON parameter files exclusively, you do not need to set this option. Instead continue reading using parameter files.

Setup Bicep#

To expand Azure resources for analysis from Bicep source files the Bicep CLI is required. The Bicep CLI is already installed on hosted runners and agents used by GitHub Actions and Azure Pipelines. For details on how to configure Bicep for PSRule for Azure see Setup Bicep.

Building files#

It's not necessary to build .bicep files with bicep build or az bicep build. PSRule will automatically detect and build .bicep files. You may choose to pre-build .bicep files if the Bicep CLI is not available when PSRule is run.

Important

If using this method, follow using templates instead. Using bicep build transpiles Bicep code into an Azure template .json.

Testing Bicep modules#

Bicep allows you to separate out complex details into separate files called modules. To expand resources, any parameters must be resolved.

Tip

If you are not familiar with the concept of expansion within PSRule for Azure see Expanding source files.

Two types of parameters exist, required (also called mandatory) and optional. An optional parameter is any parameter with a default value. Required parameters do not have a default value and must be specified.

Example modules/storage/main.bicep

// Required parameter
param name string

// Optional parameters
param location string = resourceGroup().location
param sku string = 'Standard_LRS'

To specify required parameters for a module, create a deployment or test that references the module.

Example deploy.bicep

// Deploy storage account to production subscription
module storageAccount './modules/storage/main.bicep' = {
  name: 'deploy-storage'
  params: {
    name: 'stpsrulebicep001'
    sku: 'Standard_GRS'
  }
}

Example modules/storage/.tests/main.tests.bicep

// Test with only required parameters
module test_required_params '../main.bicep' = {
  name: 'test_required_params'
  params: {
    name: 'sttest001'
  }
}

Configuring path exclusions#

Unless configured, PSRule will discover all .bicep files when expansion is enabled. Bicep module files with required parameters will not be able be expanded and should be excluded. Instead expand resources from deployments or tests.

To do this configure ps-rule.yaml with the input.pathIgnore option.

Example ps-rule.yaml

configuration:
  # Enable expansion for Bicep source files.
  AZURE_BICEP_FILE_EXPANSION: true

input:
  pathIgnore:
  # Exclude bicepconfig.json
  - 'bicepconfig.json'
  # Exclude module files
  - 'modules/**/*.bicep'
  # Include test files from modules
  - '!modules/**/*.tests.bicep'

Note

In this example, Bicep files such as deploy.bicep in other directories will be expanded.

Using parameter files#

When using Bicep, you don't need to use parameter files. You can call .bicep files directly from other .bicep files with modules by using the module keyword.

Alternatively, Bicep supports two options for parameter files:

  • JSON parameter files — This format uses conventional JSON syntax compatible with ARM templates.
  • Bicep parameter files — This format uses Bicep language from a .bicepparam file to reference a Bicep module.

Each option is described in more detail in the following sections.

Using JSON parameter files#

You can choose to expand and test a Bicep module from JSON parameter files by metadata.

When using parameter files exclusively, the AZURE_BICEP_FILE_EXPANSION configuration option does not need to be set. Instead set the AZURE_PARAMETER_FILE_EXPANSION configuration option to true. This option will discover Bicep files from parameter metadata.

Example ps-rule.yaml

configuration:
  # Enable expansion for Bicep module from parameter files.
  AZURE_PARAMETER_FILE_EXPANSION: true

input:
  pathIgnore:
  # Exclude bicepconfig.json
  - 'bicepconfig.json'
  # Exclude module files
  - 'modules/**/*.bicep'

Example template.parameters.json

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "metadata": {
        "template": "./template.bicep"
    },
    "parameters": {
        "storageAccountName": {
            "value": "bicepstorage001"
        },
        "tags": {
            "value": {
                "env": "test"
            }
        }
    }
}

Using Bicep parameter files#

v1.34.0

You can use .bicepparam files to reference your Bicep modules as a method for providing parameters. Using the Bicep parameter file format, allows you to get many of the benefits of the Bicep language.

For example:

using 'main.bicep'

param storageAccountName = 'bicepstorage001'
param tags = {
  env: 'test'
}

Learn

To learn more about Bicep parameter files see Create parameters files for Bicep deployment.

Note

To use Bicep parameter files you must use a minimum of Bicep CLI version 0.18.4. You can configure PSRule to check for the minimum Bicep version. See configuring minimum version for information on how to enable this check.

Restoring modules from a private registry#

Bicep modules can be stored in a private registry. Storing modules in a private registry gives you a central location to reference modules across your organization.

To test Bicep deployments which uses modules stored in a private registry, these modules must be restored. The restore process automatically occurs when PSRule is run, however some additional steps are required to authenticate.

To prepare your registry for storing Bicep modules see Create private registry for Bicep modules.

To configure authentication for PSRule to a private registry:

Some organizations may want to expose Bicep modules publicly. This can be configured by enabling anonymous pull access. To configure your registry see Make your container registry content publicly available.

Note

To use anonymous pull access to a registry you must use a minimum of Bicep CLI version 0.15.31. You can configure PSRule to check for the minimum Bicep version. See configuring minimum version for information on how to enable this check.

Configure bicepconfig.json#

To authenticate to a private registry, configure bicepconfig.json by setting credentialPrecedence. This setting determines the order to find a credential to use when authenticating to the registry.

Use the following credential type based on your environment as the first value of the credentialPrecedence setting:

  • Environment — Use environment variables to authenticate to the registry. This is the most common scenario for CI pipelines and works for cloud-hosted or self-hosted agents/ private runners.
  • ManagedIdentity — Use a managed identity to authenticate to the registry. This may be applicable for scenarios where you are using self-hosted agents or private runners. You must configure a System-Assigned managed identity for the Azure Virtual Machine or Virtual Machine Scale Set.

Example bicepconfig.json

{
  "credentialPrecedence": [
    "Environment",
    "AzureCLI",
  ]
}

Tip

The bicepconfig.json configures the Bicep CLI. You should commit this file into a repository along with your Bicep code.

Granting access to a private registry#

To access a private registry use an Entra ID identity which has been granted permissions to pull Bicep modules. When using Environment credential type, see create a service principal that can access resources to create the identity. If you are using the ManagedIdentity credential type, an identity is created for when you configure the managed identity.

After configuring the identity, grant access using the AcrPull built-in RBAC role on the Azure Container Registry.

Set pipeline environment variables#

When using the Environment credential type, environment variables should be set in the pipeline. Typically, the following three environment variables should be set:

  • AZURE_CLIENT_ID — The Client ID (also called Application ID) of an App Registration in Azure AD. This will be represented as a GUID.
  • AZURE_CLIENT_SECRET — A valid secret that was generated for the App Registration.
  • AZURE_TENANT_ID — The Tenant ID that identifies your specific Azure AD tenant where your App Registration is created. This will be represented as a GUID.

Note

The environment credential type also supports other environment variables that may be applicable to your environment. To see a list visit EnvironmentCredential Class.

Configure the microsoft/ps-rule action with Azure environment variables.

- name: Analyze Azure template files
  uses: microsoft/ps-rule@v2.9.0
  with:
    modules: PSRule.Rules.Azure,PSRule.Monitor
    conventions: Monitor.LogAnalytics.Import
  env:
    # Define environment variables using GitHub encrypted secrets
    AZURE_CLIENT_ID: ${{ secrets.BICEP_REGISTRY_CLIENTID }}
    AZURE_CLIENT_SECRET: ${{ secrets.BICEP_REGISTRY_CLIENTSECRET }}
    AZURE_TENANT_ID: ${{ secrets.BICEP_REGISTRY_TENANTID }}

Important

Environment variables can be configured in the workflow or from a secret. To keep BICEP_REGISTRY_CLIENTSECRET secure, use an encrypted secret.

Configure the ps-rule-assert task with Azure environment variables.

- task: ps-rule-assert@2
  displayName: Analyze Azure template files
  inputs:
    modules: 'PSRule.Rules.Azure'
  env:
    # Define environment variables within Azure Pipelines
    AZURE_CLIENT_ID: $(BICEPREGISTRYCLIENTID)
    AZURE_CLIENT_SECRET: $(BICEPREGISTRYCLIENTSECRET)
    AZURE_TENANT_ID: $(BICEPREGISTRYTENANTID)

Important

Variables can be configured in YAML, on the pipeline, or referenced from a defined variable group. To keep BICEPREGISTRYCLIENTSECRET secure, use a variable group linked to an Azure Key Vault.

Recommended content#

Comments