Skip to content

Latest commit

 

History

History
115 lines (81 loc) · 4.47 KB

InfrastructureAutomation.md

File metadata and controls

115 lines (81 loc) · 4.47 KB
Raw

Infrastructure Automation

Modules

The modules folder contains functions that are shared between scripts in the Resources folder. Functions should generally be grouped by type. For example, all Azure based custom functions should be in Azure.psm1.

Resources

The resources folder contains scripts that carry out Azure infrastructure operations. These scripts can be consumed by VSTS release definitions or executed locally.

Code and design guidelines

When writing a script or a helper function keep in mind that it:

  • Should have an acceptance test
  • Should work locally and on build agents
  • Should contain appropriate documentation
  • Should use Write-Log for logging (See the logging section for more information)
  • Should use the PascalCasing convention for variables
  • Should not mix Service Manager(ASM) and Resource Manager(ARM) operations
  • Should contain functions that follow the Verb-Noun and PascalCasing conventions (For a list of acceptable verbs use Get-Verb)
  • Should contain descriptive inline comments
  • Should avoid using aliases for built-in functions
  • Should not generate any errors from PSScriptAnalyzers **

** In the case that exceptions must be made, you should use the SuppressMessageAttribute() decorator and add a .NOTES section to the help with justification.

Example

[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingConvertToSecureStringWithPlainText", "")]
[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]

For more information, see the PSScriptAnalyzer readme.

Documentation

Scripts and functions should contain comment based help that is compatible with Get-Help.

The help should consist of the following elements:

  • Synopsis
  • Description
  • A parameter description for each parameter in the Param() block
  • At least one example demonstrating how the script can be executed

For further information see about_Comment_Based_Help

Example

<#

.SYNOPSIS
Move a Resource to a new Resource Group

.DESCRIPTION
Move one or more resources to a new Resource Group and remove their source Resource Groups

.PARAMETER ResourceName
The names of one or more resources to move

.PARAMETER DestinationResourceGroup
The name of the destination Resource Group

.EXAMPLE
.\Move-Resource.ps1 -ResourceName cloud-service-01 -DestinationResourceGroup arm-rg-01

.EXAMPLE
.\Move-Resource.ps1 -ResourceName cloud-service-01,cloud-service-02 -DestinationResourceGroup arm-rg-01

#>

Common parameters

The majority of Azure functions will require the user to specify the Location and Resource Group where the resource will reside.

If this is the case for a script you are writing, these parameters should be exposed in the Param() block as non mandatory parameters and follow these guidelines.

The parameter names should be consistent across the script library.

Location

  • Should be limited with ValidateSet() to West Europe and North Europe
  • Should have a default value of $Env:Location

ResourceGroupName

  • Should have a default value of $Env:ResourceGroup

Example

Param(
    [Parameter(Mandatory = $false)]
    [ValidateSet("West Europe", "North Europe")]
    [String]$Location = $ENV:Location,
    [Parameter(Mandatory = $false)]
    [ValidateNotNullOrEmpty()]
    [String]$ResourceGroupName = $ENV:ResourceGroup    
)

Logging

When logging in a script you should use Write-Log from the helper functions module (Modules\Helpers.ps1).

There are four log levels that you can use; Information, Warning, Verbose and Error. For example:

Write-Log -LogLevel Information -Message "An informational message"

Write-Log -LogLevel Warning -Message "A warning message"

Write-Log -LogLevel Verbose -Message "A verbose message"

Write-Log -LogLevel Error -Message "An error message"

Running scripts in VSTS build and release definitions

When running scripts in VSTS you should use the built in Azure PowerShell task. This task allows you to make use of pre configured Service Endpoints and therefore keep scripts clear of any hard coded authentication variables.

Scripts can be grouped together using Task Groups and if applicable, reused across environments and definitions. This allows for reuse of common parameters across scripts and better organisation within the definition.