Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: publish v1.1.0 feature docs #397

Merged
merged 1 commit into from
Jul 3, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions docs/versioned_docs/version-v1.1.0/01-index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
title: "Arcus - Scripting"
layout: default
slug: /
sidebar_label: Welcome
---

# Introduction
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!

Take a quick look at the sidebar categories to find more information on the resource or topic you're working with.

![Arcus Azure diagram](/img/arcus-azure-diagram.png)

# License
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.

*[Full license here](https://github.com/arcus-azure/arcus.scripting/blob/master/LICENSE)*
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
title: "Installation"
layout: default
---

# Installation

To have access to the Arcus Scripting features, you have to import the modules.
The best practice for usage in your build and release pipelines is to use the following commands:

``` powershell
PS> Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
PS> Install-Module -Name Arcus.Scripting.{Module} -AllowClobber
```

This drastically improves performance over using the `-Force` parameter and as such, usage of the `-Force` parameter is not recommended.
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
---
title: "Setting ARM outputs to Azure DevOps variable group"
layout: default
---

# Setting ARM outputs to Azure DevOps variable group

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.

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.

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.

## Example
### Specify Output Parameters
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.

Our Bicep template looks like this:
``` bicep
param location string = resourceGroup().location

resource applicationInsight 'microsoft.insights/components@2020-02-02' = {
name: 'myAppInsights'
location: location
kind: 'other'
properties: {
Application_Type: 'other'
}
}

output ApplicationInsights_Id string = applicationInsight.id
output ApplicationInsights_ConnectionString string = reference(applicationInsight.id, '2020-02-02').ConnectionString
```

This Bicep template will deploy the Application Insights instance and place the `Id` and `ConnectionString` in the output parameters.

### Updating The Variable Group
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.

From an Azure DevOps pipeline this can be done like so:
``` powershell
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
Install-Module -Name Arcus.Scripting.DevOps -AllowClobber

Set-AzDevOpsArmOutputsToVariableGroup -VariableGroupName 'myVariableGroup'
```

### Combining It All In A Pipeline
Now that we have walked through both steps, let's take a look on how to combine all this into an Azure DevOps pipeline.
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.

``` yaml
- task: AzureResourceGroupDeployment@3
displayName: 'Deploy Bicep template'
inputs:
azureResourceManagerConnection: 'myServiceConnection'
subscriptionId: 'mySubscriptionId'
resourceGroupName: 'myResourceGroup'
location: 'West Europe'
csmFile: 'applicationInsights.bicep'
csmParametersFile: 'applicationInsights.parameters.json'
deploymentOutputs: ArmOutputs

- task: PowerShell@2
displayName: 'Update Variable Group'
env:
system_accesstoken: $(System.AccessToken)
inputs:
targetType: 'inline'
script: |
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
Install-Module -Name Arcus.Scripting.DevOps -AllowClobber

Set-AzDevOpsArmOutputsToVariableGroup -VariableGroupName 'myVariableGroup' -ArmOutputsEnvironmentVariableName 'ArmOutputs' -UpdateVariablesForCurrentJob
```

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'`.

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.

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.

## Closing Up
Using this setup we are able to deploy a Bicep template and update an Azure DevOps variable group with the specified output parameters!

> ⚠ Before running your pipeline, make sure the variable group already exists in Azure DevOps and the permissions below are set:
> - Project Collection Build Service (`<your devops org name>`) - Administrator
> - `<your devops project name>` Build Service (`<your devops org name>`) - Administrator

## Further Reading
- [Arcus Scripting Azure DevOps documentation](../03-Features/powershell/azure-devops.md)
- [Setting ARM outputs to Azure DevOps variable group](../03-Features/powershell/azure-devops.md#setting-arm-outputs-to-azure-devops-variable-group)
- [Setting ARM outputs to Azure DevOps pipeline variables](../03-Features/powershell/azure-devops.md#setting-arm-outputs-to-azure-devops-pipeline-variables)
- [Bicep Outputs](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/outputs/)
- [Azure DevOps Variable Groups](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/variable-groups?view=azure-devops&tabs=yaml)
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
---
title: "Azure Active Directory"
layout: default
---

# Azure Active Directory

## Installation

To have access to the following features, you have to import the module:

```powershell
PS> Install-Module -Name Arcus.Scripting.ActiveDirectory
```

## Access Rights to Azure Active Directory

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:

```powershell
PS> Install-Module -Name Microsoft.Graph.Applications
```

After importing this module, make sure you are connected to Microsoft Graph with the following scopes:

```powershell
PS> Connect-MgGraph -Scopes "Application.ReadWrite.All,AppRoleAssignment.ReadWrite.All"
```

## Listing the Roles and Role Assignments for an Azure Active Directory Application

Lists the roles and role assignments for an Azure Active Directory Application.

| Parameter | Mandatory | Description |
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ClientId` | yes | The client ID of the Azure Active Directory Application Registration for which the roles and assignments are retrieved. |
| `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. |

**Example**

Retrieving all information for a Client Id.

```powershell
PS> List-AzADAppRoleAssignments `
-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85"
#Found role 'FirstRole' on Active Directory Application 'main-application'
#Role 'FirstRole' is assigned to the Active Directory Application 'client-application-one' with ID '6ea09bbd-c21c-460c-b58a-f4a720f51826'
#Role 'FirstRole' is assigned to the Active Directory Application 'client-application-two' with ID 'ebafc99d-cbf4-4bd2-9295-f2b785cfc1a1'
#Found role 'SecondRole' on Active Directory Application 'arcus-scripting-test-main'
#Role 'SecondRole' is assigned to the Active Directory Application 'client-application-one' with ID '6ea09bbd-c21c-460c-b58a-f4a720f51826'
```

Retrieving all information for a Client Id and a specific role.

```powershell
PS> List-AzADAppRoleAssignments `
-ClientId 'b885c208-6067-44bd-aba9-4010c62b7d85' `
-RolesAssignedToClientId '6ea09bbd-c21c-460c-b58a-f4a720f51826'
#Found role 'FirstRole' on Active Directory Application 'main-application'
#Role 'FirstRole' is assigned to the Active Directory Application 'client-application-one' with id '6ea09bbd-c21c-460c-b58a-f4a720f51826'
#Found role 'SecondRole' on Active Directory Application 'main-application'
#Role 'SecondRole' is assigned to the Active Directory Application 'client-application-one' with id '6ea09bbd-c21c-460c-b58a-f4a720f51826'
```

## Add a Role and Assignment for an Azure Active Directory Application

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.

| Parameter | Mandatory | Description |
| ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ClientId` | yes | The client ID of the Azure Active Directory Application Registration to which the role will be added if not present. |
| `Role` | yes | The name of the role. |
| `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`. |

**Example**

```powershell
PS> Add-AzADAppRoleAssignment `
-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85" `
-Role "DummyRole" `
-AssignRoleToClientId "6ea09bbd-c21c-460c-b58a-f4a720f51826"
#Active Directory Application 'main-application' does not contain the role 'DummyRole', adding the role
#Added Role 'DummyRole' to Active Directory Application 'main-application'
#Role Assignment for the role 'DummyRole' added to the Active Directory Application 'client-application-one'
```

## Remove a Role and Assignment from an Azure Active Directory Application

Removes a role assignment for an Azure Active Directory Application.

| Parameter | Mandatory | Description |
| ---------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ClientId` | yes | The client ID of the Azure Active Directory Application Registration containing the role for which the assignment must be removed. |
| `Role` | yes | The name of the role. |
| `RemoveRoleFromClientId` | yes | The client ID of the Azure Active Directory Application Registration for which the role assignment will be removed. |
| `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. |

**Example**

Removes a role assignment.

```powershell
PS> Remove-AzADAppRoleAssignment `
-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85" `
-Role "DummyRole" `
-RemoveRoleFromClientId "6ea09bbd-c21c-460c-b58a-f4a720f51826" `
#Role assignment for 'DummyRole' has been removed from Active Directory Application 'client-application-one'
```

Removes a role assignment and removes the fole if no assignments are left on the role.

```powershell
PS> Remove-AzADAppRoleAssignment `
-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85" `
-Role "DummyRole" `
-RemoveRoleFromClientId "6ea09bbd-c21c-460c-b58a-f4a720f51826" `
-RemoveRoleIfNoAssignmentsAreLeft
#Role assignment for 'DummyRole' has been removed from Active Directory Application 'client-application-one'
#Role 'DummyRole' on Active Directory Application 'main-application' has been disabled as no more role assignments were left and the option 'RemoveRoleIfNoAssignmentsAreLeft' is set
#Role 'DummyRole' removed from Active Directory Application 'main-application' as no more role assignments were left and the option 'RemoveRoleIfNoAssignmentsAreLeft' is set
```

Loading