Skip to content

Commit 030dd4e

Browse files
stijnmoreelsstijnmoreels
authored
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
1 parent 8f458ab commit 030dd4e

5 files changed

Lines changed: 140 additions & 4 deletions

File tree

‎docs/preview/01-index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ For more granular packages we recommend reading the documentation.
2525
* Automate Azure Integration Account tasks ([powershell](./02-Features/powershell/azure-integration-account.md))
2626
* Automate Azure Key Vault tasks ([powershell](./02-Features/powershell/azure-key-vault.md))
2727
* Automate Azure Logic Apps tasks ([powershell](./02-Features/powershell/azure-logic-apps.md))
28+
* Automate Azure Management tasks ([powershell](./02-Features/powershell/azure-management.md))
2829
* Automate Azure Resource Manager (ARM) tasks ([powershell](./02-Features/powershell/arm.md))
2930
* Automate Azure Security tasks ([powershell](./02-Features/powershell/azure-security.md))
3031
* Automate Azure SQL tasks ([powershell](./02-Features/powershell/azure-sql.md))

‎docs/versioned_docs/version-v0.6.0/01-index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ For more granular packages we recommend reading the documentation.
2525
* Automate Azure Integration Account tasks ([powershell](./02-Features/powershell/azure-integration-account.md))
2626
* Automate Azure Key Vault tasks ([powershell](./02-Features/powershell/azure-key-vault.md))
2727
* Automate Azure Logic Apps tasks ([powershell](./02-Features/powershell/azure-logic-apps.md))
28+
* Automate Azure Management tasks ([powershell](./02-Features/powershell/azure-management.md))
2829
* Automate Azure Resource Manager (ARM) tasks ([powershell](./02-Features/powershell/arm.md))
2930
* Automate Azure Security tasks ([powershell](./02-Features/powershell/azure-security.md))
3031
* Automate Azure SQL tasks ([powershell](./02-Features/powershell/azure-sql.md))

‎docs/versioned_docs/version-v0.6.0/02-Features/powershell/arm.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,10 +70,12 @@ It is possible to supply injection instructions in the injection annotation, thi
7070
| `InjectAsJsonObject` | Tests if the content is valid JSON and makes sure the content is injected without surrounding double quotes |
7171

7272
Usage of multiple injection instructions is supported as well, for example if you need both the `EscapeJson` and `ReplaceSpecialChars` functionality.
73+
The reference to the file to inject can either be a path relative to the 'parent' file or an absolute path.
7374

7475
Some examples are:
7576
```powershell
7677
${ FileToInject = ".\Parent Directory\file.xml" }
78+
${ FileToInject = "c:\Parent Directory\file.xml" }
7779
${ FileToInject = ".\Parent Directory\file.xml", EscapeJson, ReplaceSpecialChars }
7880
${ FileToInject = '.\Parent Directory\file.json', InjectAsJsonObject }
7981
```

‎docs/versioned_docs/version-v0.6.0/02-Features/powershell/azure-devops.md‎

Lines changed: 63 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ This module provides the following capabilities:
1919
To have access to the following features, you have to import the module:
2020

2121
```powershell
22-
PS> Install-Module -Name Arcus.Scripting.DevOps
22+
PS> Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
23+
PS> Install-Module -Name Arcus.Scripting.DevOps -Repository PSGallery -AllowClobber
2324
```
2425

2526
## 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
4950
| `UpdateVariablesForCurrentJob` | no | The switch to also set the variables in the ARM output as pipeline variables in the current running job |
5051

5152
**Example**
53+
5254
Without updating the variables in the current job running the pipeline:
5355

5456
```powershell
@@ -82,6 +84,37 @@ PS> Set-AzDevOpsArmOutputsToVariableGroup -VariableGroupName "my-variable-group"
8284
# The pipeline variable $variableName will be updated to value $variableValue as well, so it can be used in subsequent tasks of the current job.
8385
```
8486

87+
**Azure DevOps Example**
88+
This function is intended to be used from an Azure DevOps pipeline. Internally, it uses some predefined Azure DevOps variables.
89+
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.
90+
To be able to use this variable, it must be explicitly added to the environment-variables.
91+
92+
> ⚠ 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.
93+
94+
> 💡 We have seen a much better performance when using Linux agents, and would recommend using Linux agents when possible.
95+
96+
Example of how to use this function in an Azure DevOps pipeline:
97+
98+
```yaml
99+
- task: PowerShell@2
100+
displayName: 'Promote Azure resource outputs to variable group'
101+
env:
102+
SYSTEM_ACCESSTOKEN: $(System.AccessToken)
103+
ArmOutputs: $(ArmOutputs) # only needs to be set for Linux agents
104+
inputs:
105+
targetType: 'inline'
106+
script: |
107+
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
108+
Install-Module -Name Arcus.Scripting.DevOps -Repository PSGallery -AllowClobber
109+
110+
Set-AzDevOpsArmOutputsToVariableGroup -VariableGroupName "my-variable-group"
111+
```
112+
113+
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).
114+
115+
- Project Collection Build Service (`<your devops org name>`) - Administrator
116+
- `<your devops project name>` Build Service (`<your devops org name>`) - Administrator
117+
85118
## Setting ARM outputs to Azure DevOps pipeline variables
86119

87120
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
91124
| `ArmOutputsEnvironmentVariableName` | no | The name of the environment variable where the ARM outputs are located (default: `ArmOutputs`) |
92125

93126
**Example**
127+
94128
With default `ArmOutputs` environment variable containing: `"my-variable": "my-value"`:
95129

96130
```powershell
@@ -109,6 +143,29 @@ PS> Set-AzDevOpsArmOutputsToPipelineVariables -ArmOutputsEnvironmentVariableName
109143
# ##vso[task.setvariable variable=my-variable]my-value
110144
```
111145

