DEV Community: Cole Heard

Input Validation - Terraform Tips & Tricks

Cole Heard — Sun, 10 Mar 2024 00:20:11 +0000

Terraform modules are a great way to follow D.R.Y. development principles. I’ve written about D.R.Y. in the past, but to sum it up briefly:

The DRY (“Don't Repeat Yourself”) principle follows the idea of every logic duplication being eliminated by abstraction. This means that during the development process we should avoid writing repetitive duplicated code as much as possible.

Writing a module for use by others on your team or the community at large can present some challenges.

If someone isn't familiar with my code - they may input a value that I did not account for.

Incorrect input can cause deployment failure or, even more frightening, deploy an incorrect configuration without being immediately apparent.

In this post, I’ll be covering some of the methods I’ve used to enforce input standards.

Structured Types
Validation Blocks
- Going Further with Functions
- Adding For Expressions
Wrapping Up

Structured Types

You'll see the most basic form of type enforcement everywhere you look.

The variable below enforces the input standards with the type argument.

This variable will only accept a bool, true or false.



variable "validation_environment" {
  type        = bool
  description = "Set as true to enable validation environment."
  default     = false
}

The input must be a number.



variable "maximum_sessions_allowed" {
  type        = number
  description = "The maximum number of concurrent sessions per host."
  default     = 3
}

You can nest and combine these types using basic Terraform syntax. In the example below, Terraform must receive a list. Even if the list only contains a single string, it is a list of one string.



variable "included_location_ids" {
  type        = list(string)
  description = "A list of Named Location IDs that will this policy will apply against."
  default     = ["All"]
}

In the next example, the type is defined as a map of objects. We've added a few other conditions as well - Each object must have 4 key-value pairs (KPV). Each key must match the defined name, "app_name" or "local_path". Each KPV value is also type defined: string, number, bool, etc.



variable "application_map" {
  type = map(object({
    app_name     = string
    local_path   = string
    aad_group    = string
    cmd_argument = string
  }))
  description = "A map of all applications and their metadata."
  default     = null
}

Lets reconsider enforcing the cmd_argument KPV from the object.



variable "application_map" {
  type = map(object({
    app_name     = string
    local_path   = string
    aad_group    = string
  }))
  description = "A map of all applications and their metadata."
  default     = null
}

This change did remove the enforcement of cmd_argument, but it also barred its presence completely.



variable "application_map" {
  type = map(object({
    app_name     = string
    local_path   = string
    aad_group    = string
    cmd_argument = optional(string)
  }))
  description = "A map of all applications and their metadata."
  default     = null
}

The optional modifier allows cmd_argument to be included within the object, but it won't reject an object without it.

Validation Block

The condition argument succeeds if it evaluates to true. If the statement evaluates to false, Terraform cancels the operation and outputs the string value of the error_message argument.



variable "stars" {
  type        = number
  description = "Please rate your sanctification with my module. Select the number of stars, 1 through 5."
  default     = 5
  validation {
    condition = (
      var.stars >= 1 &&
      var.stars <= 5
    )
    error_message = "Please select a number of stars 1 through 5."
  }
}

Going Further with Functions

We can expand the validation block use with Terraform functions.

In the example below, the anytrue function evaluates the input against each statement. If any of the three statements within evaluate to true, Terraform will proceed.



variable "primary_color" {
  type        = string
  description = "The primary color of your choice!"
  validation {
    condition = anytrue([
      lower(var.primary_color) == "blue",
      lower(var.primary_color) == "red",
      lower(var.primary_color) == "yellow"
    ])
    error_message = "The var.primary_color input is incorrect. Please select blue, red, or yellow."
  }
}

Did you notice the lower function was used here as well? We don't care if the user inputs "BLUE" or "blue" do we? They're both valid primary colors.

Adding For Expressions

For Expressions can be used alongside functions to build more thorough validation rules.

Anytrue evaluate every string as it loops each of the ingested list's values.
The result of each loop is compiled into a new list of bools.
Finally, the list of bools is evaluated against the alltrue function. If any value in the list is false, the condition will fail and trigger error_message.



variable "excluded_platforms" {
  type        = list(string)
  description = "The policy will enforce if the sign-in comes from the listed device platform(s)."
  default     = ["none"]
  validation {
    condition = alltrue([
      for i in var.excluded_platforms : anytrue([
        i == "none",
        i == "all",
        i == "android",
        i == "iOS",
        i == "linux",
        i == "macOS",
        i == "windows",
        i == "windowsPhone",
        i == "unknownFutureValue"
      ])
    ])
    error_message = "Invalid input for included_platforms. The list may only contain the following value(s): none, all, android, iOS, linux, macOS, windows, windowsPhone or unknownFutureValue."
  }
}

Wrapping Up

Validation blocks and structured types are both excellent tools for input validation and consistency.

Mix and match both techniques for the best outcome.

GitHub Actions - Automated Terraform-docs

Cole Heard — Sat, 16 Sep 2023 22:30:36 +0000

Earlier this year I wrote about the challenges I faced creating a Terraform module. I mentioned then that I was leveraging terraform-docs and GitHub Actions to automate documentation, but a full workflow walkthrough was out of that post's scope.

This post, however, is entirely focused on automated documentation.

If you're looking for an easy way to save time, enforce documentation formatting standards, or ensure documentation is kept up-to-date - my autodoc workflow is a great place to start.

The Workflow
- Repo clone
Generating Documentation
- Action arguments
- Markdown formatting
- Resulting output
Premerge Review
- Echoing contents
  - Escape characters
  - Multiline string
- Pull request comment
Wrapping Up

The Workflow

The workflow starts by defining a name, a start condition, and a host that will execute the job.

name: "Autodoc Workflow - Terraform-docs"

on:
  pull_request:

jobs:
  tfdocs:
    runs-on: ubuntu-latest

On a pull request, GitHub Actions will provision a Ubuntu VM with the latest OS version considered "stable" by GitHub.

Note: The -latest runner images are the latest stable images that GitHub provides, and might not be the most recent version of the operating system available from the operating system vendor.

Repo clone

Now that the job has been defined, the first step will clone the repository down to the runner. More specifically, it will pull the PR head from Actions context.

    steps:
    - name: Pull request checkout
      uses: actions/checkout@v3
      id: checkout
      with:
        ref: ${{ github.event.pull_request.head.ref }}

With a local copy of the code now available, the runner can update the documentation.

Generating documentation

This step uses the terraform-docs action to update the README.md.

    - name: README.md generation
      uses: terraform-docs/gh-actions@main
      id: tfdocs
      with:
        config-file: terraform-docs.yaml
        working-dir: .
        output-file: README.md
        output-method: inject
        git-push: "true"

If you'd prefer to install the CLI tool on the runner and execute the commands directly from the shell, other installation options exist.

Action arguments

The terraform-docs action accepts many arguments, but the five below are used by this workflow.

config-file accepts the terraform-docs config file.
working-dir specifies the location of the terraform files.
output-file defines the name of the generated/updated doc.
output-method accepts print, replace, or inject. If other content (e.g. content not generated by terraform-docs) exists within the README.md file, you'll want to use inject. Inject updates the existing file and places the newly created documentation between the hardcoded delimiters  and .
git-push is set to "true" and adds the newly updated document to the pull request.

Markdown formatting

GitHub understands markdown formatting in readme files, posts, and comments. The terraform-docs.yaml file specifies markdown output to take advantage of this.

formatter: "markdown table"

You can find the full example terraform-docs.yaml file here.

Resulting output

This is what the README.md file looks like after the pull request is merged:

Premerge Review

Now that the README.md has been updated, approvers will want to review the changes prior to merging branches.

The next two steps will post updated content to pull request review thread for the approver's convenience.

Echoing contents

The output step echoes the file content into a standard GitHub environmental variable, github_env.

    - name: Output README.md
      id: output
      run: |
        echo 'readme<<EOF' >> $GITHUB_ENV
        echo "$(<README.md)" >> $GITHUB_ENV
        echo 'EOF' >> $GITHUB_ENV

Escape characters

Streaming output of the file into a variable will strip the content of "escape characters", including newline. To preserve these special characters, $(<README.md) is wrapped in double quotes.

echo "$(<README.md)"

Multiline strings

Action's requirements surrounding environmental variables restrict the use of multiline strings. "EOF" (end of file) is used as the delimiter to circumvent this restriction.

echo 'readme<<EOF' >> $GITHUB_ENV
echo "$(<README.md)" >> $GITHUB_ENV
echo 'EOF' >> $GITHUB_ENV

The updated markdown content can now be used in the next step.

Pull request comment

The last step in the workflow creates a comment on the pull request thread in GitHub with the script action.

A fine-grained token grants access to the repository. It is stored as the secret GH_TOKEN.

    - name: Pull request comment
      id: comment
      uses: actions/github-script@v6
      with:
        github-token: ${{ secrets.GH_TOKEN }}
        script: |
          const output = `Terraform-docs has updated the README.md. 

          ${process.env.readme}`
          github.rest.issues.createComment({
            issue_number: context.issue.number,
            owner: context.repo.owner,
            repo: context.repo.repo,
            body: output
          })

The markdown stored in the previous step is referenced with ${process.env.readme}.

After the job is completed, this is what the comment looks like:

Wrapping up

The job is complete and the documentation has been updated! If you'd like to test this workflow yourself, fork and modify my example module - Configure the repository permissions, modify a new branch, and kick off a pull request to see it in action.

If you're interested in learning more about terraform-docs, checkout their user guide or drop by their slack.

Thanks for taking the time read this post!

GitHub Actions - Azure Terraform CI/CD

Cole Heard — Wed, 05 Jul 2023 22:45:07 +0000

Terraform is my preferred tool for Azure resource creation. I still run some Terraform commands from my local shell, but I've made a real effort to execute the bulk of my changes with GitHub Actions.

This post will detail my basic Azure Terraform pipeline. If you're looking for more advanced content, this is not the article for you.

First, I will highlight some workflow prerequisites. Once those have been covered, I will walkthrough the pipeline, step-by-step.

Take a seat and let's get started.

Prerequisites
The Workflow
- Getting Started
- Azure Authentication
- Access to Private Repositories
- Terraform Prep
- Checkov
- More Terraform
- Checking the Plan
- Pull Request Comment
- Terraform Apply
Wrapping up

Prerequisites

The workflow does not exist in a vacuum - there are a few things that need to be configured outside of the workflow itself.

Branch protection: Enforced Branch protection requires the use of pull requests and merges. The code will always be merged from another branch to main, the pull request will detail the specific changes to be made, and the main branch will more reliably reflect the current state of the environment.

GitHub Token: A fine-grained token grants access to private repositories. The token is stored as a secret for later use.

Azure Credentials: An app registration is used to authenticate the runner to Azure. The app registration's associated client secret - along with the subscription, tenant, and management endpoint are stored as a GitHub secret (in JSON syntax).



{                                   
    "clientId": "12345678-1234-5678-9012-345678901234",
    "clientSecret": "0000000000000000000000000000000000000000",
    "subscriptionId": "1010101-0101-0101-0101-010101010101",
    "tenantId": "ABCDEFG-HIJK-LMNO-PQRS-123456789012",
    "managementEndpointUrl": "https://management.core.windows.net/"
}

Azure Storage Account: This is an Azure focused project, so an azurerm backend seemed appropriate. An Azure Storage Account was created to store Terraform's statefile. The app registration's service principal has contributor rights to the storage account - Terraform will authenticate with the same secret stored above (more on that later).

The Workflow

Now that the prerequisites have been addressed, we will dissect the pipeline, tfpipeline.yaml.

Getting Started

The workflow will only begin once a trigger condition has been met, as described by on:



name: "Basic Terraform Pipeline"

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  terraform:
    name: 'Terraform - Ubuntu'
    runs-on:    Self-hosted

    defaults:
      run:
        shell: bash

This workflow is waiting for one of two events to occur:

A pull request is opened.
A push is made to the main branch.

On these conditions, the self-hosted runner starts the Job as defined below.

The checkout step clones the repository down to the runner.



    steps:
      - name: Code Checkout
        id: checkout
        uses: actions/checkout@v3

Azure Authentication

The Azure Login Action authenticates with the Azure JSON secret.



      - name: Azure Authentication
        id: login
        uses: azure/login@v1
        with:
          creds: ${{ secrets.AZJSON }}

The parse step uses jq to parse the Azure JSON. The key values are echoed to environmental variables for use by Terraform.

The variables are ultimately passed to $GITHUB_ENV, one of GitHub Actions default environmental variables.



      - name: JSON Parse
        id: parse
        env:
          AZJSON: ${{ secrets.AZJSON }}
        run: |
          ARM_CLIENT_ID=$(echo $AZJSON | jq -r '.["clientId"]')
          ARM_CLIENT_SECRET=$(echo $AZJSON | jq -r '.["clientSecret"]')
          ARM_TENANT_ID=$(echo $AZJSON | jq -r '.["tenantId"]')
          ARM_SUBSCRIPTION_ID=$(echo $AZJSON | jq -r '.["subscriptionId"]')
          echo ARM_CLIENT_ID=$ARM_CLIENT_ID >> $GITHUB_ENV
          echo ARM_CLIENT_SECRET=$ARM_CLIENT_SECRET >> $GITHUB_ENV
          echo ARM_TENANT_ID=$ARM_TENANT_ID >> $GITHUB_ENV
          echo ARM_SUBSCRIPTION_ID=$ARM_SUBSCRIPTION_ID >> $GITHUB_ENV

Access to Private Repositories

The GitHub token is streamed to .netrc. Git is then configured to use https for the logon. These git changes provide access to the private registry configured within the same GitHub org.

This step also disables git's detached head warnings.



      - name: GitHub Token
        id: token
        env:
          TOKEN: ${{ secrets.GHTOKEN }}
        run: |
          echo "machine github.com login x password ${TOKEN}" > ~/.netrc
          git config --global url."https://github.com/".insteadOf "git://github.com/"
          git config --global advice.detachedHead false

Terraform Prep

Terraform is installed and initialized.

The azurerm backend is configured to use environmental variables created during the parse step. Only a single secret is maintained for all Azure authentication.



      - name: Install Terraform
        uses: hashicorp/setup-terraform@v2.0.3
        with:
          terraform_version: 1.3.5

      - name: Terraform Init
        id: init
        run: |
          terraform init

Checkov

Checkov is an open-source static code analysis tool.
The tool compares the code to defined policy - the policies can be out-of-the-box security checks or custom .py or .yaml files.

Here Pip installs Checkov.



      - name: Install Checkov
        id: checkov
        if: github.event_name == 'pull_request'
        run: |
          pip install checkov

Notice the if: expression. These steps only run if the trigger event was a pull request.

Checkov will now run.



      - name: Checkov Static Test
        id: static
        if: github.event_name == 'pull_request'
        run: |
          checkov -d . --download-external-modules true

Checkov should run after Terraform init; any modules called by Terraform are installed during init and we'll want Checkov to test their code as well.

More Terraform

The next few steps are Terraform staples. We run format, validate, and plan.



      - name: Terraform Format
        id: fmt
        run: terraform fmt -check -recursive
        continue-on-error: true

      - name: Terraform Validate
        id: validate
        run: terraform validate -no-color     

      - name: Terraform Plan
        id: tplan
        env: 
          TF_VAR_secret: '${{ secrets.example_secret }}'
        run: |
            terraform plan -no-color

Checking the Plan

This step requires another Terraform plan run. The previous plan did not output to a file - the console output from tplan will be used later.



      - name: Checkov Plan Test
        id: cplan
        if: github.event_name == 'pull_request'
        env: 
           TF_VAR_secret: '${{ secrets.example_secret }}'
        run: |
            terraform plan --out plan.tfplan
            terraform show -json plan.tfplan > tfplan.json
            ls
            checkov -f tfplan.json --framework terraform_plan

Pull Request Comment

This step uses the GitHub Script action.

A comment will be created on the pull request. The outcome of many previous steps is displayed for review. Additionally, the full output of the Terraform plan is available as well.

Much of this step's code was borrowed from the Setup Terraform Action documentation.



      - name: Pull Request Comment
        id: comment
        uses: actions/github-script@v3
        if: github.event_name == 'pull_request'
        env:
          TPLAN: "terraform\n${{ steps.tplan.outputs.stdout }}"
        with:
          github-token: ${{ secrets.GHTOKEN }}
          script: |
            const output = `
            ### Pull Request Information
            Please review this pull request. Merging the PR will run Terraform Apply with the plan detailed below.

            #### Terraform Checks
            Init: \`${{ steps.init.outcome }}\`
            Format: \`${{ steps.fmt.outcome }}\`
            Validation: \`${{ steps.validate.outcome }}\`
            Plan: \`${{ steps.tplan.outcome }}\`

            #### Checkov
            Static: \`${{ steps.static.outcome }}\`
            Plan: \`${{ steps.cplan.outcome }}\`

            <details><summary>Plan File</summary>

            \`\`\`${process.env.TPLAN}\`\`\`

            </details>

            `
            github.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: output
            })

