From 030dd4e5d9a754e15d1c432f88c2985d4b2d5c5f Mon Sep 17 00:00:00 2001 From: Stijn Moreels <9039753+stijnmoreels@users.noreply.github.com> Date: Wed, 6 Apr 2022 13:34:58 +0200 Subject: [PATCH] fix: update with remaining v0.6 feature docs (#292) * fix: update with remaining v0.6 feature docs * pr-fix: update with links to new management module on index page --- docs/preview/01-index.md | 1 + .../versioned_docs/version-v0.6.0/01-index.md | 1 + .../02-Features/powershell/arm.md | 2 + .../02-Features/powershell/azure-devops.md | 67 ++++++++++++++++- .../powershell/azure-management.md | 73 +++++++++++++++++++ 5 files changed, 140 insertions(+), 4 deletions(-) create mode 100644 docs/versioned_docs/version-v0.6.0/02-Features/powershell/azure-management.md diff --git a/docs/preview/01-index.md b/docs/preview/01-index.md index cb361423..d5caca6e 100644 --- a/docs/preview/01-index.md +++ b/docs/preview/01-index.md @@ -25,6 +25,7 @@ For more granular packages we recommend reading the documentation. * Automate Azure Integration Account tasks ([powershell](./02-Features/powershell/azure-integration-account.md)) * Automate Azure Key Vault tasks ([powershell](./02-Features/powershell/azure-key-vault.md)) * Automate Azure Logic Apps tasks ([powershell](./02-Features/powershell/azure-logic-apps.md)) +* Automate Azure Management tasks ([powershell](./02-Features/powershell/azure-management.md)) * Automate Azure Resource Manager (ARM) tasks ([powershell](./02-Features/powershell/arm.md)) * Automate Azure Security tasks ([powershell](./02-Features/powershell/azure-security.md)) * Automate Azure SQL tasks ([powershell](./02-Features/powershell/azure-sql.md)) diff --git a/docs/versioned_docs/version-v0.6.0/01-index.md b/docs/versioned_docs/version-v0.6.0/01-index.md index cb361423..d5caca6e 100644 --- a/docs/versioned_docs/version-v0.6.0/01-index.md +++ b/docs/versioned_docs/version-v0.6.0/01-index.md @@ -25,6 +25,7 @@ For more granular packages we recommend reading the documentation. * Automate Azure Integration Account tasks ([powershell](./02-Features/powershell/azure-integration-account.md)) * Automate Azure Key Vault tasks ([powershell](./02-Features/powershell/azure-key-vault.md)) * Automate Azure Logic Apps tasks ([powershell](./02-Features/powershell/azure-logic-apps.md)) +* Automate Azure Management tasks ([powershell](./02-Features/powershell/azure-management.md)) * Automate Azure Resource Manager (ARM) tasks ([powershell](./02-Features/powershell/arm.md)) * Automate Azure Security tasks ([powershell](./02-Features/powershell/azure-security.md)) * Automate Azure SQL tasks ([powershell](./02-Features/powershell/azure-sql.md)) diff --git a/docs/versioned_docs/version-v0.6.0/02-Features/powershell/arm.md b/docs/versioned_docs/version-v0.6.0/02-Features/powershell/arm.md index 48bf4aca..11da013c 100644 --- a/docs/versioned_docs/version-v0.6.0/02-Features/powershell/arm.md +++ b/docs/versioned_docs/version-v0.6.0/02-Features/powershell/arm.md @@ -70,10 +70,12 @@ It is possible to supply injection instructions in the injection annotation, thi | `InjectAsJsonObject` | Tests if the content is valid JSON and makes sure the content is injected without surrounding double quotes | Usage of multiple injection instructions is supported as well, for example if you need both the `EscapeJson` and `ReplaceSpecialChars` functionality. +The reference to the file to inject can either be a path relative to the 'parent' file or an absolute path. Some examples are: ```powershell ${ FileToInject = ".\Parent Directory\file.xml" } +${ FileToInject = "c:\Parent Directory\file.xml" } ${ FileToInject = ".\Parent Directory\file.xml", EscapeJson, ReplaceSpecialChars } ${ FileToInject = '.\Parent Directory\file.json', InjectAsJsonObject } ``` diff --git a/docs/versioned_docs/version-v0.6.0/02-Features/powershell/azure-devops.md b/docs/versioned_docs/version-v0.6.0/02-Features/powershell/azure-devops.md index 0f04cadd..545b63cf 100644 --- a/docs/versioned_docs/version-v0.6.0/02-Features/powershell/azure-devops.md +++ b/docs/versioned_docs/version-v0.6.0/02-Features/powershell/azure-devops.md @@ -19,7 +19,8 @@ This module provides the following capabilities: To have access to the following features, you have to import the module: ```powershell -PS> Install-Module -Name Arcus.Scripting.DevOps +PS> Set-PSRepository -Name PSGallery -InstallationPolicy Trusted +PS> Install-Module -Name Arcus.Scripting.DevOps -Repository PSGallery -AllowClobber ``` ## Setting a variable in an Azure DevOps pipeline @@ -49,6 +50,7 @@ Stores the Azure Resource Management (ARM) outputs in a variable group on Azure | `UpdateVariablesForCurrentJob` | no | The switch to also set the variables in the ARM output as pipeline variables in the current running job | **Example** + Without updating the variables in the current job running the pipeline: ```powershell @@ -82,6 +84,37 @@ PS> Set-AzDevOpsArmOutputsToVariableGroup -VariableGroupName "my-variable-group" # The pipeline variable $variableName will be updated to value $variableValue as well, so it can be used in subsequent tasks of the current job. ``` +**Azure DevOps Example** +This function is intended to be used from an Azure DevOps pipeline. Internally, it uses some predefined Azure DevOps variables. +One of the environment variables that is used, is the `SYSTEM_ACCESSTOKEN` variable. However, due to safety reasons this variable is not available out-of-the box. +To be able to use this variable, it must be explicitly added to the environment-variables. + +> ⚠ When you are using a Linux agent, you need to pass other environment variables that you want to use as well, because these are not available. To be able to use the `ArmOutputs` environment variable, it must be explicitly added to the environment-variables. + +> 💡 We have seen a much better performance when using Linux agents, and would recommend using Linux agents when possible. + +Example of how to use this function in an Azure DevOps pipeline: + +```yaml +- task: PowerShell@2 + displayName: 'Promote Azure resource outputs to variable group' + env: + SYSTEM_ACCESSTOKEN: $(System.AccessToken) + ArmOutputs: $(ArmOutputs) # only needs to be set for Linux agents + inputs: + targetType: 'inline' + script: | + Set-PSRepository -Name PSGallery -InstallationPolicy Trusted + Install-Module -Name Arcus.Scripting.DevOps -Repository PSGallery -AllowClobber + + Set-AzDevOpsArmOutputsToVariableGroup -VariableGroupName "my-variable-group" +``` + +In Azure DevOps, below permissions need to be set on your variable group in order to make the 'Promote Azure resource outputs to variable group' task succeed. For more information on service accounts, see [the official Azure DevOps documentation](https://docs.microsoft.com/en-us/azure/devops/organizations/security/permissions?view=azure-devops&tabs=preview-page#service-accounts). + +- Project Collection Build Service (``) - Administrator +- `` Build Service (``) - Administrator + ## Setting ARM outputs to Azure DevOps pipeline variables Sets the ARM outputs as variables to an Azure DevOps pipeline during the execution of the pipeline. @@ -91,6 +124,7 @@ Sets the ARM outputs as variables to an Azure DevOps pipeline during the executi | `ArmOutputsEnvironmentVariableName` | no | The name of the environment variable where the ARM outputs are located (default: `ArmOutputs`) | **Example** + With default `ArmOutputs` environment variable containing: `"my-variable": "my-value"`: ```powershell @@ -109,6 +143,29 @@ PS> Set-AzDevOpsArmOutputsToPipelineVariables -ArmOutputsEnvironmentVariableName # ##vso[task.setvariable variable=my-variable]my-value ``` +**Azure DevOps Example** +This function is intended to be used from an Azure DevOps pipeline. + +> ⚠ When you are using a Linux agent, you need to pass other environment variables that you want to use as well, because these are not available. To be able to use the `ArmOutputs` environment variable, it must be explicitly added to the environment-variables. + +> 💡 We have seen a much better performance when using Linux agents, and would recommend using Linux agents when possible. + +Example of how to use this function in an Azure DevOps pipeline: + +```yaml +- task: PowerShell@2 + displayName: 'Promote Azure resource outputs to pipeline variables' + env: + ArmOutputs: $(ArmOutputs) # only needs to be set for Linux agents + inputs: + targetType: 'inline' + script: | + Set-PSRepository -Name PSGallery -InstallationPolicy Trusted + Install-Module -Name Arcus.Scripting.DevOps -Repository PSGallery -AllowClobber + + Set-AzDevOpsArmOutputsToPipelineVariables +``` + ## Save Azure DevOps build Saves/retains a specific Azure DevOps pipeline run. @@ -126,8 +183,9 @@ PS> Save-AzDevOpsBuild -ProjectId $(System.TeamProjectId) -BuildId $(Build.Build # Information on them can be found here: https://docs.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml ``` -This function is intended to be used from an Azure DevOps pipeline. Internally, it uses some predefined Azure DevOps variables. -One of the environment variables that is used, is the the `SYSTEM_ACCESSTOKEN` variable. However, due to safety reasons this variable is not available out-of-the box. +**Azure DevOps Example** +This function is intended to be used from an Azure DevOps pipeline. Internally, it uses some predefined Azure DevOps variables. +One of the environment variables that is used, is the `SYSTEM_ACCESSTOKEN` variable. However, due to safety reasons this variable is not available out-of-the box. To be able to use this variable, it must be explicitly added to the environment-variables. Example of how to use this function in an Azure DevOps pipeline: @@ -141,7 +199,8 @@ Example of how to use this function in an Azure DevOps pipeline: targetType: 'inline' pwsh: true script: | - Install-Module -Name Arcus.Scripting.DevOps -Force + Set-PSRepository -Name PSGallery -InstallationPolicy Trusted + Install-Module -Name Arcus.Scripting.DevOps -Repository PSGallery -AllowClobber $project = "$(System.TeamProjectId)" $buildId = $(Build.BuildId) diff --git a/docs/versioned_docs/version-v0.6.0/02-Features/powershell/azure-management.md b/docs/versioned_docs/version-v0.6.0/02-Features/powershell/azure-management.md new file mode 100644 index 00000000..69cf5e5f --- /dev/null +++ b/docs/versioned_docs/version-v0.6.0/02-Features/powershell/azure-management.md @@ -0,0 +1,73 @@ + +--- +title: "Azure Management" +layout: default +--- + +# Azure Management + +This module provides the following capabilities: +- [Azure Management](#azure-management) + - [Installation](#installation) + - [Removing a soft deleted API Management instance](#removing-a-soft-deleted-api-management-instance) + - [Restoring a soft deleted API Management instance](#restoring-a-soft-deleted-api-management-instance) + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +PS> Install-Module -Name Arcus.Scripting.Management +``` + +## Removing a soft deleted API Management instance + +Removes a soft deleted API Management instance. +For more information on API Management and soft deletion see [here](https://docs.microsoft.com/en-us/azure/api-management/soft-delete#soft-delete-behavior). + +| Parameter | Mandatory | Description | +| ---------------- | --------- | ---------------------------------------------------------------------------------------------------------- | +| `Name` | yes | The name of the API Management instance that has been soft deleted. | +| `SubscriptionId` | no | The Id of the subscription containing the Azure API Management instance. | +| | | When not provided, it will be retrieved from the current context (Get-AzContext). | +| `EnvironmentName`| no | The name of the Azure environment where the Azure API Management instance resides. (default: `AzureCloud`) | +| `AccessToken` | no | The access token to be used to remove the Azure API Management instance. | +| | | When not provided, it will be retrieved from the current context (Get-AzContext). | +| `ApiVersion ` | no | The version of the management API to be used. (default: `2021-08-01`) | + +> :bulb: The `ApiVersion` has successfully been tested with version `2021-08-01`. + +**Example** +```powershell +PS> Remove-AzApiManagementSoftDeletedService -Name "my-apim" +# Checking if the API Management instance with name 'my-apim' is listed as a soft deleted service +# API Management instance has been found for name 'my-apim' as a soft deleted service +# Removing the soft deleted API Management instance 'my-apim' +# Successfully removed the soft deleted API Management instance 'my-apim' +``` + +## Restoring a soft deleted API Management instance + +Restores a soft deleted API Management instance. +For more information on API Management and soft deletion see [here](https://docs.microsoft.com/en-us/azure/api-management/soft-delete#soft-delete-behavior). + +| Parameter | Mandatory | Description | +| ---------------- | --------- | ---------------------------------------------------------------------------------------------------------- | +| `Name` | yes | The name of the API Management instance that has been soft deleted. | +| `SubscriptionId` | no | The Id of the subscription containing the Azure API Management instance. | +| | | When not provided, it will be retrieved from the current context (Get-AzContext). | +| `EnvironmentName`| no | The name of the Azure environment where the Azure API Management instance resides. (default: `AzureCloud`) | +| `AccessToken` | no | The access token to be used to restore the Azure API Management instance. | +| | | When not provided, it will be retrieved from the current context (Get-AzContext). | +| `ApiVersion ` | no | The version of the management API to be used. (default: `2021-08-01`) | + +> :bulb: The `ApiVersion` has successfully been tested with version `2021-08-01`. + +**Example** +```powershell +PS> Restore-AzApiManagementSoftDeletedService -Name "my-apim" +# Checking if the API Management instance with name 'my-apim' is listed as a soft deleted service +# API Management instance has been found for name 'my-apim' as a soft deleted service +# Restoring the soft deleted API Management instance 'my-apim' +# Successfully restored the soft deleted API Management instance 'my-apim' +```