146+
**Azure DevOps Example**
147+
This function is intended to be used from an Azure DevOps pipeline.
148+
149+
> ⚠ 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.
150+
151+
> 💡 We have seen a much better performance when using Linux agents, and would recommend using Linux agents when possible.
152+
153+
Example of how to use this function in an Azure DevOps pipeline:
154+
155+
```yaml
156+
- task: PowerShell@2
157+
displayName: 'Promote Azure resource outputs to pipeline variables'
158+
env:
159+
ArmOutputs: $(ArmOutputs) # only needs to be set for Linux agents
160+
inputs:
161+
targetType: 'inline'
162+
script: |
163+
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
164+
Install-Module -Name Arcus.Scripting.DevOps -Repository PSGallery -AllowClobber
165+
166+
Set-AzDevOpsArmOutputsToPipelineVariables
167+
```
168+
112169
## Save Azure DevOps build
113170

114171
Saves/retains a specific Azure DevOps pipeline run.
@@ -126,8 +183,9 @@ PS> Save-AzDevOpsBuild -ProjectId $(System.TeamProjectId) -BuildId $(Build.Build
126183
# Information on them can be found here: https://docs.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml
127184
```
128185

129-
This function is intended to be used from an Azure DevOps pipeline. Internally, it uses some predefined Azure DevOps variables.
130-
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.
186+
**Azure DevOps Example**
187+
This function is intended to be used from an Azure DevOps pipeline. Internally, it uses some predefined Azure DevOps variables.
188+
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.
131189
To be able to use this variable, it must be explicitly added to the environment-variables.
132190

133191
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:
141199
targetType: 'inline'
142200
pwsh: true
143201
script: |
144-
Install-Module -Name Arcus.Scripting.DevOps -Force
202+
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
203+
Install-Module -Name Arcus.Scripting.DevOps -Repository PSGallery -AllowClobber
145204
146205
$project = "$(System.TeamProjectId)"
147206
$buildId = $(Build.BuildId)

‎docs/versioned_docs/version-v0.6.0/02-Features/powershell/azure-management.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
2+
---
3+
title: "Azure Management"
4+
layout: default
5+
---
6+
7+
# Azure Management
8+
9+
This module provides the following capabilities:
10+
- [Azure Management](#azure-management)
11+
- [Installation](#installation)
12+
- [Removing a soft deleted API Management instance](#removing-a-soft-deleted-api-management-instance)
13+
- [Restoring a soft deleted API Management instance](#restoring-a-soft-deleted-api-management-instance)
14+
15+
## Installation
16+
17+
To have access to the following features, you have to import the module:
18+
19+
```powershell
20+
PS> Install-Module -Name Arcus.Scripting.Management
21+
```
22+
23+
## Removing a soft deleted API Management instance
24+
25+
Removes a soft deleted API Management instance.
26+
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).
27+
28+
| Parameter | Mandatory | Description |
29+
| ---------------- | --------- | ---------------------------------------------------------------------------------------------------------- |
30+
| `Name` | yes | The name of the API Management instance that has been soft deleted. |
31+
| `SubscriptionId` | no | The Id of the subscription containing the Azure API Management instance. |
32+
| | | When not provided, it will be retrieved from the current context (Get-AzContext). |
33+
| `EnvironmentName`| no | The name of the Azure environment where the Azure API Management instance resides. (default: `AzureCloud`) |
34+
| `AccessToken` | no | The access token to be used to remove the Azure API Management instance. |
35+
| | | When not provided, it will be retrieved from the current context (Get-AzContext). |
36+
| `ApiVersion ` | no | The version of the management API to be used. (default: `2021-08-01`) |
37+
38+
> :bulb: The `ApiVersion` has successfully been tested with version `2021-08-01`.
39+
40+
**Example**
41+
```powershell
42+
PS> Remove-AzApiManagementSoftDeletedService -Name "my-apim"
43+
# Checking if the API Management instance with name 'my-apim' is listed as a soft deleted service
44+
# API Management instance has been found for name 'my-apim' as a soft deleted service
45+
# Removing the soft deleted API Management instance 'my-apim'
46+
# Successfully removed the soft deleted API Management instance 'my-apim'
47+
```
48+
49+
## Restoring a soft deleted API Management instance
50+
51+
Restores a soft deleted API Management instance.
52+
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).
53+
54+
| Parameter | Mandatory | Description |
55+
| ---------------- | --------- | ---------------------------------------------------------------------------------------------------------- |
56+
| `Name` | yes | The name of the API Management instance that has been soft deleted. |
57+
| `SubscriptionId` | no | The Id of the subscription containing the Azure API Management instance. |
58+
| | | When not provided, it will be retrieved from the current context (Get-AzContext). |
59+
| `EnvironmentName`| no | The name of the Azure environment where the Azure API Management instance resides. (default: `AzureCloud`) |
60+
| `AccessToken` | no | The access token to be used to restore the Azure API Management instance. |
61+
| | | When not provided, it will be retrieved from the current context (Get-AzContext). |
62+
| `ApiVersion ` | no | The version of the management API to be used. (default: `2021-08-01`) |
63+
64+
> :bulb: The `ApiVersion` has successfully been tested with version `2021-08-01`.
65+
66+
**Example**
67+
```powershell
68+
PS> Restore-AzApiManagementSoftDeletedService -Name "my-apim"
69+
# Checking if the API Management instance with name 'my-apim' is listed as a soft deleted service
70+
# API Management instance has been found for name 'my-apim' as a soft deleted service
71+
# Restoring the soft deleted API Management instance 'my-apim'
72+
# Successfully restored the soft deleted API Management instance 'my-apim'
73+
```

0 commit comments

Comments
 (0)