This is what the comment looks like:

If the trigger event was a pull request, the workflow ends here.

Terraform Apply

The workflow only runs Terraform apply when the push occurs on the main branch.



      - name: Terraform Apply
        id: apply
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
        env:
          TF_VAR_domain_pass: '${{ secrets.DOMAIN_JOIN_PASS }}'
          TF_VAR_local_pass: '${{ secrets.LOCAL_ADMIN_PASS }}'
          TF_VAR_workspace_key: '${{ secrets.LA_WORKSPACE_KEY }}'
        run: terraform apply -auto-approve

That's all. The workflow tour is finished.

Here is what it looks like all put together:

Wrapping up

I've found a lot of value deploying resources with this workflow:

Resources will be created using the same method, every deployment.
With Branch protection enabled, approvals can easily be incorporated into the deployment process.
Deploying resources with a purpose-built service principal follows the principal of least privilege.
Automated policy checks ensures that they're always being run.

If you enjoyed this article, take a look at my SharePoint Framework pipeline.

Until next time!

GitHub Actions - SharePoint Framework CI/CD

Cole Heard — Thu, 09 Mar 2023 12:23:40 +0000

The SharePoint Framework (SPFx) is Microsoft's development model for creating custom web parts in SharePoint Online. It can greatly expand SharePoint's capabilities - something out-of-the-box SharePoint Online desperately needs.

