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 v14.17.0 plus )
2. install new autorest beta package:

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

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.11.0

Install-Module Az.Accounts -RequiredVersion 2.2.8
Install-Module Az.Resources -RequiredVersion 0.11.0
Import-Module Az.Accounts
Import-Module Az.Resources

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 cusotmizations 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.

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

The tests are written with Pester framework. Pester tests are required to make sure that cmdlets are validated against a live AzureStack Hub 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

Note - Azure powershell team continuously improves/changes the steps needed for recording the tests frequently change

• Make sure each test file contains the below code to load env vars.

$loadEnvPath = Join-Path $PSScriptRoot 'loadEnv.ps1'
if (-Not (Test-Path -Path $loadEnvPath)) {
    `$loadEnvPath = Join-Path $PSScriptRoot '..\loadEnv.ps1'
}
. ($loadEnvPath)

• From the test recordings, find the values for below variables and other required parameters that the test would require and add it to env.json under test folder, example:

{
    "Tenant": "018xxx92-6d96-44fa-8c58-xxxx",
    "SubscriptionId": "xxx-4ace-4ffa-844e-xxx",
    "ResourceGroup": "testrg",
    "Location": "redmond"
}