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
arcus-azure · Apr 6, 2022 · 030dd4e · 030dd4e
1 parent 8f458ab
commit 030dd4e
Show file tree

Hide file tree

Showing 5 changed files with 140 additions and 4 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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 (`<your devops org name>`) - Administrator
+- `<your devops project name>` Build Service (`<your devops org name>`) - 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
@@ -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'
+```