This guide will walk you through the creation of a basic CI/CD pipeline for SharePoint development. The GitHub Action workflow will build and deploy custom SharePoint web parts directly to your tenant.

Why write SPFx web parts?
Azure Active Directory prerequisites
- Service Account
- Conditional Access
- Application Consent
Pipeline walkthrough
- Workflow triggers
- Running the job
- Setup steps
- Deployment steps
Wrapping up

Why write SPFx web parts?

You can build some useful web parts and widgets with SPFx.

It can also add features Microsoft should have included standard.

For instance - SharePoint Online does not have a dynamically updating table of contents. You have to type it out manually.

If you want a dynamic table of contents you need a custom web part.

Azure Active Directory prerequisites

Before building the pipeline, a few Azure Active Directory prerequisites must be met.

Service Account

A service account (SA) with the appropriate permissions in SharePoint is required to deploy the .sspkg to the application catalog.

If targeting a single site, the account will need Site Collection Administrator.
If targeting the tenant as a whole, the account will likely need SharePoint Administrator.

Unfortunately, we cannot use a service principal/application registration for SharePoint.

Attention: Currently, SharePoint does not support authentication using Azure AD App ID and Secret. CLI for Microsoft 365 commands that call the SharePoint APIs will fail while logged in to Microsoft 365 using a Secret.

