Getting Started

Welcome to AzureStack Powershell repository!

The repo holds the modules for the AzureStack Hub operator persona. The Azurestack hub admin APIs are exposed as powershell via this repo

Most of the modules are generated with the autorest tool (https://github.com/Azure/autorest.powershell) and some modules are hand written.

Contents

/src folder

This is for source of all the admin api modules. This could also contain the helper cmdlets over azurestack/azure integration For many of the modules only the metadata configuration files would be present as the modules are generated as described in the following sections

/tools folder

This contains files that are essential for devops pipelines and security scans

/docs folder

This contains the migration guides and general information docs

Dev Setup

Prerequisites

1. Install NodeJs: https://nodejs.org/ (recommended v10, https://nodejs.org/download/release/v10.15.3/) a. Please do make sure that you have the recommended version. The latest seems to have issues in generation
2. install new autorest beta packge:

npm install -g autorest 

3. Install PS core:

npm install -g pwsh

4. Install .net core:

npm install -g dotnet-sdk-2.2

Build

1. Go to module directory, e.g. src/Azs.Network.Admin
2. Run:
   • autorest
   • pwsh
   • .\build-module.ps1
3. All generated cmdlets will be inside 'exports' folder
4. The module can be imported using the 'Azs..Admin.psd1' (e.g. Azs.Network.Admin.psd1) from the module directory

Generating PowerShell with local open API file

The powershell generation could point to a local file path instead of the github repo path For example to generate Azs.Network.Admin module pointing to the local file path edit the readme.md for the following lines

require:
  - $(this-folder)/../readme.azurestack.md
  - D:\github\azure-rest-api-specs\specification\azsadmin\resource-manager\network\readme.md

Manual validations

Without doing any customizations mentioned below, the generated cmdlets can be verified.

AzureStack One node environment is enough to validate the module manually
After doing .\build-module.ps1, Copy the entire folder contents to a one node azurestack environment. In the environment DVM/host, Install the following modules. These modules are needed in the development box as well when the recorded tests are played back.

The following are the needed versions of Az.Accounts and Az.Resources modules
Az.Accounts - 2.2.8
Az.Resources - 0.12.0
Please make sure to uninstall the existing versions of azure powershell following the uninstall instructions at https://aka.ms/azspsh

Install-Module Az.Accounts -RequiredVersion 2.2.8
Install-Module Az.Resources -RequiredVersion 0.12.0
Import-Module Az.Accounts
Import-Module Az.Resources
Enable-AzContextAutosave

Enabling Context Autosave with Enable-AzContextAutosave is required for the Pester Tests

Import the newly generated module . Login to the azurestack environment with the following script and try the changed cmdlets for manual validation

# Assumption - BVTs are already run on the DVM
[XML]$BVTSettings = Get-Content "C:\CloudDeployment\BVTs\BVTSettings.xml"
function Get-Setting ([string]$parameter){
    return ($BVTSettings.Settings.Setting | Where Name -eq $parameter).'#text'
}
Add-AzEnvironment -Name AzureStack -ARMEndpoint (Get-Setting "ARMEndpoint")
$creds = New-Object PSCredential((Get-Setting "ServiceAdminUpn"), (ConvertTo-SecureString -String (Get-Setting "ServiceAdminPassword") -AsPlainText -Force))
Login-AzAccount -Environment AzureStack -Tenant (Get-Setting "AADTenantID") -Credential $creds

### Customizations:
The docs for customization can be found under https://github.com/Azure/autorest.powershell/tree/master/docs
* Input specs files: declare it inside the readme.md file in the azure-rest-api-specs  repo using input-file cmd
e.g. 
``` yaml
input-file:
    - "$(this-folder)/Microsoft.Network.Admin/preview/2015-06-15/Network.json"
    - "$(this-folder)/Microsoft.Network.Admin/preview/2015-06-15/LoadBalancers.json"
    - "$(this-folder)/Microsoft.Network.Admin/preview/2015-06-15/PublicIpAddresses.json" 
    - "$(this-folder)/Microsoft.Network.Admin/preview/2015-06-15/Quotas.json"
    - "$(this-folder)/Microsoft.Network.Admin/preview/2015-06-15/VirtualNetworks.json"

• Include the above file in the azure-powershell module directory's readme.md file using require cmd

require:
  - $(repo)/specification/azsadmin/resource-manager/network/readme.md

$(repo) and other common settings are defined in the file

• Directives: Built-in Directives support renaming cmdlets/parameters/properties of models, adding alias, setting default value, etc. These are declared in readme.md and would take effect for the generated module. Refer to https://github.com/Azure/autorest/blob/master/docs/powershell/directives.md for the supported directives. Example: https://github.com/Azure/azure-powershell/blob/stackadmin/src/StackAdmin/Azs.Network.Admin/readme.md i. Removing InputObject parameter from the New-* cmdlet ## variant removal (parameter InputObject) from all New cmdlets -- parameter sets CreateViaIdentity and CreateViaIdentityExpanded

  • where: verb: New variant: ^CreateViaIdentity(.*) remove: true

• Customization: For other customizations that directives do not support, use customization instead. Refer to https://github.com/Azure/autorest/blob/master/docs/powershell/customization.md for full instruction. A simple example is to change the param type from String to SecureString, to achieve this:

  1. Hide the cmdlet in md so that the original param with String type won't conflict with the SecureString param with same name;
  2. Generate the module and copy the .ps1 file from internal folder to custom folder;
  3. Edit the copied .ps1 file to do the customization. Change the param type to SecureString, and convert to plaintext inside cmdlet, replace the PSBoundParameters with the converted value;
  4. Call the internal cmdlet with the updated PSBoundParameters https://github.com/azure/azurestack-powershell/blob/master/src/Azs.Backup.Admin/custom/Set-AzsBackupConfiguration.ps1

Tests

Configuration

The following introduces how properties of the Azure Stack environment can be passed to the pester tests through configuration of several files.

env.json

The env.json file holds environment parameters. The parameter values in this file must be consistent with the values in the recording file. If they are not, you should replace the ones in the recording files with the parameters from the env.json or vice versa depending on which is more convenient.

{
    "Tenant": "11111111-1111-1111-1111-111111111111",
    "SubscriptionId": "11111111-1111-1111-1111-111111111111",
    "ResourceGroup": "MyResourceGroup",
    "Location": "Earth"
}

loadEnv.ps1

The loadEnv.ps1 file loads the env.json into $env hash table that is accessible in the current session of the calling script. This script is auto-generated by autorest. The $PSDefaultParameterValues will automatically pass certain parameters for your commands in the tests. DO NOT rely on this behavior as we do not have control over the contents of $PSDefaultParameterValues, which does not cover all properties set in env.json. Instead, simply use $env object to access your parameter values that the file loads from your env.json file, which is guaranteed to have all properties from your env.json file.

$envFile = 'env.json'
Write-Host "Loading env.json"
if ($TestMode -eq 'live') {
    $envFile = 'localEnv.json'
}

# Find the env.json file
if (Test-Path -Path (Join-Path $PSScriptRoot $envFile)) {
    $envFilePath = Join-Path $PSScriptRoot $envFile
} else {
    $envFilePath = Join-Path $PSScriptRoot '..\$envFile'
}
# Create $env for env.json file. Access $env from calling script to access env.json parameter values.
$env = @{}
if (Test-Path -Path $envFilePath) {
    # Convert env.json from json to powershell object.
    $env = Get-Content (Join-Path $PSScriptRoot $envFile) | ConvertFrom-Json
    $PSDefaultParameterValues=@{"*:SubscriptionId"=$env.SubscriptionId; "*:Tenant"=$env.Tenant}
}

MyTest.Tests.ps1

Sample test calling loadEnv.ps1 to load env.json into variable $env. Access parameters like Location using $env.Location. Autorest generates these test stubs containing the initial env.json loading and mocking code, as well as skeletons of test code during build-module.ps1.

# Load the env.json file by running loadEnv.ps1
$loadEnvPath = Join-Path $PSScriptRoot 'loadEnv.ps1'
if (-Not (Test-Path -Path $loadEnvPath)) {
    $loadEnvPath = Join-Path $PSScriptRoot '..\loadEnv.ps1'
}
. ($loadEnvPath)

$TestRecordingFile = Join-Path $PSScriptRoot 'MyTest.Recording.json'
$currentPath = $PSScriptRoot
while(-not $mockingPath) {
    $mockingPath = Get-ChildItem -Path $currentPath -Recurse -Include 'HttpPipelineMocking.ps1' -File
    $currentPath = Split-Path -Path $currentPath -Parent
}
. ($mockingPath | Select-Object -First 1).FullName

Describe "Tests" -Tags @('tag1', 'tag2') {
    # Loads a common file containing common features for tests, including an array of tests to skip, shared variables, and common functions.
    . $PSScriptRoot\Common.ps1

    # Run the test, unless it is in list of $global:SkippedTests instantiated in Common.ps1.
    It "MyTest" -Skip:$('MyTest' -in $global:SkippedTests) {
        Write-Host "My Azure location: $($env.Location)"
    }
}

Examples and Docs

Autorest generates examples folder and docs folder with templated contents. The developer has to add examples with sample output for each cmdlet.
Run generate-help.ps1 file , it will import the examples in to the files in the Docs folder. The docs folder need not be edited manually

Official Autorest Documentation

Pester tests are required to make sure that cmdlets are validated against a live azurestack environment. Also to make sure that the future changes are not breaking the cmdlets. We follow the record and playback framework used by the azure powershell team. The docs for authoring the tests can be found at the following wiki: https://github.com/Azure/azure-powershell/wiki/How-to-On-Board-New-RP-with-Azure-PowerShell-Generator#test