Skip to content

Commit d11ff7c

Browse files
pim-simonspim-simons
authored
add v1.0.0 docs (#387)
Co-authored-by: Pim Simons <pim.simons@codit.eu>
1 parent 558caa5 commit d11ff7c

23 files changed

Lines changed: 2659 additions & 0 deletions

‎docs/versioned_docs/version-v1.0.0/01-index.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: "Arcus - Scripting"
3+
layout: default
4+
slug: /
5+
sidebar_label: Welcome
6+
---
7+
8+
# Introduction
9+
Arcus Scripting provides an answer to many frequently-used, repeated tasks in Azure. Categorized in separate PowerShell modules, these functions help with backing up your API Management service, removing resource locks, disabling Logic Apps, injecting content in ARM templates, and many more!
10+
11+
Take a quick look at the sidebar categories to find more information on the resource or topic you're working with.
12+
13+
![Arcus Azure diagram](/img/arcus-azure-diagram.png)
14+
15+
# License
16+
This is licensed under The MIT License (MIT). Which means that you can use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the web application. But you always need to state that Codit is the original author of this web application.
17+
18+
*[Full license here](https://github.com/arcus-azure/arcus.scripting/blob/master/LICENSE)*

‎docs/versioned_docs/version-v1.0.0/02-Guidelines/Installation.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: "Installation"
3+
layout: default
4+
---
5+
6+
# Installation
7+
8+
To have access to the Arcus Scripting features, you have to import the modules.
9+
The best practice for usage in your build and release pipelines is to use the following commands:
10+
11+
``` powershell
12+
PS> Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
13+
PS> Install-Module -Name Arcus.Scripting.{Module} -AllowClobber
14+
```
15+
16+
This drastically improves performance over using the `-Force` parameter and as such, usage of the `-Force` parameter is not recommended.

‎docs/versioned_docs/version-v1.0.0/02-Guidelines/setting-arm-outputs-to-azure-devops-variable-group.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: "Setting ARM outputs to Azure DevOps variable group"
3+
layout: default
4+
---
5+
6+
# Setting ARM outputs to Azure DevOps variable group
7+
8+
In ARM and Bicep templates it is possible to specify [output parameters](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/outputs), this enables you to return values from the deployed resources.
9+
10+
To enable maximum re-use of these output parameters within your environment we developed [this script](https://scripting.arcus-azure.net/Features/powershell/azure-devops#setting-arm-outputs-to-azure-devops-variable-group) which is available in the `Arcus.Scripting.DevOps` PowerShell module. It allows you to store those output parameters in an Azure DevOps variable group. This helps you in making sure certain parameters are available throughout your Azure DevOps environment.
11+
12+
For example, think of a use-case where your vital infrastructure components are deployed in a seperate Azure DevOps pipeline and need to be referenced from other components. Storing the necessary information such as identifiers, locations or names of these components in an Azure DevOps variable group allows you to easily use these values from other components.
13+
14+
## Example
15+
### Specify Output Parameters
16+
So how does this work in practice? Let's take an example where we will deploy a very basic Application Insights instance and specify the `Id` and `ConnectionString` of the Application Insights instance as output parameters.
17+
18+
Our Bicep template looks like this:
19+
``` bicep
20+
param location string = resourceGroup().location
21+
22+
resource applicationInsight 'microsoft.insights/components@2020-02-02' = {
23+
name: 'myAppInsights'
24+
location: location
25+
kind: 'other'
26+
properties: {
27+
Application_Type: 'other'
28+
}
29+
}
30+
31+
output ApplicationInsights_Id string = applicationInsight.id
32+
output ApplicationInsights_ConnectionString string = reference(applicationInsight.id, '2020-02-02').ConnectionString
33+
```
34+
35+
This Bicep template will deploy the Application Insights instance and place the `Id` and `ConnectionString` in the output parameters.
36+
37+
### Updating The Variable Group
38+
Now all we need to do is execute our [script](../03-Features/powershell/azure-devops.md#setting-arm-outputs-to-azure-devops-variable-group) which will update the Azure DevOps variable group.
39+
40+
From an Azure DevOps pipeline this can be done like so:
41+
``` powershell
42+
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
43+
Install-Module -Name Arcus.Scripting.DevOps -AllowClobber
44+
45+
Set-AzDevOpsArmOutputsToVariableGroup -VariableGroupName 'myVariableGroup'
46+
```
47+
48+
### Combining It All In A Pipeline
49+
Now that we have walked through both steps, let's take a look on how to combine all this into an Azure DevOps pipeline.
50+
For this we use YAML and define two tasks, the first will deploy our Application Insights instance and the second will update our Azure DevOps variable group.
51+
52+
``` yaml
53+
- task: AzureResourceGroupDeployment@3
54+
displayName: 'Deploy Bicep template'
55+
inputs:
56+
azureResourceManagerConnection: 'myServiceConnection'
57+
subscriptionId: 'mySubscriptionId'
58+
resourceGroupName: 'myResourceGroup'
59+
location: 'West Europe'
60+
csmFile: 'applicationInsights.bicep'
61+
csmParametersFile: 'applicationInsights.parameters.json'
62+
deploymentOutputs: ArmOutputs
63+
64+
- task: PowerShell@2
65+
displayName: 'Update Variable Group'
66+
env:
67+
system_accesstoken: $(System.AccessToken)
68+
inputs:
69+
targetType: 'inline'
70+
script: |
71+
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
72+
Install-Module -Name Arcus.Scripting.DevOps -AllowClobber
73+
74+
Set-AzDevOpsArmOutputsToVariableGroup -VariableGroupName 'myVariableGroup' -ArmOutputsEnvironmentVariableName 'ArmOutputs' -UpdateVariablesForCurrentJob
75+
```
76+
77+
There are a few things worth noting. First of all we define `deploymentOutputs: ArmOutputs` during the `AzureResourceGroupDeployment@3` task. This means that the output parameters we specified in our Bicep template will be placed in a variable called `ArmOutputs`, this is then referenced during the execution of our script with `-ArmOutputsEnvironmentVariableName 'ArmOutputs'`.
78+
79+
Secondly we use `-UpdateVariablesForCurrentJob` as a parameter when calling the script. This means that the output parameters from the Bicep file are also available as pipeline variables in the current running job. While not necessary in our example here, if you need to deploy another Bicep template that needs output parameters from an earlier deployed Bicep template this is the way to do it.
80+
81+
Finally we use `system_accesstoken: $(System.AccessToken)` in the `Powershell@2` task, this is necessary because we need to use the security token used by the running build.
82+
83+
## Closing Up
84+
Using this setup we are able to deploy a Bicep template and update an Azure DevOps variable group with the specified output parameters!
85+
86+
> ⚠ Before running your pipeline, make sure the variable group already exists in Azure DevOps and the permissions below are set:
87+
> - Project Collection Build Service (`<your devops org name>`) - Administrator
88+
> - `<your devops project name>` Build Service (`<your devops org name>`) - Administrator
89+
90+
## Further Reading
91+
- [Arcus Scripting Azure DevOps documentation](../03-Features/powershell/azure-devops.md)
92+
- [Setting ARM outputs to Azure DevOps variable group](../03-Features/powershell/azure-devops.md#setting-arm-outputs-to-azure-devops-variable-group)
93+
- [Setting ARM outputs to Azure DevOps pipeline variables](../03-Features/powershell/azure-devops.md#setting-arm-outputs-to-azure-devops-pipeline-variables)
94+
- [Bicep Outputs](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/outputs/)
95+
- [Azure DevOps Variable Groups](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/variable-groups?view=azure-devops&tabs=yaml)

‎docs/versioned_docs/version-v1.0.0/03-Features/powershell/azure-active-directory.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
title: "Azure Active Directory"
3+
layout: default
4+
---
5+
6+
# Azure Active Directory
7+
8+
## Installation
9+
10+
To have access to the following features, you have to import the module:
11+
12+
```powershell
13+
PS> Install-Module -Name Arcus.Scripting.ActiveDirectory
14+
```
15+
16+
## Access Rights to Azure Active Directory
17+
18+
To interact with Azure Active Directory these scripts use the [Microsoft.Graph.Applications](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.applications/) module, import this module:
19+
20+
```powershell
21+
PS> Install-Module -Name Microsoft.Graph.Applications
22+
```
23+
24+
After importing this module, make sure you are connected to Microsoft Graph with the following scopes:
25+
26+
```powershell
27+
PS> Connect-MgGraph -Scopes "Application.ReadWrite.All,AppRoleAssignment.ReadWrite.All"
28+
```
29+
30+
## Listing the Roles and Role Assignments for an Azure Active Directory Application
31+
32+
Lists the roles and role assignments for an Azure Active Directory Application.
33+
34+
| Parameter | Mandatory | Description |
35+
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
36+
| `ClientId` | yes | The client ID of the Azure Active Directory Application Registration for which the roles and assignments are retrieved. |
37+
| `RolesAssignedToClientId` | no | The client ID of the Azure Active Directory Application Registration to which roles have been assigned, used when you only want to retrieve the assignments for this specific application. |
38+
39+
**Example**
40+
41+
Retrieving all information for a Client Id.
42+
43+
```powershell
44+
PS> List-AzADAppRoleAssignments `
45+
-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85"
46+
#Found role 'FirstRole' on Active Directory Application 'main-application'
47+
#Role 'FirstRole' is assigned to the Active Directory Application 'client-application-one' with ID '6ea09bbd-c21c-460c-b58a-f4a720f51826'
48+
#Role 'FirstRole' is assigned to the Active Directory Application 'client-application-two' with ID 'ebafc99d-cbf4-4bd2-9295-f2b785cfc1a1'
49+
#Found role 'SecondRole' on Active Directory Application 'arcus-scripting-test-main'
50+
#Role 'SecondRole' is assigned to the Active Directory Application 'client-application-one' with ID '6ea09bbd-c21c-460c-b58a-f4a720f51826'
51+
```
52+
53+
Retrieving all information for a Client Id and a specific role.
54+
55+
```powershell
56+
PS> List-AzADAppRoleAssignments `
57+
-ClientId 'b885c208-6067-44bd-aba9-4010c62b7d85' `
58+
-RolesAssignedToClientId '6ea09bbd-c21c-460c-b58a-f4a720f51826'
59+
#Found role 'FirstRole' on Active Directory Application 'main-application'
60+
#Role 'FirstRole' is assigned to the Active Directory Application 'client-application-one' with id '6ea09bbd-c21c-460c-b58a-f4a720f51826'
61+
#Found role 'SecondRole' on Active Directory Application 'main-application'
62+
#Role 'SecondRole' is assigned to the Active Directory Application 'client-application-one' with id '6ea09bbd-c21c-460c-b58a-f4a720f51826'
63+
```
64+
65+
## Add a Role and Assignment for an Azure Active Directory Application
66+
67+
Adds a role assignment for an Azure Active Directory Application. The role will be added to the Azure Active Directory Application Registration defined by the `ClientId` parameter, and a role assignment for this role will be added to the Azure Active Directory Application Registration defined by the `AssignRoleToClientId` parameter.
68+
69+
| Parameter | Mandatory | Description |
70+
| ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
71+
| `ClientId` | yes | The client ID of the Azure Active Directory Application Registration to which the role will be added if not present. |
72+
| `Role` | yes | The name of the role. |
73+
| `AssignRoleToClientId` | yes | The client ID of the Azure Active Directory Application Registration for which the role assignment will be created. The role assignment will be created based on the role added to the Azure Active Directory Application Registration defined by the `ClientId`. |
74+
75+
**Example**
76+
77+
```powershell
78+
PS> Add-AzADAppRoleAssignment `
79+
-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85" `
80+
-Role "DummyRole" `
81+
-AssignRoleToClientId "6ea09bbd-c21c-460c-b58a-f4a720f51826"
82+
#Active Directory Application 'main-application' does not contain the role 'DummyRole', adding the role
83+
#Added Role 'DummyRole' to Active Directory Application 'main-application'
84+
#Role Assignment for the role 'DummyRole' added to the Active Directory Application 'client-application-one'
85+
```
86+
87+
## Remove a Role and Assignment from an Azure Active Directory Application
88+
89+
Removes a role assignment for an Azure Active Directory Application.
90+
91+
| Parameter | Mandatory | Description |
92+
| ---------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
93+
| `ClientId` | yes | The client ID of the Azure Active Directory Application Registration containing the role for which the assignment must be removed. |
94+
| `Role` | yes | The name of the role. |
95+
| `RemoveRoleFromClientId` | yes | The client ID of the Azure Active Directory Application Registration for which the role assignment will be removed. |
96+
| `RemoveRoleIfNoAssignmentsAreLeft` | no | Indicate whether to remove the role from the Azure Active Directory Application Registration defined by the `ClientId` parameter when no more role assignments remain for the role. |
97+
98+
**Example**
99+
100+
Removes a role assignment.
101+
102+
```powershell
103+
PS> Remove-AzADAppRoleAssignment `
104+
-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85" `
105+
-Role "DummyRole" `
106+
-RemoveRoleFromClientId "6ea09bbd-c21c-460c-b58a-f4a720f51826" `
107+
#Role assignment for 'DummyRole' has been removed from Active Directory Application 'client-application-one'
108+
```
109+
110+
Removes a role assignment and removes the fole if no assignments are left on the role.
111+
112+
```powershell
113+
PS> Remove-AzADAppRoleAssignment `
114+
-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85" `
115+
-Role "DummyRole" `
116+
-RemoveRoleFromClientId "6ea09bbd-c21c-460c-b58a-f4a720f51826" `
117+
-RemoveRoleIfNoAssignmentsAreLeft
118+
#Role assignment for 'DummyRole' has been removed from Active Directory Application 'client-application-one'
119+
#Role 'DummyRole' on Active Directory Application 'main-application' has been disabled as no more role assignments were left and the option 'RemoveRoleIfNoAssignmentsAreLeft' is set
120+
#Role 'DummyRole' removed from Active Directory Application 'main-application' as no more role assignments were left and the option 'RemoveRoleIfNoAssignmentsAreLeft' is set
121+
```
122+

0 commit comments

Comments
 (0)