See the documentation for additional information on this limitation.

Conditional Access

Conditional Access rules should be configured allowing the SA access only if certain conditions are met.

I would highly recommend building a policy leveraging some or all of these rules:

Identity (i.e. apply only to the SA)
Trusted IP ranges
Runner OS
Cloud Application (31359c7f-bd7e-475c-86db-fdb8c937548e)

Application Consent

The SA will need application consent to login to the PnP Management Shell. Run the PowerShell commands below in the Azure Cloud Shell.



Install-Module PnP.PowerShell
Register-PnPManagementShellAccess

You may not be able to perform these actions in a development M365 tenant - the developer instance prohibits the use of the Cloud Shell.

Pipeline walkthrough

Now that the prerequisites have been addressed, we will dissect the pipeline, spfxpipeline.yaml.

Workflow triggers

The workflow will only begin once a trigger condition has been met, as described by on:



name: "Basic SharePoint Framework Pipeline - Microsoft 365"

on:
  push:
    branches:
      - 'main'
  workflow_dispatch:

This workflow is waiting for one of two events to occur:

A push occurs on the main branch.
A "workflow_dispatch" is manually triggered - useful when testing.

Once triggered, the workflow will kick off a Job.

Running the job

We start by labeling the job and selecting a runner.



jobs:
  deployment:
    name: 'SPFx Deployment'
    runs-on: self-hosted
    steps:

