diff --git a/docs/versioned_docs/version-v0.7.0/01-index.md b/docs/versioned_docs/version-v0.7.0/01-index.md new file mode 100644 index 00000000..4e5eec78 --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/01-index.md @@ -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)* diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/arm.md b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/arm.md new file mode 100644 index 00000000..11da013c --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/arm.md @@ -0,0 +1,84 @@ +--- +title: "ARM templates" +layout: default +--- + +# ARM + +This module provides the following capabilities: +- [ARM](#arm) + - [Installation](#installation) + - [Injecting content into an ARM template](#injecting-content-into-an-arm-template) + - [Usage](#usage) + - [Injection Instructions](#injection-instructions) + - [Recommendations](#recommendations) + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +PS> Install-Module -Name Arcus.Scripting.ARM +``` + +## Injecting content into an ARM template + +In certain scenarios, you have to embed content into an ARM template to deploy it. + +However, the downside of it is that it's buried inside the template and tooling around it might be less ideal - An example of this is OpenAPI specifications you'd want to deploy. + +By using this script, you can inject external files inside your ARM template. + +| Parameter | Mandatory | Description | +| --------- | --------- | ----------------------------------------------------------------------------------------------- | +| `Path` | no | The file path to the ARM template to inject the external files into (default: `$PSScriptRoot`) | + +### Usage +Annotating content to inject: + +```json +{ + "type": "Microsoft.ApiManagement/service/apis", + "name": "[concat(parameters('ApiManagement.Name'),'/', parameters('ApiManagement.Api.Name'))]", + "apiVersion": "2019-01-01", + "properties": { + "subscriptionRequired": true, + "path": "demo", + "value": "${ FileToInject='.\\..\\openapi\\api-sample.json', InjectAsJsonObject}$", + "format": "swagger-json" + }, + "tags": "[variables('Tags')]", + "dependsOn": [ + ] +} +``` + +Injecting the content: + +```powershell +PS> Inject-ArmContent -Path deploy\arm-template.json +``` + +### Injection Instructions + +It is possible to supply injection instructions in the injection annotation, this allows you to add specific functionality to the injection. These are the available injection instructions: + +| Injection Instruction | Description | +| --------------------- | ----------------------------------------------------------------------------------------------------------- | +| `EscapeJson` | Replace double quotes not preceded by a backslash with escaped quotes | +| `ReplaceSpecialChars` | Replace newline characters with literal equivalents, tabs with spaces and `"` with `\"` | +| `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 } +``` + +### Recommendations +Always inject the content in your ARM template as soon as possible, preferably during release build that creates the artifact diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-api-management.md b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-api-management.md new file mode 100644 index 00000000..73a6e144 --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-api-management.md @@ -0,0 +1,321 @@ +--- +title: "Azure API Management" +layout: default +--- + +# Azure API Management + +This module provides the following capabilities: +- [Azure API Management](#azure-api-management) + - [Installation](#installation) + - [Backing up an API Management service](#backing-up-an-api-management-service) + - [Creating a new API operation in the Azure API Management instance](#creating-a-new-api-operation-in-the-azure-api-management-instance) + - [Creating a new user in an Azure API Management service](#creating-a-new-user-in-an-azure-api-management-service) + - [Importing a policy to an API in the Azure API Management instance](#importing-a-policy-to-an-api-in-the-azure-api-management-instance) + - [Importing a policy to an operation in the Azure API Management instance](#importing-a-policy-to-an-operation-in-the-azure-api-management-instance) + - [Removing all Azure API Management defaults from the instance](#removing-all-azure-api-management-defaults-from-the-instance) + - [Restoring an API Management service](#restoring-an-api-management-service) + - [Setting authentication keys to an API in the Azure API Management instance](#setting-authentication-keys-to-an-api-in-the-azure-api-management-instance) + - [Uploading private certificates to the Azure API Management certificate store](#uploading-private-certificates-to-the-azure-api-management-certificate-store) + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +PS> Install-Module -Name Arcus.Scripting.ApiManagement +``` + +## Backing up an API Management service + +Backs up an API Management service (with built-in storage context retrieval). + +| Parameter | Mandatory | Description | +| --------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The name of the of resource group under which the API Management deployment exists. | +| `StorageAccountResourceGroupName` | yes | The name of the resource group under which the storage account exists. | +| `StorageAccountName` | yes | The name of the Storage account for which this cmdlet gets keys. | +| `ServiceName` | yes | The name of the API Management deployment that this cmdlet backs up. | +| `ContainerName` | yes | The name of the container of the blob for the backup. If the container does not exist, this cmdlet creates it. | +| `BlobName` | no | The name of the blob for the backup. If the blob does not exist, this cmdlet creates it (default value based on pattern: `{Name}-{yyyy-MM-dd-HH-mm}.apimbackup`. | +| `PassThru` | no | Indicates that this cmdlet returns the backed up PsApiManagement object, if the operation succeeds. | +| `DefaultProfile` | no | The credentials, account, tenant, and subscription used for communication with azure. | + +**Example** + +Simplest way to back up an API Management service. + +```powershell +PS> Backup-AzApiManagementService -ResourceGroupName "my-resource-group" -StorageAccountResourceGroupName "my-storage-account-resource-group" -StorageAccountName "my-storage-account" -ServiceName "my-service" -ContainerName "my-target-blob-container" +# Getting Azure storage account key.. +# Got Azure storage key! +# Create new Azure storage context with storage key... +# New Azure storage context with storage key created! +# Start backing up API management service... +# API management service is backed-up! +``` + +## Creating a new API operation in the Azure API Management instance + +Create an operation on an existing API in Azure API Management. + +| Parameter | Mandatory | Description | +| ------------------- | --------- | -------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure API Management instance | +| `ServiceName` | yes | The name of the Azure API Management instance located in Azure | +| `ApiId` | yes | The ID to identify the API running in Azure API Management | +| `OperationId` | yes | The ID to identify the to-be-created operation on the API | +| `Method` | yes | The method of the to-be-created operation on the API | +| `UrlTemplate` | yes | The URL-template, or endpoint-URL, of the to-be-created operation on the API | +| `OperationName` | no | The optional descriptive name to give to the to-be-created operation on the API (default: `OperationId`) | +| `Description` | no | The optional explanation to describe the to-be-created operation on the API | +| `PolicyFilePath` | no | The path to the file containing the optional policy of the to-be-created operation on the API | + +**Example** + +Creates a new API operation on the Azure API Management instance with using the default base operation policy. + +```powershell +PS> Create-AzApiManagementApiOperation -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -ApiId $ApiId -OperationId $OperationId -Method $Method -UrlTemplate $UrlTemplate +# New API operation '$OperationName' on Azure API Management instance was added. +``` + +Creates a new API operation on the Azure API Management instance with using a specific operation policy. + +```powershell +PS> Create-AzApiManagementApiOperation -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -ApiId $ApiId -OperationId $OperationId -Method $Method -UrlTemplate $UrlTemplate -OperationName $OperationName -Description $Description -PolicyFilePath $PolicyFilePath +# New API operation '$OperationName' on API Management instance was added. +``` + +## Creating a new user in an Azure API Management service + +Signup or invite a new user in an existing Azure API Management instance. + +| Parameter | Mandatory | Description | +| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure API Management instance | +| `ServiceName` | yes | The name of the Azure API Management instance located in Azure | +| `FirstName` | yes | The first name of the user that is to be created | +| `LastName` | yes | The last name of the user that is to be created | +| `MailAddress` | yes | The email address of the user that is to be created | +| `UserId` | no | The UserId that will be used to create the user | +| `Password` | no | The password that the user will be able to login with | +| `Note` | no | A note that will be added to the user | +| `SendNotification` | no | Wether or not a notification will be sent to the email address of the user | +| `ConfirmationType` | no | The confirmation type that will be used when creating the user, this can be `invite` (default) or `signup` | +| `ApiVersion` | no | The version of the management API to be used. (default: `2021-08-01`) | +| `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). | +| `AccessToken` | no | The access token to be used to add the user to the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext). | + +**Example** + +Invite a new user in an existing Azure API Management instance. + +```powershell +PS> Create-AzApiManagementUserAccount -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress +# Attempting to invite $FirstName $LastName ($MailAddress) +# Invitation has been sent to FirstName $LastName ($MailAddress) +``` + +Invite a new user in an existing Azure API Management instance and specify a UserId. + +```powershell +PS> Create-AzApiManagementUserAccount -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -UserId $UserId +# Attempting to invite $FirstName $LastName ($MailAddress) +# Invitation has been sent to FirstName $LastName ($MailAddress) +``` + +Invite a new user in an existing Azure API Management instance and include a note. + +```powershell +PS> Create-AzApiManagementUserAccount -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -Note $Note +# Attempting to invite $FirstName $LastName ($MailAddress) +# Invitation has been sent to FirstName $LastName ($MailAddress) +``` + +Invite a new user in an existing Azure API Management instance and send a notification. + +```powershell +PS> Create-AzApiManagementUserAccount -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -SendNotification +# Attempting to invite $FirstName $LastName ($MailAddress) +# Invitation has been sent to FirstName $LastName ($MailAddress) +``` + +Signup a new user in an existing Azure API Management instance. + +```powershell +PS> Create-AzApiManagementUserAccount -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -ConfirmationType signup +# Attempting to create account for FirstName $LastName ($MailAddress) +# Account has been created for FirstName $LastName ($MailAddress) +# Since no password was provided, one has been generated. Please advise the user to change this password the first time logging in +``` + +Signup a new user in an existing Azure API Management instance and specify a password. + +```powershell +PS> Create-AzApiManagementUserAccount -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -Password $Password -ConfirmationType signup +# Attempting to create account for FirstName $LastName ($MailAddress) +# Account has been created for FirstName $LastName ($MailAddress) +``` + +## Removing a user from an Azure API Management service + +Remove a user from an existing Azure API Management instance based on e-mail address. + +| Parameter | Mandatory | Description | +| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure API Management instance | +| `ServiceName` | yes | The name of the Azure API Management instance located in Azure | +| `MailAddress` | yes | The email address of the user that is to be removed | +| `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). | +| `AccessToken` | no | The access token to be used to add the user to the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext). | + +**Example** + +Remove a user from an existing Azure API Management instance. + +```powershell +PS> Remove-AzApiManagementUserAccount -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -MailAddress $MailAddress +# Retrieving the user account with e-mail '$MailAddress' +# Attempting to remove the user account with e-mail '$MailAddress' and id '1' +# Removed the user account with e-mail '$MailAddress' and id '1' +``` + +## Importing a policy to a product in the Azure API Management instance + +Imports a policy from a file to a product in Azure API Management. + +| Parameter | Mandatory | Description | +| ------------------- | --------- | --------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure API Management instance | +| `ServiceName` | yes | The name of the Azure API Management instance located in Azure | +| `ProductId` | yes | The ID to identify the product in Azure API Management | +| `PolicyFilePath` | yes | The path to the file containing the to-be-imported policy | + +```powershell +PS> Import-AzApiManagementProductPolicy -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -ProductId $ProductId -PolicyFilePath $PolicyFilePath +# Updating policy of the product '$ProductId' +``` + +## Importing a policy to an API in the Azure API Management instance + +Imports a base-policy from a file to an API in Azure API Management. + +| Parameter | Mandatory | Description | +| ------------------- | --------- | ---------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure API Management instance | +| `ServiceName` | yes | The name of the Azure API Management instance located in Azure | +| `ApiId` | yes | The ID to identify the API running in Azure API Management | +| `PolicyFilePath` | yes | The path to the file containing the to-be-imported policy | + +```powershell +PS> Import-AzApiManagementApiPolicy -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -ApiId $ApiId -PolicyFilePath $PolicyFilePath +# Updating policy of the API '$ApiId' +``` + +## Importing a policy to an operation in the Azure API Management instance + +Imports a policy from a file to an API operation in Azure API Management. + +| Parameter | Mandatory | Description | +| ------------------- | --------- | --------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure API Management instance | +| `ServiceName` | yes | The name of the Azure API Management service located in Azure | +| `ApiId` | yes | The ID to identify the API running in Azure API Management | +| `OperationId` | yes | The ID to identify the operation for which to import the policy | +| `PolicyFilePath` | yes | The path to the file containing the to-be-imported policy | + +```powershell +PS> Import-AzApiManagementOperationPolicy -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -ApiId $ApiId -OperationId $OperationId -PolicyFilePath $PolicyFilePath +# Updating policy of the operation '$OperationId' in API '$ApiId' +``` + +## Removing all Azure API Management defaults from the instance + +Remove all default API's and products from the Azure API Management instance ('echo-api' API, 'starter' & 'unlimited' products), including the subscriptions. + +| Parameter | Mandatory | Description | +| ------------------- | --------- | --------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure API Management instance | +| `ServiceName` | yes | The name of the Azure API Management instance located in Azure | + +```powershell +PS> Remove-AzApiManagementDefaults -ResourceGroupName $ResourceGroup -ServiceName $ServiceName +# Removing Echo Api... +# Removing Starter product... +# Removing Unlimited product... +``` + +## Restoring an API Management service + +The Restore-AzApiManagement cmdlet restores an API Management Service from the specified backup residing in an Azure Storage blob. + +| Parameter | Mandatory | Description | +| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The name of resource group under which API Management exists. | +| `StorageAccountResourceGroupName` | yes | The name of the resource group that contains the Storage account. | +| `StorageAccountName` | yes | The name of the Storage account for which this cmdlet gets keys. | +| `ServiceName` | yes | The name of the API Management instance that will be restored with the backup. | +| `ContainerName` | yes | The name of the Azure storage backup source container. | +| `BlobName` | yes | The name of the Azure storage backup source blob. | +| `PassThru` | no | Returns an object representing the item with which you are working. By default, this cmdlet does not generate any output. | +| `DefaultProfile` | no | The credentials, account, tenant, and subscription used for communication with azure. | + +```powershell +PS> Restore-AzApiManagementService -ResourceGroupName $ResourceGroupName -$StorageAccountResourceGroupName -StorageAccountName $StorageAccountName -ServiceName $ServiceName -ContainerName $ContainerName -BlobName $BlobName +# Getting Azure storage account key... +# Got Azure storage key! +# Create new Azure storage context with storage key... +# New Azure storage context with storage key created! +# Start restoring up API management service... +# API management service is restored! +``` + +## Setting authentication keys to an API in the Azure API Management instance + +Sets the subscription header/query parameter name to an API in Azure API Management. + +| Parameter | Mandatory | Description | +| ------------------- | --------- | --------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure API Management instance | +| `ServiceName` | yes | The name of the Azure API Management instance located in Azure | +| `ApiId` | yes | The ID to identify the API running in Azure API Management | +| `HeaderName` | no | The name of the header where the subscription key should be set. (default: `x-api-key`) | +| `QueryParamName` | no | The name of the query parameter where the subscription key should be set. (default: `apiKey`) | + +**Using default** + +```powershell +PS> Set-AzApiManagementApiSubscriptionKey -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -ApiId $ApiId +Write-Host "Using API Management instance '$ServiceName' in resource group '$ResourceGroup'" +Write-Host "Subscription key header 'x-api-key' was assigned" +Write-Host "Subscription key query parameter 'apiKey' was assigned" +``` + +**User-defined values** + +```powershell +PS> Set-AzApiManagementApiSubscriptionKey -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -ApiId $ApiId -HeaderName "my-api-key" -QueryParamName "myApiKey" +Write-Host "Using API Management instance '$ServiceName' in resource group '$ResourceGroup'" +Write-Host "Subscription key header 'my-api-key' was assigned" +Write-Host "Subscription key query parameter 'myApiKey' was assigned" +``` + +## Uploading private certificates to the Azure API Management certificate store + +Uploads a private certificate to the Azure API Management certificate store, allowing authentication against backend services. + +| Parameter | Mandatory | Description | +| --------------------- | --------- | --------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure API Management instance | +| `ServiceName` | yes | The name of the Azure API Management instance | +| `CertificateFilePath` | yes | The full file path to the location of the private certificate | +| `CertificatePassword` | yes | The password for the private certificate | + +**Example** + +```powershell +PS> Upload-AzApiManagementCertificate -ResourceGroupName "my-resource-group" -ServiceName "my-api-management-instance' -CertificateFilePath "c:\temp\certificate.pfx" -CertificatePassword "P@ssw0rd" +# Using API Management instance 'my-api-management-instance' in resource group 'my-resource-group' +# Uploaded private certificate at 'c:\temp\certificate.pfx' +``` diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-app-service.md b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-app-service.md new file mode 100644 index 00000000..c5cb345a --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-app-service.md @@ -0,0 +1,43 @@ +--- +title: "Azure App Service" +layout: default +--- + +# Azure App Service + +This module provides the following capabilities: +- [Azure App Service](#azure-app-service) + - [Installation](#installation) + - [Set an app setting within an Azure App Service](#set-an-app-setting-within-an-azure-app-service) + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +PS> Install-Module -Name Arcus.Scripting.AppService +``` + +## Set an app setting within an Azure App Service + +Create/update a single application setting within an Azure App Service. + +| Parameter | Mandatory | Description | +| ----------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The name of the Azure resource group where the Azure App Service is located. | +| `AppServiceName` | yes | The name of the Azure App Service where the application setting will be created/updated. | +| `AppServiceSettingName` | yes | The name of the application setting that will be created/updated. | +| `AppServiceSettingValue` | yes | The value of the application setting that will be created/updated. | +| `PrintSettingValuesIfVerbose` | no | Indicator (switch) whether the values of the application settings will be written to the verbose log. | + +**Example** + +Setting an application setting within an Azure App Service. +```powershell +PS> Set-AzAppServiceSetting -ResourceGroupName 'my-resource-group' -AppServiceName 'my-app-service' -AppServiceSettingName 'my-app-setting' -AppServiceSettingValue 'my-value' +# Checking if the App Service with name 'my-app-service' can be found in the resource group 'my-resource-group' +# App service has been found +# Extracting the existing application settings +# Setting the application setting 'my-app-setting' +# Successfully set the application setting 'my-app-setting' of the App Service 'my-app-service' within resource group 'my-resource-group' +``` diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-data-factory.md b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-data-factory.md new file mode 100644 index 00000000..fbef05a4 --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-data-factory.md @@ -0,0 +1,67 @@ +--- +title: " Azure Data Factory" +layout: default +--- + +# Azure Data Factory + +This module provides the following capabilities: +- [Azure Data Factory](#azure-data-factory) + - [Installation](#installation) + - [Enabling a trigger of an Azure Data Factory pipeline](#enabling-a-trigger-of-an-azure-data-factory-pipeline) + - [Disabling a trigger of an Azure Data Factory pipeline](#disabling-a-trigger-of-an-azure-data-factory-pipeline) + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +PS> Install-Module -Name Arcus.Scripting.DataFactory +``` + +## Enabling a trigger of an Azure Data Factory pipeline + +Enable a Data Factory V2 Trigger. + +| Parameter | Mandatory | Description | +| --------------------------- | --------- | ---------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure Data Factory V2 | +| `DataFactoryName` | yes | The name of the Azure Data Factory V2 | +| `DataFactoryTriggerName` | yes | The name of the trigger to be enabled | +| `FailWhenTriggerIsNotFound` | no | Indicate whether to throw an exception if the trigger cannot be found (default: `false`) | + +**Example** + +```powershell +PS> Enable-AzDataFactoryTrigger -ResourceGroupName "my-resource-group" -DataFactoryName "my-data-factory-name" -DataFactoryTriggerName "my-data-factory-trigger-name" +# The trigger 'my-data-factory-trigger-name' has been enabled. +``` + +```powershell +PS> Enable-AzDataFactoryTrigger -ResourceGroupName "my-resource-group" -DataFactoryName "my-data-factory-name" -DataFactoryTriggerName "unknown-data-factory-trigger-name" -FailWhenTriggerIsNotFound +# Error: Error retrieving trigger 'unknown-data-factory-trigger-name' in data factory 'my-data-factory'. +``` + + +## Disabling a trigger of an Azure Data Factory pipeline + +Disable a Data Factory V2 Trigger. + +| Parameter | Mandatory | Description | +| --------------------------- | --------- | ---------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure Data Factory V2 | +| `DataFactoryName` | yes | The name of the Azure Data Factory V2 | +| `DataFactoryTriggerName` | yes | The name of the trigger to be disabled | +| `FailWhenTriggerIsNotFound` | no | Indicate whether to throw an exception if the trigger cannot be found (default: `false`) | + +**Example** + +```powershell +PS> Disable-AzDataFactoryTrigger -ResourceGroupName "my-resource-group" -DataFactoryName "my-data-factory-name" -DataFactoryTriggerName "my-data-factory-trigger-name" +# The trigger 'my-data-factory-trigger-name' has been disabled. +``` + +```powershell +PS> Disable-AzDataFactoryTrigger -ResourceGroupName "my-resource-group" -DataFactoryName "my-data-factory-name" -DataFactoryTriggerName "unknown-data-factory-trigger-name" -FailWhenTriggerIsNotFound +# Error: Error retrieving trigger 'unknown-data-factory-trigger-name' in data factory 'my-data-factory'. +``` diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-devops.md b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-devops.md new file mode 100644 index 00000000..545b63cf --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-devops.md @@ -0,0 +1,209 @@ +--- +title: " Azure DevOps" +layout: default +--- + +# Azure DevOps + +This module provides the following capabilities: + +- [Azure DevOps](#azure-devops) + - [Installation](#installation) + - [Setting a variable in an Azure DevOps pipeline](#setting-a-variable-in-an-azure-devops-pipeline) + - [Setting ARM outputs to Azure DevOps variable group](#setting-arm-outputs-to-azure-devops-variable-group) + - [Setting ARM outputs to Azure DevOps pipeline variables](#setting-arm-outputs-to-azure-devops-pipeline-variables) + - [Save Azure DevOps build](#save-azure-devops-build) + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +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 + +Assign a value to a DevOps pipeline variable during the execution of this pipeline. + +| Parameter | Mandatory | Description | +| --------------- | --------- | ------------------------------------------------- | +| `Name` | yes | The name of the variable to set in the pipeline | +| `Value` | yes | The value of the variable to set in the pipeline | + +**Example** + +```powershell +PS> Set-AzDevOpsVariable "my-variable" "my-variable-value" +# #vso[task.setvariable variable=my-variable] my-variable-value +``` + +## Setting ARM outputs to Azure DevOps variable group + +Stores the Azure Resource Management (ARM) outputs in a variable group on Azure DevOps. + +| Parameter | Mandatory | Description | +| ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------- | +| `VariableGroupName` | yes | The name of the variable group on Azure DevOps where the ARM outputs should be stored | +| `ArmOutputsEnvironmentVariableName` | no | The name of the environment variable where the ARM outputs are located (default: `ArmOutputs`) | +| `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 +PS> Set-AzDevOpsArmOutputsToVariableGroup -VariableGroupName "my-variable-group" +# Get ARM outputs from 'ArmOutputs' environment variable +# Adding variable $output.Name with value $variableValue to variable group my-variable-group +# Retrieving project details +# Set properties for update of existing variable group +``` + +Include updating the variables in the current job running the pipeline, to immediately make them available to the next pipeline tasks: + +```powershell +PS> Set-AzDevOpsArmOutputsToVariableGroup -VariableGroupName "my-variable-group" -UpdateVariablesForCurrentJob +# Get ARM outputs from 'ArmOutputs' environment variable +# Adding variable $output.Name with value $variableValue to variable group my-variable-group +# Retrieving project details +# Set properties for update of existing 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. +# ##vso[task.setvariable variable=$variableName]$variableValue +``` + +Include user-defined environment variable for the ARM outputs: + +```powershell +PS> Set-AzDevOpsArmOutputsToVariableGroup -VariableGroupName "my-variable-group" -ArmOutputsEnvironmentVariableName "MyArmOutputs" +# Get ARM outputs from 'MyArmOutputs' environment variable +# Adding variable $output.Name with value $variableValue to variable group my-variable-group +# Retrieving project details +# Set properties for update of existing 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. + +| Parameter | Mandatory | Description | +| ----------------------------------- | --------- | ---------------------------------------------------------------------------------------------- | +| `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 +PS> Set-AzDevOpsArmOutputsToPipelineVariables +# Get ARM outputs from 'ArmOutputs' environment variable +# The pipeline variable my-variable will be updated to value my-value, so it can be used in subsequent tasks of the current job. +# ##vso[task.setvariable variable=my-variable]my-value +``` + +With custom `MyArmOutputs` environment variable containing: `"my-variable": "my-value"`: + +```powershell +PS> Set-AzDevOpsArmOutputsToPipelineVariables -ArmOutputsEnvironmentVariableName "MyArmOutputs" +# Get ARM outputs from 'MyArmOutputs' environment variable +# The pipeline variable my-variable will be updated to value my-value, so it can be used in subsequent tasks of the current job. +# ##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. + +| Parameter | Mandatory | Description | +| --------------- | --------- | ---------------------------------------------------------------------------| +| `ProjectId` | yes | The Id of the Project where the build that must be retained can be found | +| `BuildId` | yes | The Id of the build that must be retained | + +**Example** + +```powershell +PS> Save-AzDevOpsBuild -ProjectId $(System.TeamProjectId) -BuildId $(Build.BuildId) +# The variables $(System.TeamProjectId) and $(Build.BuildId) are predefined Azure DevOps variables +# Information on them can be found here: https://docs.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml +``` + +**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: + +```yaml +- task: PowerShell@2 + displayName: 'Retain current build indefinitely' + env: + SYSTEM_ACCESSTOKEN: $(System.AccessToken) + inputs: + targetType: 'inline' + pwsh: true + script: | + Set-PSRepository -Name PSGallery -InstallationPolicy Trusted + Install-Module -Name Arcus.Scripting.DevOps -Repository PSGallery -AllowClobber + + $project = "$(System.TeamProjectId)" + $buildId = $(Build.BuildId) + + Save-AzDevOpsBuild -ProjectId $project -BuildId $buildId +``` diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-integration-account.md b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-integration-account.md new file mode 100644 index 00000000..40142930 --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-integration-account.md @@ -0,0 +1,575 @@ +--- +title: "Azure Integration Account" +layout: default +--- + +# Azure Integration Account + +This module provides the following capabilities: +- [Azure Integration Account](#azure-integration-account) + - [Installation](#installation) + - [Uploading schemas into an Azure Integration Account](#uploading-schemas-into-an-azure-integration-account) + - [Uploading maps into an Azure Integration Account](#uploading-maps-into-an-azure-integration-account) + - [Uploading assemblies into an Azure Integration Account](#uploading-assemblies-into-an-azure-integration-account) + - [Uploading certificates into an Azure Integration Account](#uploading-certificates-into-an-azure-integration-account) + - [Uploading partners into an Azure Integration Account](#uploading-partners-into-an-azure-integration-account) + - [Uploading agreements into an Azure Integration Account](#uploading-agreements-into-an-azure-integration-account) + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +PS> Install-Module -Name Arcus.Scripting.IntegrationAccount +``` + +## Uploading schemas into an Azure Integration Account + +Upload/update a single, or multiple schemas into an Azure Integration Account. + +| Parameter | Mandatory | Description | +| ---------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The name of the Azure resource group where the Azure Integration Account is located. | +| `Name` | yes | The name of the Azure Integration Account into which the schemas are to be uploaded/updated. | +| `SchemaFilePath` | conditional | The full path of a schema that should be uploaded/updated. (_Mandatory if SchemasFolder has not been specified_). | +| `SchemasFolder` | conditional | The path to a directory containing all schemas that should be uploaded/updated. (_Mandatory if SchemaFilePath has not been specified_).| +| `ArtifactsPrefix` | no | The prefix, if any, that should be added to the schemas before uploading/updating. | +| `RemoveFileExtensions` | no | Indicator (switch) whether the extension should be removed from the name before uploading/updating. | + +**Example** + +Uploading a *single schema* into an Integration Account. +```powershell +PS> Set-AzIntegrationAccountSchemas -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -SchemaFilePath "C:\Schemas\MySchema.xsd" +# Uploading schema 'MySchema.xsd' into the Azure Integration Account 'my-integration-account' +# Schema 'MySchema.xsd' has been uploaded into the Azure Integration Account 'my-integration-account' +``` + +Uploading a *single schema* into an Integration Account and remove the file-extension. +```powershell +PS> Set-AzIntegrationAccountSchemas -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -SchemaFilePath "C:\Schemas\MySchema.xsd" -RemoveFileExtensions +# Uploading schema 'MySchema' into the Azure Integration Account 'my-integration-account' +# Schema 'MySchema' has been uploaded into the Azure Integration Account 'my-integration-account' +``` +Uploading a *single schema* into an Integration Account and set add a prefix to the name of the schema within the Integration Account. +```powershell +PS> Set-AzIntegrationAccountSchemas -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -SchemaFilePath "C:\Schemas\MySchema.xsd" -ArtifactsPrefix 'dev-' +# Uploading schema 'dev-MySchema.xsd' into the Azure Integration Account 'my-integration-account' +# Schema 'dev-MySchema.xsd' has been uploaded into the Azure Integration Account 'my-integration-account' +``` + +Uploading *all schemas* located in a specific folder into an Integration Account. +```powershell +PS> Set-AzIntegrationAccountSchemas -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -SchemasFolder "C:\Schemas" +# Uploading schema 'MyFirstSchema.xsd' into the Azure Integration Account 'my-integration-account' +# Schema 'MyFirstSchema.xsd' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +# Uploading schema 'MySecondSchema.xsd' into the Azure Integration Account 'my-integration-account' +# Schema 'MySecondSchema.xsd' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +``` + +Uploading *all schemas* located in a specific folder into an Integration Account and remove the file-extension. +```powershell +PS> Set-AzIntegrationAccountSchemas -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -SchemasFolder "C:\Schemas" -RemoveFileExtensions +# Uploading schema 'MyFirstSchema' into the Azure Integration Account 'my-integration-account' +# Schema 'MyFirstSchema' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +# Uploading schema 'MySecondSchema' into the Azure Integration Account 'my-integration-account' +# Schema 'MySecondSchema' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +``` + +Uploading *all schemas* located in a specific folder into an Integration Account and set add a prefix to the name of the schemas. +```powershell +PS> Set-AzIntegrationAccountSchemas -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -SchemasFolder "C:\Schemas" -ArtifactsPrefix 'dev-' +# Uploading schema 'dev-MyFirstSchema.xsd' into the Azure Integration Account 'my-integration-account' +# Schema 'dev-MyFirstSchema.xsd' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +# Uploading schema 'dev-MySecondSchema.xsd' into the Azure Integration Account 'my-integration-account' +# Schema 'dev-MySecondSchema.xsd' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +``` + + +## Uploading maps into an Azure Integration Account + +Upload/update a single, or multiple maps into an Azure Integration Account. + +| Parameter | Mandatory | Description | +| ---------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The name of the Azure resource group where the Azure Integration Account is located. | +| `Name` | yes | The name of the Azure Integration Account into which the maps are to be uploaded/updated. | +| `MapFilePath` | conditional | The full path of a map that should be uploaded/updated. (_Mandatory if MapsFolder has not been specified_). | +| `MapsFolder` | conditional | The path to a directory containing all maps that should be uploaded/updated. (_Mandatory if MapFilePath has not been specified_). | +| `MapType` | no | The type of map to be created, default to 'Xslt'. See possible values [here](https://docs.microsoft.com/en-us/powershell/module/az.logicapp/get-azintegrationaccountmap?view=azps-6.2.1#parameters). | +| `ArtifactsPrefix` | no | The prefix, if any, that should be added to the maps before uploading/updating. | +| `RemoveFileExtensions` | no | Indicator (switch) whether the extension should be removed from the name before uploading/updating. | + +**Example** + +Uploading a *single map* into an Integration Account. +```powershell +PS> Set-AzIntegrationAccountMaps -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -MapFilePath "C:\Maps\MyMap.xslt" +# Uploading map 'MyMap.xslt' into the Azure Integration Account 'my-integration-account' +# Map 'MyMap.xslt' has been uploaded into the Azure Integration Account 'my-integration-account' +``` + +Uploading a *single map* into an Integration Account and remove the file-extension. +```powershell +PS> Set-AzIntegrationAccountMaps -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -MapFilePath "C:\Maps\MyMap.xslt" -RemoveFileExtensions +# Uploading map 'MyMap' into the Azure Integration Account 'my-integration-account' +# Map 'MyMap' has been uploaded into the Azure Integration Account 'my-integration-account' +``` +Uploading a *single map* into an Integration Account and set add a prefix to the name of the schema within the Integration Account. +```powershell +PS> Set-AzIntegrationAccountMaps -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -MapFilePath "C:\Maps\MyMap.xslt" -ArtifactsPrefix 'dev-' +# Uploading map 'dev-MyMap.xsd' into the Azure Integration Account 'my-integration-account' +# Map 'dev-MyMap.xsd' has been uploaded into the Azure Integration Account 'my-integration-account' +``` + +Uploading *all maps* located in a specific folder into an Integration Account. +```powershell +PS> Set-AzIntegrationAccountMaps -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -MapsFolder "C:\Maps" +# Uploading map 'MyFirstMap.xslt' into the Azure Integration Account 'my-integration-account' +# Map 'MyFirstMap.xslt' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +# Uploading map 'MySecondMap.xslt' into the Azure Integration Account 'my-integration-account' +# Map 'MySecondMap.xslt' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +``` + +Uploading *all maps* located in a specific folder into an Integration Account and remove the file-extension. +```powershell +PS> Set-AzIntegrationAccountMaps -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -MapsFolder "C:\Maps" -RemoveFileExtensions +# Uploading map 'MyFirstMap' into the Azure Integration Account 'my-integration-account' +# Map 'MyFirstMap' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +# Uploading map 'MySecondMap' into the Azure Integration Account 'my-integration-account' +# Map 'MySecondMap' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +``` + +Uploading *all maps* located in a specific folder into an Integration Account and set add a prefix to the name of the maps. +```powershell +PS> Set-AzIntegrationAccountMaps -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -MapsFolder "C:\Maps" -ArtifactsPrefix 'dev-' +# Uploading map 'dev-MyFirstMap.xslt' into the Azure Integration Account 'my-integration-account' +# Map 'dev-MyFirstMap.xslt' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +# Uploading map 'dev-MySecondMap.xslt' into the Azure Integration Account 'my-integration-account' +# Map 'dev-MySecondMap.xslt' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +``` + +## Uploading assemblies into an Azure Integration Account + +Upload/update a single, or multiple assemblies into an Azure Integration Account. + +| Parameter | Mandatory | Description | +| ---------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The name of the Azure resource group where the Azure Integration Account is located. | +| `Name` | yes | The name of the Azure Integration Account into which the assemblies are to be uploaded/updated. | +| `AssemblyFilePath` | conditional | The full path of an assembly that should be uploaded/updated. (_Mandatory if AssembliesFolder has not been specified_). | +| `AssembliesFolder` | conditional | The path to a directory containing all assemblies that should be uploaded/updated. (_Mandatory if AssemblyFilePath has not been specified_). | +| `ArtifactsPrefix` | no | The prefix, if any, that should be added to the assemblies before uploading/updating. | + +**Example** + +Uploading a *single assembly* into an Integration Account. +```powershell +PS> Set-AzIntegrationAccountAssemblies -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -AssemblyFilePath "C:\Assemblies\MyAssembly.dll" +# Uploading assembly 'MyAssembly.dll' into the Azure Integration Account 'my-integration-account' +# Assembly 'MyAssembly.dll' has been uploaded into the Azure Integration Account 'my-integration-account' +``` + +Uploading a *single assembly* into an Integration Account and set add a prefix to the name of the assembly within the Integration Account. +```powershell +PS> Set-AzIntegrationAccountAssemblies -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -AssemblyFilePath "C:\Assemblies\MyAssembly.dll" -ArtifactsPrefix 'dev-' +# Uploading assembly 'dev-MyAssembly.dll' into the Azure Integration Account 'my-integration-account' +# Assembly 'dev-MyAssembly.dll' has been uploaded into the Azure Integration Account 'my-integration-account' +``` + +Uploading *all assemblies* located in a specific folder into an Integration Account. +```powershell +PS> Set-AzIntegrationAccountAssemblies -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -AssembliesFolder "C:\Assemblies" +# Uploading assembly 'MyFirstAssembly.dll' into the Azure Integration Account 'my-integration-account' +# Assembly 'MyFirstAssembly.dll' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +# Uploading assembly 'MySecondAssembly.dll' into the Azure Integration Account 'my-integration-account' +# Assembly 'MySecondAssembly.dll' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +``` + +Uploading *all assemblies* located in a specific folder into an Integration Account and set add a prefix to the name of the assemblies. +```powershell +PS> Set-AzIntegrationAccountAssemblies -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -AssembliesFolder "C:\Assemblies" -ArtifactsPrefix 'dev-' +# Uploading assembly 'dev-MyFirstAssembly.dll' into the Azure Integration Account 'my-integration-account' +# Assembly 'dev-MyFirstAssembly.dll' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +# Uploading assembly 'dev-MySecondAssembly.dll' into the Azure Integration Account 'my-integration-account' +# Assembly 'dev-MySecondAssembly.dll' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +``` + +## Uploading certificates into an Azure Integration Account + +Upload/update a single, or multiple certificates into an Azure Integration Account. + +| Parameter | Mandatory | Description | +| ---------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The name of the Azure resource group where the Azure Integration Account is located. | +| `Name` | yes | The name of the Azure Integration Account into which the certificates are to be uploaded/updated. | +| `CertificateType` | yes | The type of certificate that will be uploaded, this can be either _Public_ or _Private_. | +| `CertificateFilePath` | conditional | The full path of a certificate that should be uploaded/updated. (_Mandatory if CertificatesFolder has not been specified_). | +| `CertificatesFolder` | conditional | The path to a directory containing all certificates that should be uploaded/updated. (_Mandatory if CertificateFilePath has not been specified_). This parameter is not supported when uploading Private certificates. | +| `KeyName` | no | The name of the key in Azure KeyVault that is used when uploading Private certificates. (_Mandatory if CertificateType is set to Private_) | +| `KeyVersion` | no | The version of the key in Azure KeyVault that is used when uploading Private certificates. (_Mandatory if CertificateType is set to Private_) | +| `KeyVaultId` | no | The id of the Azure KeyVault that is used when uploading Private certificates. (_Mandatory if CertificateType is set to Private_) | +| `ArtifactsPrefix` | no | The prefix, if any, that should be added to the certificates before uploading/updating. | + +**Example** + +Uploading a *single public certificate* into an Integration Account. +```powershell +PS> Set-AzIntegrationAccountCertificates -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -CertificateType 'Public' -CertificateFilePath "C:\Certificates\MyCertificate.cer" +# Uploading certificate 'MyCertificate.cer' into the Azure Integration Account 'my-integration-account' +# Certificate 'MyCertificate.cer' has been uploaded into the Azure Integration Account 'my-integration-account' +``` + +Uploading a *single public certificate* into an Integration Account and set add a prefix to the name of the certificate within the Integration Account. +```powershell +PS> Set-AzIntegrationAccountCertificates -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -CertificateType 'Public' -CertificateFilePath "C:\Certificates\MyCertificate.cer" -ArtifactsPrefix 'dev-' +# Uploading certificate 'dev-MyCertificate.cer' into the Azure Integration Account 'my-integration-account' +# Certificate 'dev-MyCertificate.cer' has been uploaded into the Azure Integration Account 'my-integration-account' +``` + +Uploading *all public certificates* located in a specific folder into an Integration Account. +```powershell +PS> Set-AzIntegrationAccountCertificates -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -CertificateType 'Public' -CertificatesFolder "C:\Certificates" +# Uploading certificate 'MyFirstCertificate.cer' into the Azure Integration Account 'my-integration-account' +# Certificate 'MyFirstCertificate.cer' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +# Uploading certificate 'MySecondCertificate.cer' into the Azure Integration Account 'my-integration-account' +# Certificate 'MySecondCertificate.cer' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +``` + +Uploading *all public assemblies* located in a specific folder into an Integration Account and set add a prefix to the name of the certificates. +```powershell +PS> Set-AzIntegrationAccountCertificates -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -CertificateType 'Public' -CertificatesFolder "C:\Certificates" -ArtifactsPrefix 'dev-' +# Uploading certificate 'dev-MyFirstCertificate.cer' into the Azure Integration Account 'my-integration-account' +# Certificate 'dev-MyFirstCertificate.cer' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +# Uploading certificate 'dev-MySecondCertificate.cer' into the Azure Integration Account 'my-integration-account' +# Certificate 'dev-MySecondCertificate.cer' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +``` + +Uploading a *single private certificate* into an Integration Account. +```powershell +PS> Set-AzIntegrationAccountCertificates -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -CertificateType 'Private' -CertificateFilePath "C:\Certificates\MyCertificate.cer" -KeyName 'MyKey' -KeyVersion 'MyKeyVersion' -KeyVaultId '/subscriptions//resourcegroups//providers/microsoft.keyvault/vaults/' +# Uploading certificate 'MyCertificate.cer' into the Azure Integration Account 'my-integration-account' +# Certificate 'MyCertificate.cer' has been uploaded into the Azure Integration Account 'my-integration-account' +``` + +Uploading a *single private certificate* into an Integration Account and set add a prefix to the name of the certificate within the Integration Account. +```powershell +PS> Set-AzIntegrationAccountCertificates -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -CertificateType 'Private' -CertificateFilePath "C:\Certificates\MyCertificate.cer" -ArtifactsPrefix 'dev-' -KeyName 'MyKey' -KeyVersion 'MyKeyVersion' -KeyVaultId '/subscriptions//resourcegroups//providers/microsoft.keyvault/vaults/' +# Uploading certificate 'dev-MyCertificate.cer' into the Azure Integration Account 'my-integration-account' +# Certificate 'dev-MyCertificate.cer' has been uploaded into the Azure Integration Account 'my-integration-account' +``` + +## Uploading partners into an Azure Integration Account + +Upload/update a single, or multiple partners into an Azure Integration Account. + +| Parameter | Mandatory | Description | +| ---------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The name of the Azure resource group where the Azure Integration Account is located. | +| `Name` | yes | The name of the Azure Integration Account into which the partners are to be uploaded/updated. | +| `PartnerFilePath` | conditional | The full path of a partner that should be uploaded/updated. (_Mandatory if `PartnersFolder` has not been specified_). | +| `PartnersFolder` | conditional | The path to a directory containing all partners that should be uploaded/updated. (_Mandatory if `PartnerFilePath` has not been specified_). | +| `ArtifactsPrefix` | no | The prefix, if any, that should be added to the partners before uploading/updating. | + +**Example** + +Uploading a *single partner* into an Integration Account. +```powershell +PS> Set-AzIntegrationAccountPartners -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -PartnerFilePath "C:\Partners\MyPartner.json" +# Uploading partner 'MyPartner.json' into the Azure Integration Account 'my-integration-account' +# Partner 'MyPartner.json' has been uploaded into the Azure Integration Account 'my-integration-account' +``` + +Uploading a *single partner* into an Integration Account and set add a prefix to the name of the partner within the Integration Account. +```powershell +PS> Set-AzIntegrationAccountPartners -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -PartnerFilePath "C:\Partners\MyPartner.json" -ArtifactsPrefix 'dev-' +# Uploading partner 'dev-MyPartner.json' into the Azure Integration Account 'my-integration-account' +# Partner 'dev-MyPartner.json' has been uploaded into the Azure Integration Account 'my-integration-account' +``` + +Uploading *all partners* located in a specific folder into an Integration Account. +```powershell +PS> Set-AzIntegrationAccountPartners -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -PartnersFolder "C:\Partners" +# Uploading partner 'MyFirstPartner.json' into the Azure Integration Account 'my-integration-account' +# Partner 'MyFirstPartner.json' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +# Uploading partner 'MySecondPartner.json' into the Azure Integration Account 'my-integration-account' +# Partner 'MySecondPartner.json' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +``` + +Uploading *all partners* located in a specific folder into an Integration Account and set add a prefix to the name of the partners. +```powershell +PS> Set-AzIntegrationAccountPartners -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -PartnersFolder "C:\Partners" -ArtifactsPrefix 'dev-' +# Uploading partner 'dev-MyFirstPartner.json' into the Azure Integration Account 'my-integration-account' +# Partner 'dev-MyFirstPartner.json' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +# Uploading partner 'dev-MySecondPartner.json' into the Azure Integration Account 'my-integration-account' +# Partner 'dev-MySecondPartner.json' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +``` + +**Partner JSON Example** +The partner definition is the JSON representation of your partner, this JSON definition can also be viewed in the Azure Portal using https://docs.microsoft.com/en-us/azure/logic-apps/logic-apps-enterprise-integration-partners#edit-a-partner and clicking on `Edit as JSON`. + +
+ + An example of this file + +```json +{ + "name": "MyPartner", + "properties": { + "partnerType": "B2B", + "content": { + "b2b": { + "businessIdentities": [ + { + "qualifier": "1", + "value": "12345" + }, + { + "qualifier": "1", + "value": "54321" + } + ] + } + } + } +} +``` + +
+ + +## Uploading agreements into an Azure Integration Account + +Upload/update a single, or multiple agreements into an Azure Integration Account. + +| Parameter | Mandatory | Description | +| ---------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The name of the Azure resource group where the Azure Integration Account is located. | +| `Name` | yes | The name of the Azure Integration Account into which the agreements are to be uploaded/updated. | +| `AgreementFilePath` | conditional | The full path of a agreement that should be uploaded/updated. (_Mandatory if `AgreementsFolder` has not been specified_). | +| `AgreementsFolder` | conditional | The path to a directory containing all agreements that should be uploaded/updated. (_Mandatory if `AgreementFilePath` has not been specified_). | +| `ArtifactsPrefix` | no | The prefix, if any, that should be added to the agreements before uploading/updating. | + +**Example** + +Uploading a *single agreement* into an Integration Account. +```powershell +PS> Set-AzIntegrationAccountAgreements -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -AgreementFilePath "C:\Agreements\MyAgreement.json" +# Uploading agreement 'MyAgreement' into the Azure Integration Account 'my-integration-account' +# Agreement 'MyAgreement' has been uploaded into the Azure Integration Account 'my-integration-account' +``` + +Uploading a *single agreement* into an Integration Account and set add a prefix to the name of the agreement within the Integration Account. +```powershell +PS> Set-AzIntegrationAccountAgreements -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -AgreementFilePath "C:\Agreements\MyAgreement.json" -ArtifactsPrefix 'dev-' +# Uploading agreement 'dev-MyAgreement' into the Azure Integration Account 'my-integration-account' +# Agreement 'dev-MyAgreement' has been uploaded into the Azure Integration Account 'my-integration-account' +``` + +Uploading *all agreements* located in a specific folder into an Integration Account. +```powershell +PS> Set-AzIntegrationAccountAgreements -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -AgreementsFolder "C:\Agreements" +# Uploading agreement 'MyFirstAgreement' into the Azure Integration Account 'my-integration-account' +# Agreement 'MyFirstAgreement' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +# Uploading agreement 'MySecondAgreement' into the Azure Integration Account 'my-integration-account' +# Agreement 'MySecondAgreement' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +``` + +Uploading *all agreements* located in a specific folder into an Integration Account and set add a prefix to the name of the agreements. +```powershell +PS> Set-AzIntegrationAccountAgreements -ResourceGroupName 'my-resource-group' -Name 'my-integration-account' -AgreementsFolder "C:\Agreements" -ArtifactsPrefix 'dev-' +# Uploading agreement 'dev-MyFirstAgreement' into the Azure Integration Account 'my-integration-account' +# Agreement 'dev-MyFirstAgreement' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +# Uploading agreement 'dev-MySecondAgreement' into the Azure Integration Account 'my-integration-account' +# Agreement 'dev-MySecondAgreement' has been uploaded into the Azure Integration Account 'my-integration-account' +# ---------- +``` + +**Agreement JSON Example** +The agreement definition is the JSON representation of your agreement, this JSON definition can also be viewed in the Azure Portal using https://docs.microsoft.com/en-us/azure/logic-apps/logic-apps-enterprise-integration-agreements#edit-an-agreement and clicking on `Edit as JSON`. + +
+ + An example of this file + +```json +{ + "name": "MyAgreement", + "properties": { + "hostPartner": "Partner1", + "guestPartner": "Partner2", + "hostIdentity": { + "qualifier": "1", + "value": "12345" + }, + "guestIdentity": { + "qualifier": "1", + "value": "98765" + }, + "agreementType": "AS2", + "content": { + "aS2": { + "receiveAgreement": { + "protocolSettings": { + "messageConnectionSettings": { + "ignoreCertificateNameMismatch": false, + "supportHttpStatusCodeContinue": true, + "keepHttpConnectionAlive": true, + "unfoldHttpHeaders": true + }, + "acknowledgementConnectionSettings": { + "ignoreCertificateNameMismatch": false, + "supportHttpStatusCodeContinue": false, + "keepHttpConnectionAlive": false, + "unfoldHttpHeaders": false + }, + "mdnSettings": { + "needMDN": false, + "signMDN": false, + "sendMDNAsynchronously": false, + "dispositionNotificationTo": "http://localhost", + "signOutboundMDNIfOptional": false, + "sendInboundMDNToMessageBox": true, + "micHashingAlgorithm": "SHA1" + }, + "securitySettings": { + "overrideGroupSigningCertificate": false, + "enableNRRForInboundEncodedMessages": false, + "enableNRRForInboundDecodedMessages": false, + "enableNRRForOutboundMDN": false, + "enableNRRForOutboundEncodedMessages": false, + "enableNRRForOutboundDecodedMessages": false, + "enableNRRForInboundMDN": false + }, + "validationSettings": { + "overrideMessageProperties": false, + "encryptMessage": false, + "signMessage": false, + "compressMessage": false, + "checkDuplicateMessage": false, + "interchangeDuplicatesValidityDays": 5, + "checkCertificateRevocationListOnSend": false, + "checkCertificateRevocationListOnReceive": false, + "encryptionAlgorithm": "DES3", + "signingAlgorithm": "Default" + }, + "envelopeSettings": { + "messageContentType": "text/plain", + "transmitFileNameInMimeHeader": false, + "fileNameTemplate": "%FILE().ReceivedFileName%", + "suspendMessageOnFileNameGenerationError": true, + "autogenerateFileName": false + }, + "errorSettings": { + "suspendDuplicateMessage": false, + "resendIfMDNNotReceived": false + } + }, + "senderBusinessIdentity": { + "qualifier": "1", + "value": "9876" + }, + "receiverBusinessIdentity": { + "qualifier": "1", + "value": "1234" + } + }, + "sendAgreement": { + "protocolSettings": { + "messageConnectionSettings": { + "ignoreCertificateNameMismatch": false, + "supportHttpStatusCodeContinue": true, + "keepHttpConnectionAlive": true, + "unfoldHttpHeaders": true + }, + "acknowledgementConnectionSettings": { + "ignoreCertificateNameMismatch": false, + "supportHttpStatusCodeContinue": false, + "keepHttpConnectionAlive": false, + "unfoldHttpHeaders": false + }, + "mdnSettings": { + "needMDN": false, + "signMDN": false, + "sendMDNAsynchronously": false, + "dispositionNotificationTo": "http://localhost", + "signOutboundMDNIfOptional": false, + "sendInboundMDNToMessageBox": true, + "micHashingAlgorithm": "SHA1" + }, + "securitySettings": { + "overrideGroupSigningCertificate": false, + "enableNRRForInboundEncodedMessages": false, + "enableNRRForInboundDecodedMessages": false, + "enableNRRForOutboundMDN": false, + "enableNRRForOutboundEncodedMessages": false, + "enableNRRForOutboundDecodedMessages": false, + "enableNRRForInboundMDN": false + }, + "validationSettings": { + "overrideMessageProperties": false, + "encryptMessage": false, + "signMessage": false, + "compressMessage": false, + "checkDuplicateMessage": false, + "interchangeDuplicatesValidityDays": 5, + "checkCertificateRevocationListOnSend": false, + "checkCertificateRevocationListOnReceive": false, + "encryptionAlgorithm": "DES3", + "signingAlgorithm": "Default" + }, + "envelopeSettings": { + "messageContentType": "text/plain", + "transmitFileNameInMimeHeader": false, + "fileNameTemplate": "%FILE().ReceivedFileName%", + "suspendMessageOnFileNameGenerationError": true, + "autogenerateFileName": false + }, + "errorSettings": { + "suspendDuplicateMessage": false, + "resendIfMDNNotReceived": false + } + }, + "senderBusinessIdentity": { + "qualifier": "1", + "value": "1234" + }, + "receiverBusinessIdentity": { + "qualifier": "1", + "value": "9876" + } + } + } + } + } +} +``` + +
diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-key-vault.md b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-key-vault.md new file mode 100644 index 00000000..97fdf7e3 --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-key-vault.md @@ -0,0 +1,98 @@ +--- +title: "Azure Key Vault" +layout: default +--- + +# Azure Key Vault + +This module provides the following capabilities: +- [Azure Key Vault](#azure-key-vault) + - [Installation](#installation) + - [Getting all access policies for an Azure Key Vault](#getting-all-access-policies-for-an-azure-key-vault) + - [Setting a secret value from file into Azure Key Vault](#setting-a-secret-value-from-file-into-azure-key-vault) + - [Setting a secret value with BASE64 encoded file-content into Azure Key Vault](#setting-a-secret-value-with-base64-encoded-file-content-into-azure-key-vault) + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +PS> Install-Module -Name Arcus.Scripting.KeyVault +``` + +## Getting all access policies for an Azure Key Vault + +Lists the current available access policies of the Azure Key Vault resource. + +| Parameter | Mandatory | Description | +| ------------------- | --------- | ---------------------------------------------------------------------------- | +| `KeyVaultName` | yes | The name of the key vault from which the access policies are to be retrieved | +| `ResourceGroupName` | no | The resource group containing the key vault | + +**Example** + +```powershell +PS> $accessPolicies = Get-AzKeyVaultAccessPolicies -KeyVaultName "my-key-vault" +# Looking for the Azure Key Vault with name 'my-key-vault'... +# Found Azure Key Vault 'my-key-vault' +# accessPolicies: {list: [{tenantId: ...,permissions: ...}]} +``` + +```powershell +PS> $accessPolicies = Get-AzKeyVaultAccessPolicies -KeyVaultName "my-key-vault" -ResourceGroupName "my-resource-group" +# Looking for the Azure Key Vault with name 'my-key-vault' in resource group 'my-resource-group'... +# Found Azure Key Vault 'my-key-vault' +# accessPolicies: {list: [{tenantId: ...,permissions: ...}]} +``` + +## Setting a secret value from file into Azure Key Vault + +Sets a secret certificate from a file as plain text in Azure Key Vault. + +| Parameter | Mandatory | Description | +| -------------- | --------- | ------------------------------------------------------------------------------------ | +| `KeyVaultName` | yes | The name of the Azure Key Vault where the secret should be added | +| `SecretName` | yes | The name of the secret to add in the Azure Key Vault | +| `FilePath` | yes | The path to the file containing the secret certificate to add in the Azure Key Vault | +| `Expires` | no | The optional expiration date of the secret to add in the Azure Key Vault | + +**Example** +```powershell +PS> Set-AzKeyVaultSecretFromFile -KeyVaultName "my-key-vault" -SecretName "my-secret" -FilePath "/file-path/secret-certificate.pfx" +# Creating Azure Key Vault secret from file... +# Azure Key Vault Secret 'my-secret' (Version: 'new-secret-version') has been created +``` + +And with expiration date: +```powershell +PS> Set-AzKeyVaultSecretFromFile -FilePath "/file-path/secret-certificate.pfx" -SecretName "my-secret" -Expires [Datetime]::ParseExact('07/15/2019', 'MM/dd/yyyy', $null) -KeyVaultName "my-key-vault" +# Creating Azure Key Vault secret from file... +# Azure Key Vault Secret 'my-secret' (Version: 'new-secret-version') has been created +``` + +## Setting a secret value with BASE64 encoded file-content into Azure Key Vault + +Uploads the content of a file as a Base64 encoded string, as plain text, into an Azure Key Vault secret. +Can be useful when having to refer to a certificate from within an ARM-template. + +| Parameter | Mandatory | Description | +| -------------- | --------- | ------------------------------------------------------------------------------------ | +| `KeyVaultName` | yes | The name of the Azure Key Vault where the secret should be added | +| `SecretName` | yes | The name of the secret to add in the Azure Key Vault | +| `FilePath` | yes | The path to the file containing the secret certificate to add in the Azure Key Vault | +| `Expires` | no | The optional expiration date of the secret to add in the Azure Key Vault | + +**Example** +```powershell +PS> Set-AzKeyVaultSecretAsBase64FromFile -KeyVaultName "my-key-vault" -SecretName "my-secret" -FilePath "/file-path/secret-certificate.pfx" +# Creating Azure Key Vault secret from file... +# Use BASE64 format as secret format +# Azure Key Vault Secret 'my-secret' (Version: 'new-secret-version') has been created +``` + +And with expiration date: +```powershell +PS> Set-AzKeyVaultSecretAsBase64FromFile -FilePath "/file-path/secret-certificate.pfx" -SecretName "my-secret" -Expires [Datetime]::ParseExact('07/15/2019', 'MM/dd/yyyy', $null) -KeyVaultName "my-key-vault" +# Creating Azure Key Vault secret from file... +# Azure Key Vault Secret 'my-secret' (Version: 'new-secret-version') has been created +``` diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-logic-apps.md b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-logic-apps.md new file mode 100644 index 00000000..a385e07c --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-logic-apps.md @@ -0,0 +1,426 @@ +--- +title: " Azure Logic Apps" +layout: default +--- + +# Azure Logic Apps + +This module provides the following capabilities: +- [Azure Logic Apps](#azure-logic-apps) + - [Installation](#installation) + - [Disable an Azure Logic App](#disable-an-azure-logic-app) + - [Enable an Azure Logic App](#enable-an-azure-logic-app) + - [Disabling Azure Logic Apps from configuration file](#disabling-azure-logic-apps-from-configuration-file) + - [Enabling Azure Logic Apps from configuration file](#enabling-azure-logic-apps-from-configuration-file) + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +PS> Install-Module -Name Arcus.Scripting.LogicApps +``` + +## Disable an Azure Logic App + +Using this script to enable a specific Azure Logic App. + +| Parameter | Mandatory | Description | +| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------- | +| EnvironmentName | no | The name of the Azure environment where the Azure Logic App resides. (default: `AzureCloud`) | +| SubscriptionId | no | The Id of the subscription containing the Azure Logic App. | +| | | When not provided, it will be retrieved from the current context (Get-AzContext). | +| ResourceGroupName | yes | The resource group containing the Azure Logic Apps. | +| LogicAppName | yes | The name of the Azure Logic App to be disabled. | +| ApiVersion | no | The version of the management API to be used. (default: `2016-06-01`) | +| AccessToken | no | The access token to be used to disable the Azure Logic App. | +| | | When not provided, it will be retrieved from the current context (Get-AzContext). | + +**Example** + +Taking an example in which a specific Azure Logic Apps (`"rcv-shopping-order-sftp"`) needs to be disabled, without providing the subscriptionId or accesstoken. + +```powershell +PS> Disable-AzLogicApp -ResourceGroupName "rg-common-dev" -LogicAppName "rcv-shopping-order-sftp" +# Access-token and subscriptionId retrieved +# Attempting to disable rcv-shopping-order-sftp + +# Successfully disabled rcv-shopping-order-sftp +``` + +Taking an example in which a specific Azure Logic Apps (`"rcv-shopping-order-sftp"`) needs to be disabled, with providing the subscriptionId or accesstoken. + +```powershell +PS> Disable-AzLogicApp -SubscriptionId $SubscriptionId -ResourceGroupName "rg-common-dev" -LogicAppName "rcv-shopping-order-sftp" -AccessToken $AccessToken +# Attempting to disable rcv-shopping-order-sftp + +# Successfully disabled rcv-shopping-order-sftp +``` + +## Enable an Azure Logic App + +Using this script to enable a specific Azure Logic App. + +| Parameter | Mandatory | Description | +| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------- | +| EnvironmentName | no | The name of the Azure environment where the Azure Logic App resides. (default: `AzureCloud`) | +| SubscriptionId | no | The Id of the subscription containing the Azure Logic App. | +| | | When not provided, it will be retrieved from the current context (Get-AzContext). | +| ResourceGroupName | yes | The resource group containing the Azure Logic Apps. | +| LogicAppName | yes | The name of the Azure Logic App to be enabled. | +| ApiVersion | no | The version of the management API to be used. (default: `2016-06-01`) | +| AccessToken | no | The access token to be used to enable the Azure Logic App. | +| | | When not provided, it will be retrieved from the current context (Get-AzContext). | + +**Example** + +Taking an example in which a specific Azure Logic Apps (`"rcv-shopping-order-sftp"`) needs to be enabled, without providing the subscriptionId or accesstoken. + +```powershell +PS> Enable-AzLogicApp -ResourceGroupName "rg-common-dev" -LogicAppName "rcv-shopping-order-sftp" +# Access-token and subscriptionId retrieved +# Attempting to enable rcv-shopping-order-sftp + +# Successfully enabled rcv-shopping-order-sftp +``` + +Taking an example in which a specific Azure Logic Apps (`"rcv-shopping-order-sftp"`) needs to be enabled, with providing the subscriptionId or accesstoken. + +```powershell +PS> Enable-AzLogicApp -SubscriptionId $SubscriptionId -ResourceGroupName "rg-common-dev" -LogicAppName "rcv-shopping-order-sftp" -AccessToken $AccessToken +# Attempting to enable rcv-shopping-order-sftp + +# Successfully enabled rcv-shopping-order-sftp +``` + +## Disabling Azure Logic Apps from configuration file + +Typically done the first task of the release pipeline, right before the deployment of the Logic Apps, will disable all specified Logic Apps in a specific order. +The Azure Logic Apps to be disabled and the order in which this will be done, will be defined in the provided configuration file. +The order of the Azure Logic Apps in the configuration file (bottom to top) defines the order in which they will be disabled by the script. The counterpart of this script used to enable the Azure Logic Apps, will take the order as specified (top to bottom) in the file. + +| Parameter | Mandatory | Description | +| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------- | +| ResourceGroupName | yes | The resource group containing the Azure Logic Apps. | +| DeployFileName | no | If your solution consists of multiple interfaces, you can specify the flow-specific name of the configuration file. | +| ResourcePrefix | no | In case the Azure Logic Apps all start with the same prefix, you can specify this prefix through this parameter | +| | | instead of updating the configuration-file. | +| EnvironmentName | no | The name of the Azure environment where the Azure Logic App resides. (default: `AzureCloud`) | +| ApiVersion | no | The version of the management API to be used. (default: `2016-06-01`) | + +The schema of this configuration file is a JSON structure of an array with the following inputs: + +| Node | Type | Description | +| ----------- | --------------- | --------------------------------------------------------------------------------------------------------------------- | +| Description | `string` | Description of Azure Logic App set to disable. | +| CheckType | `enum` | `None`: don't perform any additional checks. | +| | | `NoWaitingOrRunningRuns`: waits until there are no more waiting or running Logic App instances. | +| StopType | `enum` | `None`: don't disable to given Logic Apps. | +| | | `Immediate`: disable the given Logic Apps. | +| LogicApps | `string array` | Set of Logic App names to disable. | + +**Example** + +Taking an example in which a set of Azure Logic Apps (`"rcv-shopping-order-*"`) need to be disabled, the following configuration will not take into account any active Logic Apps runs (`checkType = None`) and will immediately disable them (`stopType = Immediate`), starting with the _receive protocol_ instances and working its way up to the _sender_ Logic App. + +```json +[ + { + "description": "Sender(s)", + "checkType": "None", + "stopType": "Immediate", + "logicApps": [ + "snd-shopping-order-confirmation-smtp" + ] + }, + { + "description": "Orchestrator(s)", + "checkType": "None", + "stopType": "Immediate", + "logicApps": [ + "orc-shopping-order-processing" + ] + }, + { + "description": "Generic Receiver(s)", + "checkType": "None", + "stopType": "Immediate", + "logicApps": [ + "rcv-shopping-order" + ] + }, + { + "description": "Protocol Receiver(s)", + "checkType": "None", + "stopType": "Immediate", + "logicApps": [ + "rcv-shopping-order-ftp", + "rcv-shopping-order-sftp", + "rcv-shopping-order-file" + ] + } +] +``` + +**Example** + +Disables all the Logic Apps based on the `./deploy-orderControl.json` configuration file. +Uses the sample configuration file here above. + +```powershell +PS> Disable-AzLogicAppsFromConfig -DeployFilename "./deploy-orderControl" -ResourceGroupName "my-resource-group" +# Executing batch: Protocol Receiver(s) +# ========================== +# > Executing CheckType 'None' for batch 'Protocol Receiver(s)' in resource group 'my-resource-group'" +# Executing Check 'None' => performing no check and executing stopType + +# > Executing StopType 'Immediate' for Logic App 'rcv-shopping-order-ftp' in resource group 'my-resource-group' +# Attempting to disable rcv-shopping-order-ftp +# Successfully disabled rcv-shopping-order-ftp + +# > Executing StopType 'Immediate' for Logic App 'rcv-shopping-order-sftp' in resource group 'my-resource-group' +# Attempting to disable rcv-shopping-order-sftp +# Successfully disabled rcv-shopping-order-sftp + +# > Executing StopType 'Immediate' for Logic App 'rcv-shopping-order-file' in resource group 'my-resource-group' +# Attempting to disable rcv-shopping-order-file +# Successfully disabled rcv-shopping-order-file + +# -> Batch: 'Protocol Receiver(s)' has been executed + +# Executing batch: 'Generic Receiver(s)' +# ========================== +# > Executing StopType 'Immediate' for Logic App 'rcv-shopping-order' in resource group 'my-resource-group' +# Attempting to disable rcv-shopping-order +# Successfully disabled rcv-shopping-order + +# -> Batch: 'Generic Receiver(s)' has been executed + +# Executing batch: 'Orchestrator(s)' +# ========================== +# > Executing StopType 'Immediate' for Logic App 'orc-shopping-order-processing' in resource group 'my-resource-group' +# Attempting to disable orc-shopping-order-processing +# Successfully disabled orc-shopping-order-processing + +# -> Batch: 'Orchestrator(s)' has been executed + +# Executing batch: 'Sender(s)' +# ========================== +# > Executing StopType 'Immediate' for Logic App 'snd-shopping-order-confirmation-smtp' in resource group 'my-resource-group' +# Attempting to disable snd-shopping-order-confirmation-smtp +# Successfully disabled snd-shopping-order-confirmation-smtp + +# -> Batch: 'Sender(s)' has been executed +``` + +Disables all the Logic Apps based on the `./deploy-orderControl.json` configuration file with specifying a resource-prefix. +Uses the sample configuration file here above. + +```powershell +PS> Disable-AzLogicAppsFromConfig -DeployFilename "./deploy-orderControl" -ResourceGroupName "my-resource-group" -ResourcePrefix "la-cod-dev-we-" +# Executing batch: Protocol Receiver(s) +# ========================== +# > Executing CheckType 'None' for batch 'Protocol Receiver(s)' in resource group 'my-resource-group'" +# Executing Check 'None' => performing no check and executing stopType + +# > Executing StopType 'Immediate' for Logic App 'la-cod-dev-we-rcv-shopping-order-ftp' in resource group 'my-resource-group' +# Attempting to disable la-cod-dev-we-rcv-shopping-order-ftp +# Successfully disabled la-cod-dev-we-rcv-shopping-order-ftp + +# > Executing StopType 'Immediate' for Logic App 'la-cod-dev-we-rcv-shopping-order-sftp' in resource group 'my-resource-group' +# Attempting to disable la-cod-dev-we-rcv-shopping-order-sftp +# Successfully disabled la-cod-dev-we-rcv-shopping-order-sftp + +# > Executing StopType 'Immediate' for Logic App 'la-cod-dev-we-rcv-shopping-order-file' in resource group 'my-resource-group' +# Attempting to disable la-cod-dev-we-rcv-shopping-order-file +# Successfully disabled la-cod-dev-we-rcv-shopping-order-file + +# -> Batch: 'Protocol Receiver(s)' has been executed + +# Executing batch: 'Generic Receiver(s)' +# ========================== +# > Executing StopType 'Immediate' for Logic App 'la-cod-dev-we-rcv-shopping-order' in resource group 'my-resource-group' +# Attempting to disable la-cod-dev-we-rcv-shopping-order +# Successfully disabled la-cod-dev-we-rcv-shopping-order + +# -> Batch: 'Generic Receiver(s)' has been executed + +# Executing batch: 'Orchestrator(s)' +# ========================== +# > Executing StopType 'Immediate' for Logic App 'la-cod-dev-we-orc-shopping-order-processing' in resource group 'my-resource-group' +# Attempting to disable la-cod-dev-we-orc-shopping-order-processing +# Successfully disabled la-cod-dev-we-orc-shopping-order-processing + +# -> Batch: 'Orchestrator(s)' has been executed + +# Executing batch: 'Sender(s)' +# ========================== +# > Executing StopType 'Immediate' for Logic App 'la-cod-dev-we-snd-shopping-order-confirmation-smtp' in resource group 'my-resource-group' +# Attempting to disable la-cod-dev-we-snd-shopping-order-confirmation-smtp +# Successfully disabled la-cod-dev-we-snd-shopping-order-confirmation-smtp + +# -> Batch: 'Sender(s)' has been executed +``` + +## Enabling Azure Logic Apps from configuration file + +Typically done as the last task of the release pipeline, right after the deployment of the Logic Apps, as this will enable all specified Logic Apps in a specific order. +The Azure Logic Apps to be enabled and the order in which this will be done, will be defined in the provided configuration file. +The order of the Azure Logic Apps in the configuration file (top to bottom) defines the order in which they will be enabled by the script. The counterpart of this script used to disable the Azure Logic Apps, will take the reversed order as specified (bottom to top) in the file. + +| Parameter | Mandatory | Description | +| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------- | +| ResourceGroupName | yes | The resource group containing the Azure Logic Apps. | +| DeployFileName | no | If your solution consists of multiple interfaces, you can specify the flow-specific name of the configuration file. | +| ResourcePrefix | no | In case the Azure Logic Apps all start with the same prefix, you can specify this prefix through this parameter | +| | | instead of updating the configuration-file. | +| EnvironmentName | no | The name of the Azure environment where the Azure Logic App resides. (default: `AzureCloud`) | +| ApiVersion | no | The version of the management API to be used. (default: `2016-06-01`) | + +The schema of this configuration file is a JSON structure of an array with the following inputs: + +| Node | Type | Description | +| ----------- | --------------- | --------------------------------------------------------------------------------------------------------------------- | +| Description | `string` | Description of Azure Logic App set to enable. | +| CheckType | `enum` | _Not taken into account for enabling Logic Apps._ | +| StopType | `enum` | `None`: don't enable to given Logic Apps. | +| | | `Immediate`: enable the given Logic Apps. | +| LogicApps | `string array` | Set of Logic App names to enable. | + +**Example** + +Taking an example in which a set of Azure Logic Apps (`"rcv-shopping-order-*"`) need to be enabled, the following configuration will ignore the `checkType`, as this is only used for disabling the Logic Apps, and will simply enable them (`stopType = Immediate`), starting with the _sender_ instances and working its way down to the _receive protocol_ Logic Apps. +This ensures that all of the down-stream Logic Apps are enabled by the time the initial/trigger Logic App have been activated. + +```json +[ + { + "description": "Sender(s)", + "checkType": "None", + "stopType": "Immediate", + "logicApps": [ + "snd-shopping-order-confirmation-smtp" + ] + }, + { + "description": "Orchestrator(s)", + "checkType": "None", + "stopType": "Immediate", + "logicApps": [ + "orc-shopping-order-processing" + ] + }, + { + "description": "Generic Receiver(s)", + "checkType": "None", + "stopType": "Immediate", + "logicApps": [ + "rcv-shopping-order" + ] + }, + { + "description": "Protocol Receiver(s)", + "checkType": "None", + "stopType": "Immediate", + "logicApps": [ + "rcv-shopping-order-ftp", + "rcv-shopping-order-sftp", + "rcv-shopping-order-file" + ] + } +] +``` + +**Example** + +Enables all the Logic Apps based on the `./deploy-orderControl.json` configuration file. +Uses the sample configuration file here above. + +```powershell +PS> Enable-AzLogicAppsFromConfig -DeployFilename "./deploy-orderControl" -ResourceGroupName "my-resource-group" +# Executing batch: 'Sender(s)' +# ========================== +# > Reverting StopType 'Immediate' for Logic App 'snd-shopping-order-confirmation-smtp' in resource group 'my-resource-group' +# Attempting to enable snd-shopping-order-confirmation-smtp +# Successfully enabled snd-shopping-order-confirmation-smtp + +# -> Batch: 'Sender(s)' has been executed + +# Executing batch: 'Orchestrator(s)' +# ========================== +# > Reverting StopType 'Immediate' for Logic App 'orc-shopping-order-processing' in resource group 'my-resource-group' +# Attempting to enable orc-shopping-order-processing +# Successfully enabled orc-shopping-order-processing + +# -> Batch: 'Orchestrator(s)' has been executed + +# Executing batch: 'Generic Receiver(s)' +# ========================== +# > Reverting StopType 'Immediate' for Logic App 'rcv-shopping-order' in resource group 'my-resource-group' +# Attempting to enable rcv-shopping-order +# Successfully enabled rcv-shopping-order + +# -> Batch: 'Generic Receiver(s)' has been executed + +# Executing batch: Protocol Receiver(s) +# ========================== +# > Reverting StopType 'Immediate' for Logic App 'rcv-shopping-order-ftp' in resource group 'my-resource-group' +# Attempting to enable rcv-shopping-order-ftp +# Successfully enabled rcv-shopping-order-ftp + +# > Reverting StopType 'Immediate' for Logic App 'rcv-shopping-order-sftp' in resource group 'my-resource-group' +# Attempting to enable rcv-shopping-order-sftp +# Successfully enabled rcv-shopping-order-sftp + +# > Reverting StopType 'Immediate' for Logic App 'rcv-shopping-order-file' in resource group 'my-resource-group' +# Attempting to enable rcv-shopping-order-file +# Successfully enabled rcv-shopping-order-file + +# -> Batch: 'Protocol Receiver(s)' has been executed +``` + +Enables all the Logic Apps based on the `./deploy-orderControl.json` configuration file with specifying a resource-prefix. +Uses the sample configuration file here above. + +```powershell +PS> Enable-AzLogicAppsFromConfig -DeployFilename "./deploy-orderControl" -ResourceGroupName "my-resource-group" -ResourcePrefix "la-cod-dev-we-" +# Executing batch: 'Sender(s)' +# ========================== +# > Reverting StopType 'Immediate' for Logic App 'la-cod-dev-we-snd-shopping-order-confirmation-smtp' in resource group 'my-resource-group' +# Attempting to enable la-cod-dev-we-snd-shopping-order-confirmation-smtp +# Successfully enabled la-cod-dev-we-snd-shopping-order-confirmation-smtp + +# -> Batch: 'Sender(s)' has been executed + +# Executing batch: 'Orchestrator(s)' +# ========================== +# > Reverting StopType 'Immediate' for Logic App 'la-cod-dev-we-orc-shopping-order-processing' in resource group 'my-resource-group' +# Attempting to enable la-cod-dev-we-orc-shopping-order-processing +# Successfully enabled la-cod-dev-we-orc-shopping-order-processing + +# -> Batch: 'Orchestrator(s)' has been executed + +# Executing batch: 'Generic Receiver(s)' +# ========================== +# > Reverting StopType 'Immediate' for Logic App 'la-cod-dev-we-rcv-shopping-order' in resource group 'my-resource-group' +# Attempting to enable la-cod-dev-we-rcv-shopping-order +# Successfully enabled la-cod-dev-we-rcv-shopping-order + +# -> Batch: 'Generic Receiver(s)' has been executed + +# Executing batch: Protocol Receiver(s) +# ========================== +# > Reverting StopType 'Immediate' for Logic App 'la-cod-dev-we-rcv-shopping-order-ftp' in resource group 'my-resource-group' +# Attempting to enable la-cod-dev-we-rcv-shopping-order-ftp +# Successfully enabled la-cod-dev-we-rcv-shopping-order-ftp + +# > Reverting StopType 'Immediate' for Logic App 'la-cod-dev-we-rcv-shopping-order-sftp' in resource group 'my-resource-group' +# Attempting to enable la-cod-dev-we-rcv-shopping-order-sftp +# Successfully enabled la-cod-dev-we-rcv-shopping-order-sftp + +# > Reverting StopType 'Immediate' for Logic App 'la-cod-dev-we-rcv-shopping-order-file' in resource group 'my-resource-group' +# Attempting to enable la-cod-dev-we-rcv-shopping-order-file +# Successfully enabled la-cod-dev-we-rcv-shopping-order-file + +# -> Batch: 'Protocol Receiver(s)' has been executed +``` diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-management.md b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-management.md new file mode 100644 index 00000000..966d9f98 --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-management.md @@ -0,0 +1,72 @@ +--- +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' +``` diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-security.md b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-security.md new file mode 100644 index 00000000..ff08d46e --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-security.md @@ -0,0 +1,109 @@ +--- +title: "Azure security" +layout: default +--- + +# Azure Security + +This module provides the following capabilities: +- [Azure Security](#azure-security) + - [Installation](#installation) + - [Removing resource locks from an Azure resource group](#removing-resource-locks-from-an-azure-resource-group) + - [Retrieving the current Az Access token](#retrieving-the-current-az-access-token) + - [Granting a resource access to all resources within a specific resource group](#granting-a-resource-access-to-all-resources-within-a-specific-resource-group) + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +PS> Import-Module -Name Arcus.Scripting.Security +``` + +## Removing resource locks from an Azure resource group + +In some deployments resource-locks are being assigned. To help in removing these quickly, we have provided you with a function that removes all the existing locks on the resource group. + +While this seems dangerous, only users with sufficient access rights are allowed to delete locks. + +| Parameter | Mandatory | Description | +| ------------------- | --------- | ------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The name of the resource group where the locks should be removed | +| `LockName` | no | The optional name of the lock to remove. When this is not provided, all the locks will be removed | + +**Usage** + +When you want to remove all the resource locks, no matter what the name or the sub-location: + +```powershell +PS> Remove-AzResourceGroupLocks -ResourceGroupName "your-resource-group-name" +# Retrieving all locks in resourceGroup 'your-resource-group-name' +# Start removing all locks in resourceGroup 'your-resource-group-name' +# Removing the lock: 'some resource lock 1' +# Removing the lock: 'some resource lock 2' +# All locks in resourceGroup 'your-resource-group-name' have been removed +``` + +When you want to remove a specific resource lock, with a given name: + +```powershell +PS> Remove-AzResourceGroupLocks -ResourceGroupName "your-resource-group-name" -LockName "your-resource-lock-name" +# Retrieving all locks in resourceGroup 'your-resource-group-name' with name 'your-resource-lock-name' +# Start removing all locks in resourceGroup 'your-resource-group-name' +# Removing the lock: 'your-resource-lock-name' +# All locks in resourceGroup 'your-resource-group-name' have been removed +``` + +## Retrieving the current Az Access token + +When you want to make use of the REST-API's made available to manage Azure Resources, you can use this command to easily retrieve the access-token which is stored in your cache after performing the `Connect-AzAccount` command. + +| Parameter | Mandatory | Description | +| ----------------------- | --------- | ------------------------------------------------------------------------------------------------- | +| `AssignGlobalVariables` | no | Indicator (switch - default value: false) whether you want the global variables `access_token` and `subscriptionId` assigned for easy access. | + +**Usage** + +When you want to retrieve the current access-token, after connecting to a specific subscription: + +```powershell +PS> $token = Get-AzCachedAccessToken +# Azure access token and subscription ID retrieved from current active Azure authenticated session +PS> Write-Host "Current SubscriptionId:" $token.SubscriptionId +# Current SubscriptionId: b1a8131b-35fb-4d49-b77b-11abd21c9dcb +PS> Write-Host "Current AccessToken:" $token.AccessToken +# Current AccessToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c +``` + +When you want to retrieve the current access-token, after connecting to a specific subscription and assign them to global variables for easy access: + +```powershell +PS> $token = Get-AzCachedAccessToken -AssignGlobalVariables +# Global variable 'subscriptionId' assigned +# Global variable 'accessToken' assigned +# Azure access token and subscription ID retrieved from current active Azure authenticated session +PS> Write-Host "Current SubscriptionId:" $Global:subscriptionId +# Current SubscriptionId: b1a8131b-35fb-4d49-b77b-11abd21c9dcb +PS> Write-Host "Current AccessToken:" $Global:accessToken +# Current AccessToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c +``` + +## Granting a resource access to all resources within a specific resource group + +In some cases, a resource needs to be granted access to all resources present within a specific resource group. +This function allows you to assign an Azure built-in role to a resource upon a resource group. + +| Parameter | Mandatory | Description | +| ------------------------- | ---------- | -------------------------------------------------------------------------------------------- | +| `TargetResourceGroupName` | yes | The name of the resource group to which access should be granted. | +| `ResourceGroupName` | yes | The name of the resource group where the resource is located which should be granted access. | +| `ResourceName` | yes | The name of the resource which should be granted access. | +| `RoleDefinitionName` | yes | The name of the role to assign. | + +**Usage** + +```powershell +PS> New-AzResourceGroupRoleAssignment -TargetResourceGroupName "to-gain-access-resource-group" -ResourceGroupName "to-assign-role-resource-group" -ResourceName "to-assign-resource" -RoleAssignmentDefinition "Contributor" +# Assigning Contributor-rights to the 'to-assign-role-resource' in the resource group 'to-assign-resource-group to gain access to the 'to-gain-access-resource-group' +# Contributor access granted! +``` diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-sql.md b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-sql.md new file mode 100644 index 00000000..20e9b75a --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-sql.md @@ -0,0 +1,76 @@ +--- +title: " Azure SQL" +layout: default +--- + +# Azure SQL + +This module provides the following capabilities: +- [Azure SQL](#azure-sql) + - [Installation](#installation) + - [Invoke a database migration](#invoke-a-database-migration) + - [Adding SQL scripts so they can be picked up by the script](#adding-sql-scripts-so-they-can-be-picked-up-by-the-script) + - [Compatibility](#compatibility) + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +PS> Install-Module -Name Arcus.Scripting.SQL +``` + +## Invoke a database migration + +With this script, you can perform database upgrades by providing/adding specific SQL scripts with the right version number. +Once a new version number is detected it will incrementally execute this. + +While doing so it will create a table "DatabaseVersion". +If the DatabaseVersion table doesn't exist it will automatically create it. + +This function allows you to trigger a database migration, which will only execute the newly provided SQL scripts, based on the provided version number in each of the scripts. +The current version is stored in a table "DatabaseVersion", which will be created if it doesn't exist yet. + +| Parameter | Mandatory | Description | +| ------------------- | --------------------------------------- | ----------------------------------------------------------------------------------- | +| `ServerName` | yes | The full name of the SQL Server that hosts the SQL Database. | +| `DatabaseName` | yes | The name of the SQL Database | +| `UserName` | yes | The UserName of the SQL Database | +| `Password` | yes | The Password of the SQL Database | +| `ScriptsFolder` | no (default: `$PSScriptRoot/sqlScripts` | The directory folder where the SQL migration scripts are located on the file system | +| `ScriptsFileFilter` | no (default: `*.sql`) | The file filter to limit the SQL script files to use during the migrations | +| `DatabaseSchema` | no (default: `dbo`) | The database schema to use when running SQL commands on the target database | + +Make sure that the credentials that you provide can write tables to the database + any action that you specify in the SQL scripts. (If the user is a member of the `db_ddlamin` role, then that user should have the necessary rights) + +**Example with defaults** + +```powershell +PS> Invoke-AzSqlDatabaseMigration -ServerName "my-server-name.database.windows.net" -DatabaseName "my-database-name" -Username "my-sql-username" -Password "my-sql-password" +# Looking for SQL scripts in folder: ./sqlScripts +``` + +**Example with custom values** + +```powershell +PS> Invoke-AzSqlDatabaseMigration -ServerName "my-server-name.database.windows.net" -DatabaseName "my-database-name" -Username "my-sql-username" -Password "my-sql-password" -ScriptsFolder "$PSScriptRoot/sql-scripts" -ScriptsFileFilter "*.MyScript.sql" -DatabaseSchema "custom" +# Looking for SQL scripts in folder: ./sql-scripts +``` + +### Adding SQL scripts so they can be picked up by the script + +1. In the location where you want to run the script add a folder where the migration scripts will be placed. By default, we're looking in a folder called `SqlScripts`, but this can be any folder as it is configurable via the `ScriptsFolder` argument. + +2. Add your database migration scripts in the folder that was created in the previous step. To be recognized by the module, the files must match with the following naming convention: +`[MajorVersionNumber].[MinorVersionNumber].[PatchVersionNumber]_[DescriptionOfMigration].sql` + +In practice this can look like this: +`1.0.0_Baseline.sql` +`1.1.0_AddIndexes.sql` +`1.1.1_PopulateCodetables.sql` + +When a new migration comes along, just create the new SQL script with a version number one number higher than the previous one. + +### Compatibility + +Semantic versioning of database-migrations is supported since version v0.5. Existing migration scripts that follow the old naming convention will be recognized and will be given this version-number: `[VersionNumber].0.0`. diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-storage/_category_.yml b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-storage/_category_.yml new file mode 100644 index 00000000..9d1c82b6 --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-storage/_category_.yml @@ -0,0 +1 @@ +label: 'Azure Storage' diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-storage/azure-storage-all.md b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-storage/azure-storage-all.md new file mode 100644 index 00000000..c45bafcd --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-storage/azure-storage-all.md @@ -0,0 +1,32 @@ +--- +title: "Azure Storage" +layout: default +sidebar_label: Installation +--- + +# Azure Storage + +This module contains several sub-modules, all related to Azure Storage. + +## Installation + +Install all Azure Storage-related modules at once via: + +```powershell +PS> Install-Module -Name Arcus.Scripting.Storage.All +``` + +## Azure Table Storage + +This sub-module contains scripts related to interacting with Azure Table Storage. +See the [dedicated docs](./azure-storage-table.md) for more information. + +## Azure Blob Storage + +This sub-module contains scripts related to interacting with the Azure Blob Storage. +See the [dedicated docs](./azure-storage-blob.md) for more information. + +## Azure File Share + +This sub-module contains scripts related to interacting with the Azure File Share. +See the [dedicated docs](./azure-storage-fileshare.md) for more information. diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-storage/azure-storage-blob.md b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-storage/azure-storage-blob.md new file mode 100644 index 00000000..4a82f744 --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-storage/azure-storage-blob.md @@ -0,0 +1,57 @@ +--- +title: " Azure Blob Storage" +layout: default +--- + +# Azure Blob Storage + +This module provides the following capabilities: +- [Azure Blob Storage](#azure-blob-storage) + - [Installation](#installation) + - [Uploading files to a Azure Storage Blob container](#uploading-files-to-a-azure-storage-blob-container) + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +PS> Install-Module -Name Arcus.Scripting.Storage.Blob +``` + +## Uploading files to a Azure Storage Blob container + +Uploads a set of files located in a given directory to a container on a Azure Blob Storage resource. + +| Parameter | Mandatory | Description | +| ---------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The name of the Azure resource group where the Azure storage account is located. | +| `StorageAccountName` | yes | The name of the Azure storage account. | +| `TargetFolderPath` | yes | The directory where the files are located to upload to Azure Blob Storage. | +| `ContainerName` | yes | The name of the container at Azure Blob Storage to upload the targeted files to. | +| `ContainerPermissions` | no | The level of public access to this container. By default, the container and any blobs in it can be accessed only by the owner of the storage account. To grant anonymous users read permissions to a container and its blobs, you can set the container permissions to enable public access. Anonymous users can read blobs in a publicly available container without authenticating the request. The acceptable values for this parameter are: | +| | | Container: Provides full read access to a container and its blobs. Clients can enumerate blobs in the container through anonymous request, but cannot enumerate containers in the storage account. | +| | | Blob: Provides read access to blob data throughout a container through anonymous request, but does not provide access to container data. Clients cannot enumerate blobs in the container by using anonymous request. | +| | | Off: Which restricts access to only the storage account owner. | +| `FilePrefix` | no | The optional prefix to append to the blob content when uploading the file in the targeted directory to Azure Blob Storage. | + +**Example** + +With existing blob container: + +```powershell +PS> Upload-AzFilesToBlobStorage -ResourceGroupName "resource-group" -StorageAccountName "account-name" -TargetFolderPath "./directory" -ContainerName "blob-container" +# Try using existing Azure Storage Container blob-container... +# Using existing Azure Storage Container blob-container +# Uploading files from ./directory +# Uploaded the file to Azure Blob Storage: [file] +``` + +With non-existing blob container: + +```powershell +PS> Upload-AzFilesToBlobStorage -ResourceGroupName "resource-group" -StorageAccountName "account-name" -TargetFolderPath "./directory" -ContainerName "blob-container" +# Try using existing Azure Storage Container blob-container... +# Creating Storage Container blob-container +# Uploading files from ./directory +# Uploaded the file to Azure Blob Storage: [file] +``` diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-storage/azure-storage-fileshare.md b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-storage/azure-storage-fileshare.md new file mode 100644 index 00000000..034fb037 --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-storage/azure-storage-fileshare.md @@ -0,0 +1,63 @@ +--- +title: " Azure Storage for file shares" +layout: default +--- + +# Azure Storage for file shares + +This module provides the following capabilities: +- [Azure Storage for file shares](#azure-storage-for-file-shares) + - [Installation](#installation) + - [Creating a folder on an Azure file share](#creating-a-folder-on-an-azure-file-share) + - [Uploading files to a folder on an Azure file share](#uploading-files-to-a-folder-on-an-azure-file-share) + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +PS> Install-Module -Name Arcus.Scripting.Storage.FileShare +``` + +## Creating a folder on an Azure file share + +Creates a new folder within the Azure File Share resource. +When a folder already exists with the provided name, it will be skipped. No exception will be thrown. + +| Parameter | Mandatory | Description | +| -------------------- | --------- | ----------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure File Share. | +| `StorageAccountName` | yes | The Azure Storage Account name that hosting the Azure File Share. | +| `FileShareName` | yes | The name of the Azure File Share. | +| `FolderName` | yes | The name of the folder to create in the Azure File Share. | + +**Example** + +```powershell +PS> Create-AzFileShareStorageFolder -ResourceGroupName "shipping-resources" -StorageAccountName "tracking-account-storage" -FileShareName "returned" -FolderName "containers" +# Creating Azure FileShare storage folder 'containers' in file share 'returned'.. +# Created Azure FileShare storage folder 'containers' in file share 'returned' +``` + +## Uploading files to a folder on an Azure file share + +Upload a set of files from a given folder, optionally matching a specific file mask, to an Azure File Share. + +| Parameter | Mandatory | Description | +| ----------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure File Share. | +| `StorageAccountName` | yes | The name of the Azure Storage account that is hosting the Azure File Share. | +| `FileShareName` | yes | The name of the Azure File Share. | +| `SourceFolderPath` | yes | The file directory where the targeted files are located. | +| `DestinationFolderName` | yes | The name of the destination folder on the Azure File Share where the targeted files will be uploaded. | +| `FileMask` | no | The file mask that filters out the targeted files at the source folder that will be uploaded to the Azure File Share. | + +**Example** + +```powershell +PS> Upload-AzFileShareStorageFiles -ResourceGroupName "shipping-resources" -StorageAccountName "tracking-account-storage" -FileShareName "returned" -SourceFolderPath "containers" -DestinationFolderName "containers" +# Upload files to Azure FileShare storage 'returned'... +# Uploaded the '[fileName]' file to Azure FileShare 'returned' +# Uploaded the '[fileName]' file to Azure FileShare 'returned' +# Files have been uploaded to Azure FileShare storage 'returned' +``` diff --git a/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-storage/azure-storage-table.md b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-storage/azure-storage-table.md new file mode 100644 index 00000000..986b1331 --- /dev/null +++ b/docs/versioned_docs/version-v0.7.0/02-Features/powershell/azure-storage/azure-storage-table.md @@ -0,0 +1,54 @@ +--- +title: " Azure Table Storage" +layout: default +--- + +# Azure Storage - Tables + +This module provides the following capabilities: +- [Azure Storage - Tables](#azure-storage---tables) + - [Installation](#installation) + - [Creating a new table in an Azure Storage Account](#creating-a-new-table-in-an-azure-storage-account) + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +PS> Install-Module -Name Arcus.Scripting.Storage.Table +``` + +## Creating a new table in an Azure Storage Account + +(Re)Create a Azure Table Storage within an Azure Storage Account. + +| Parameter | Mandatory | Description | +| ---------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group where the Azure Storage Account is located | +| `StorageAccountName` | yes | The name of the Azure Storage Account to add the table to | +| `TableName` | yes | The name of the table to add on the Azure Storage Account | +| `Recreate` | no | The optional flag to indicate whether or not a possible already existing table should be deleted and re-created | +| `RetryIntervalSeconds` | no | The optional amount of seconds to wait each retry-run when a failure occurs during the re-creating process (default: 5s) | +| `MaxRetryCount` | no | The optional maximum amount of retry-runs should happen when a failure occurs during the re-creating process (default: 10) | + +**Example** + +With non-existing table: + +```powershell +PS> Create-AzStorageTable -ResourceGroupName "stock" -StorageAccountName "admin" -TableName "products" +# Azure storage account context has been retrieved +# Azure storage table 'products' does not exist yet in the Azure storage account, so will create one +# Azure storage table 'products' created +``` + +With existing table and re-create: + +```powershell +PS> Create-AzStorageTable -ResourceGroupName "stock" -StorageAccountName "admin" -TableName "products" -Recreate -RetryIntervalSeconds 3 +# Azure storage account context has been retrieved +# Azure storage table 'products' has been removed +# Failed to re-create the Azure storage table 'products', retrying in 5 seconds... +# Failed to re-create the Azure storage table 'products', retrying in 5 seconds... +# Azure storage table 'products' created +``` diff --git a/docs/versioned_sidebars/version-v0.7.0-sidebars.json b/docs/versioned_sidebars/version-v0.7.0-sidebars.json new file mode 100644 index 00000000..6fb4db3b --- /dev/null +++ b/docs/versioned_sidebars/version-v0.7.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "version-v0.7.0/tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/docs/versions.json b/docs/versions.json index 6813e2bd..c1ceacac 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,4 +1,5 @@ [ + "v0.7.0", "v0.6.0", "v0.5", "v0.4.3",