The runs-on: argument defines the runner our job will execute on.

In the example above, I use a self-hosted runner provisioned within Azure.

Substitute self-hosted with ubuntu-latest to use a GitHub-hosted runner.

Next, steps: define the Job's individual actions.

Setup steps

The first two steps are Actions. Actions are small, purpose built applets.

Action steps are defined with the uses: keyword.

The checkout action is a workflow staple - it clones the repository's code down to the runner.

The setup-node action installs and configures node.



      - name: Checkout
        uses: actions/checkout@v3

      - name: Node.js install
        uses: actions/setup-node@v1
        with:
          node-version: 16.x

The next few steps run commands directly in the runner's shell.

Run steps are defined by the run: keyword.

One step installs NPM (with the CI switch) and the next one installs Gulp globally.



      - name: NPM install
        run: npm ci

      - name: Gulp install
        run: npm i -g gulp

The environment has been configured.

Deployment steps

The runner can now compile our web part. The step below builds our package with two Gulp commands.



      - name: Gulp package
        run: |
          gulp bundle --ship
          gulp package-solution --ship

The action-cli-login action will authenticate with the service account discussed earlier.

As the SA's credentials are sensitive, the workflow will reference GitHub Action Secrets to inject the credentials into the pipeline as needed.



      - name: M365 login
        id: login
        uses: pnp/action-cli-login@v2.2.1
        with:
          ADMIN_USERNAME:  ${{ secrets.ADMIN_USERNAME }}
          ADMIN_PASSWORD:  ${{ secrets.ADMIN_PASSWORD }}

Finally, the package is deployed to the tenant's SharePoint application catalog using action-cli-deploy.

We specify the package's relative path with APP_FILE_PATH and grant permission to overwrite any existing deployments of the application with OVERWRITE set to true.



      - name: SharePoint deploy
        id: deploy
        uses: pnp/action-cli-deploy@v3.0.1
        with:
          APP_FILE_PATH: ./package/example-web-part.sppkg
          OVERWRITE: true

In production, you'd want to replace the hardcoded path and file name with a variable.

The workflow has completed and the custom web part has been deployed to the tenant.

Wrapping up

As I said back at the beginning of this post, this is a basic pipeline. It is a solid foundation to build upon and not much more.

If you're looking for something more advanced, consider:

Integrating the workflow with your project management platform of choice.
Setting up Jest or Enzyme for SPFx unit testing.
Building a SharePoint UAT environment to pre-stage your deployment.

Thanks for reading!

Staying DRY - Writing a Terraform Module

Cole Heard — Sun, 26 Feb 2023 01:05:06 +0000

After writing my Azure Virtual Desktop (AVD) environment in HCL, I knew a few changes would be required before I could use my code in production.

The project was flat and wide - almost every object had its own block of code. Sure, I took advantage of the count argument when it was a clear fit, but most objects still had a 1-to-1 relationship with a resource block.

Writing a module was the obvious solution. A well-written Terraform module can be easily reused, scaled, shared, versioned, and maintained. They are also an excellent tool when building with a DRY design focus.

The DRY (“Don't Repeat Yourself”) principle follows the idea of every logic duplication being eliminated by abstraction. This means that during the development process we should avoid writing repetitive duplicated code as much as possible.

This post will highlight the challenges I encountered while writing the module and the lessons I learned.

Lessons Learned

Mutually Exclusive Arguments
Optional Resource Blocks
Validating Input
Resources with Complicated Relationships
Expiring Timestamps
Adding Workspace Support

Mutually Exclusive Arguments

The first set of resources I targeted were the session hosts.

The backbone of the session host, the virtual machine, may use an Azure Marketplace image in one configuration and a custom Azure Compute Gallery shared image in another.

This was a problem - the arguments for each of these image types are mutually exclusive.

Challenge

Some resource blocks have mutually exclusive arguments.

One argument must be present or provisioning will fail.

The module must support the use of both arguments.

Solution

Using conditional expressions and dynamic blocks, the module can dynamically select one of the arguments and omit the other:

resource "azurerm_windows_virtual_machine" "vm" {
...
 source_image_id = var.managed_image_id
 dynamic "source_image_reference" {
   for_each = var.managed_image_id == null ? ["One loop, please!"] : []
   content {
     publisher = var.market_place_image.publisher
     offer     = var.market_place_image.offer
     sku       = var.market_place_image.sku
     version   = var.market_place_image.version
     }
...
}

If an Azure Compute Gallery image ID was passed to the module, var.managed_image_id would set source_image_id. As var.managed_image_id is not null, the dynamic block would not loop... or if we're being pedantic it would loop 0 times. This functionally omits the source_image_reference argument.

Alternatively, if var.managed_image_id was null (the variable's default) at runtime, the argument would be ignored. As the execution moves to evaluate the dynamic block below, it would find that var.managed_image_id is null and the block will loop once.

This solution isn't perfect - the module will fail to provision if neither argument is made. We need to ensure the block is fed something.

Validation can't be used as validation blocks cannot reference other variables.

As a bandaid, var.market_place_image was given a default value.

variable "managed_image_id" {
 type        = any
 description = "The ID of an Azure Compute Gallery image."
 default     = null
}
variable "market_place_image" {
 type        = map(any)
 description = "The publisher, offer, sku, and version of an image in Azure's market place. Only used if var.custom_image is null."
 default = {
   publisher = "microsoftwindowsdesktop"
   offer     = "windows-10"
   sku       = "win10-22h2-ent"
   version   = "latest"
 }
}

Optional Resource Blocks

I wanted to include support for multiple virtual machine extensions.

The DSC extension is always needed; it installs the AVD agent on the host and configures it interpolated host pool registration token.

The domain join extension and Microsoft monitoring agent extensions, however, are entirely optional.

I needed the module to skip provisioning these resources based on existing variable input.

Challenge

A resources block should not be provisioned if a condition is not met.

Additional module input should be avoided.

Solution

The module can determine if the resource block is needed using conditional expressions, locals, and the count argument.

locals {
 extensions = {
   mmaagent    = var.workspace_id != null ? var.vmcount : 0
 }
}
resource "azurerm_virtual_machine_extension" "mmaagent_ext" {
 count                      = local.extensions.mmaagent
 name                       = "${local.prefix}-${format("%02d", count.index)}-avd_mma"
 virtual_machine_id         = azurerm_windows_virtual_machine.vm.*.id[count.index]
 publisher                  = "Microsoft.EnterpriseCloud.Monitoring"
 type                       = "MicrosoftMonitoringAgent"
 type_handler_version       = "1.0"
 auto_upgrade_minor_version = true
 settings                   = <<SETTINGS
   {
     "workspaceId": "${var.workspace_id}"
   }
SETTINGS
 protected_settings         = <<PROTECTED_SETTINGS
  {
     "workspaceKey": "${var.workspace_key}"
  }
PROTECTED_SETTINGS
}

If we're configuring the pool's session hosts to enroll in our log analytics workspace, we'll pass the module the workspace ID. The conditional expression within local.extensions.mmaagent is set to var.vmcount. An extension is created for every virtual machine in the pool.

If the workspace ID is not set, the conditional expression local.extensions.mmaagent is set to 0. The entire block will be skipped.

Validating Input

As the module's input became increasingly complex, so did the input requirements. It became clear that some input validation was needed - especially if the module was to be shared with others.

Fine-tuned validation can improve a module's ease of use, error checking, and reliability.

Excessive validation can make a module virtually unusable.

A set of variables were identified as perfect candidates for validation - three are highlighted in the solutions below.

Challenge

Some variables have input structure requirements.

Some variables must be limited to avoid errors.

Some variables only accept a small pool of values.

Solution #1

Terraform's validation block can perform custom condition checks.

The int passed to the variable below must be between 0 and 99.

variable "vmcount" {
  type        = number
  description = "The number of VMs requested for this pool."
  default     = 1
  validation {
    condition = (
      var.vmcount >= 0 &&
      var.vmcount <= 99
    )
    error_message = "The number of VMs must be between 0 and 99."
  }
}

In the example below, the lower function is used on the value prior to evaluation.

As the equality operator judges the case of the string, it will not error due to a case mismatch.

variable "load_balancer_type" {
  type        = string
  description = "The method of load balancing the pool with use to distribute users across session hosts."
  default     = "DepthFirst"
  validation {
    condition = anytrue([
      lower(var.load_balancer_type) == "breadthfirst",
      lower(var.load_balancer_type) == "depthfirst",
      lower(var.load_balancer_type) == "persistent"
    ])
    error_message = "The var.load_balancer_type input was incorrect. Please select breadthfirst, depthfirst, or persistent."
  }
}

Solution #2

The Variable's type argument can do more than specify if a variable should be a string, a bool, or a list.

In the example below, var.application_map is expecting an input that is:

A map of objects
The objects each contain four keys named app_name, local_path, cmd_argument, aad_group.
Each of the keys contain a string (or null).

variable "application_map" {
  type = map(object({
    app_name     = string
    local_path   = string
    cmd_argument = string
    aad_group    = string
  }))
  description = "A map of all applications and metadata."
  default     = null
}

Additional Notes

While 99 is not the hard limit, it is a safe number to work with - namely, to avoid NetBIOS name limitations and API throttling.

Remember var.application_map! The data structure will be discussed at length in the next section.

Resources with Complicated Relationships

A pair of resource blocks scale differently. Despite this, our module still needs to correctly tie them together.

Application Groups and Applications share a complicated relationship:

A single application pool can have multiple application groups.
An application group can have many applications.
Each application group in the pool may have a different number of applications assigned.
Permissions are assigned at an Application groups level.

How can the module identify which resources should connect to each other?

How can the module accomplish all of this, while only using the input from var.application_map?

Challenge

Resources should dynamically connect to each other.

The module should support as many configurations as it possibly can.

Additional module input should be avoided.

Solution

We use the shared Azure Active Directory (AAD) groups to assign and collect each application.

By organizing each application under their shared aad_group, we're able to scale both resource blocks independently while retaining the ability to logically join them.

Creating Application Groups

We make a list of each unique aad_group key value with local.aad_group_list.

The local selects the aad_group values and eliminates the duplicates with the distinct function.

locals {
  ...
  aad_group_list = var.application_map != null ? distinct(values({ for k, v in var.application_map : k => v.aad_group })) : ["${var.aad_group_desktop}"]
  ...
}

Then we create each of our application groups using for_each = toset(local.aad_group_list).

resource "azurerm_virtual_desktop_application_group" "app_group" {
  ...
  for_each            = toset(local.aad_group_list)
  ...
}

The module will produce one application group for every unique AAD group reference.

Creating Applications

The application block, looping through the unaltered list of application objects, inserts the aad_group key value into application_group_id.

resource "azurerm_virtual_desktop_application" "application" {
  ...
  for_each                     = local.applications # In this example, this local resolves to var.application_map. See additional notes for more info.
  name                         = replace(each.value["app_name"], " ", "")
  friendly_name                = each.value["app_name"]
  application_group_id         = azurerm_virtual_desktop_application_group.app_group[each.value["aad_group"]].id
  path                         = each.value["local_path"]
  command_line_argument_policy = each.value["cmd_argument"] == null ? "DoNotAllow" : "Require"
  command_line_arguments       = each.value["cmd_argument"]
  ...
}

The application has successfully recreated the resource address of the correct application group.

In short - every application will be assigned to the application group with a matching AAD group.

Additional Notes

Desktop pools do not require "applications". The desktop application group inherently provides the "Remote Desktop" application to all assigned members.

Local.applications will pass var.appliction_map unless it is null. If it is null, we must pass an empty map instead - null cannot be given to the for_each argument.

locals {
 applications   = var.application_map != null ? var.application_map : tomap({}) # Null is not accepted as for_each value, substituting for an empty map if null.
}

Expiring Timestamps

The last section was heavy - this one is a palate cleanser.

While working on this module, I needed to manually update the registration token's RF3339 timestamp several times.

I'm not updating it myself any longer - Terraform functions can handle it.

Challenge

A timestamp is needed to generate a token.

The token should expire as soon as possible after resources are provisioned.

No manual intervention at run time is permitted.

Solution

The RF3339 timestamp is updated each time we plan or apply. The module leverages two simple Terraform functions:
timestamp and timeadd to generate a valid, formatted timestamp.

resource "azurerm_virtual_desktop_host_pool_registration_info" "token" {
 hostpool_id     = azurerm_virtual_desktop_host_pool.pool.id
 expiration_date = timeadd(timestamp(), "2h")
}
locals {
 token = azurerm_virtual_desktop_host_pool_registration_info.token.token
}

The newly created token is passed to a local, local.token, that the vm_dsc_ext block will reference later.

resource "azurerm_virtual_machine_extension" "vm_dsc_ext" {
  ...
  settings                   = <<-SETTINGS
    {
      "modulesUrl": "https://wvdportalstorageblob.blob.core.windows.net/galleryartifacts/Configuration_09-08-2022.zip",
      "configurationFunction": "Configuration.ps1\\AddSessionHost",
      "properties": {
        "HostPoolName":"${azurerm_virtual_desktop_host_pool.pool.name}"
      }
    }
SETTINGS
  protected_settings         = <<PROTECTED_SETTINGS
  {
    "properties": {
      "registrationInfoToken": "${local.token}"
    }
  }
PROTECTED_SETTINGS
 ...
}

Adding Workspace Support

Terraform Workspaces are used to redeploy existing code by creating a new statefile.

Terraform workspaces can be used to mirror one subscription's infrastructure into another. They can also programmatically enforce other changes - the production workspace and the development workspace may be configured to use a different default VM size.

Resources created by the module should clearly indicate their associated workspace.

Challenge

Resource names should indicate the workspace.

The resource should be tagged with the workspace name.

Solution

Using a series of conditional expressions and the coalesce function, Terraform will identify the workspace and select a three letter abbreviation to concat in the resource naming scheme.

The module runs through the list of possible workspace names, checking each against a conditional expression.

If the workspace name matches the conditional expression, the local is set to the conditional expression's true condition value (e.g. PRD).
If the conditional expression resolves to false, the local is set to an empty string. All the locals are fed to coalesce. The function returns the first value in the index that is not an empty string.

locals {
 production_workspace  = terraform.workspace == "default" ? "PRD" : ""
 development_workspace = terraform.workspace == "development" ? "DEV" : ""
 uat_workspace         = terraform.workspace == "uat" ? "UAT" : ""
 other_workspace       = terraform.workspace != "default" && terraform.workspace != "development" && terraform.workspace != "uat" ? "TST" : ""
 workspace_prefix      = coalesce(local.production_workspace, local.development_workspace, local.uat_workspace, local.other_workspace)
}

The module will also tag the resources with it's workspace.

locals {
  tags = {
    ...
    Status = terraform.workspace == "default" ? "Production" : "${terraform.workspace}"
    ...
  }
}

The Completed Module

I now have a working module! If you'd like to see how all the code fits together, visit my GitHub repo.

This post was focused on the module's code. Before I uploaded it to the Terraform Registry, I performed other tasks that were outside the scope of this post. Highlights include automated documentation with Terraform-Docs, the inclusion of OOS licensing, and creating a release tag in GitHub.

The code snippet below calls the module from the Terraform Registry. The example module is based on application pool described in Resources with Complicated Relationships.

module "example" {
 # Required Input
 source       = "ColeHeard/avd/azurerm"
 version      = "1.0.0"
 pool_type    = "application"
 rg           = azurerm_resource_group.main_rg.id
 region       = var.region
 local_admin  = var.local_admin
 local_pass   = var.local_pass
 network_data = data.azurerm_subnet.network
 # Optional Input
 application_map          = merge(var.red_app, var.blue_app, var.yellow_app)
 managed_image_id         = data.azurerm_shared_image_version.custom_image
 custom_rdp_properties    = var.rdp_app_streaming
 domain                   = var.domain
 domain_user              = var.domain_user
 domain_pass              = var.domain_pass
 workspace_id             = var.workspace_id
 workspace_key            = var.workspace_key
 vmsize                   = "Standard_D8as_v4"
 vmcount                  = 10
 maximum_sessions_allowed = 7
}

Thanks for reading!

DEV Community: Cole Heard

Input Validation - Terraform Tips & Tricks

Table of Contents

Structured Types

Validation Block

Going Further with Functions

Adding For Expressions

Wrapping Up

GitHub Actions - Automated Terraform-docs

The Workflow

Repo clone

Generating documentation

Action arguments

Markdown formatting

Resulting output

Premerge Review

Echoing contents

Escape characters

Multiline strings

Pull request comment

Wrapping up

GitHub Actions - Azure Terraform CI/CD

Prerequisites

The Workflow

Getting Started

Azure Authentication

Access to Private Repositories

Terraform Prep

Checkov

More Terraform

Checking the Plan

Pull Request Comment

Terraform Apply

Wrapping up

GitHub Actions - SharePoint Framework CI/CD

Why write SPFx web parts?

Azure Active Directory prerequisites

Service Account

Conditional Access

Application Consent

Pipeline walkthrough

Workflow triggers

Running the job

Setup steps

Deployment steps

Wrapping up

Staying DRY - Writing a Terraform Module

Lessons Learned

Mutually Exclusive Arguments

Challenge

Solution

Optional Resource Blocks

Challenge

Solution

Validating Input

Challenge

Solution #1

Solution #2

Additional Notes

Resources with Complicated Relationships

Challenge

Solution

Creating Application Groups

Creating Applications

Additional Notes

Expiring Timestamps

Challenge

Solution

Adding Workspace Support

Challenge

Solution

The Completed Module