From 2673c44a5e71e9c7f3b015a6f05b5a73181e3601 Mon Sep 17 00:00:00 2001 From: Pim Simons Date: Mon, 3 Jul 2023 10:26:13 +0200 Subject: [PATCH] add v1.1.0 docs --- .../versioned_docs/version-v1.1.0/01-index.md | 18 + .../02-Guidelines/Installation.md | 16 + ...-outputs-to-azure-devops-variable-group.md | 95 +++ .../powershell/azure-active-directory.md | 122 ++++ .../powershell/azure-api-management.md | 382 +++++++++++ .../powershell/azure-app-service.md | 42 ++ .../powershell/azure-data-factory.md | 75 +++ .../03-Features/powershell/azure-devops.md | 230 +++++++ .../powershell/azure-integration-account.md | 611 ++++++++++++++++++ .../03-Features/powershell/azure-key-vault.md | 101 +++ .../powershell/azure-logic-apps.md | 429 ++++++++++++ .../powershell/azure-management.md | 60 ++ .../03-Features/powershell/azure-security.md | 107 +++ .../03-Features/powershell/azure-sql.md | 82 +++ .../powershell/azure-storage/_category_.yml | 1 + .../azure-storage/azure-storage-all.md | 32 + .../azure-storage/azure-storage-blob.md | 54 ++ .../azure-storage/azure-storage-fileshare.md | 62 ++ .../azure-storage/azure-storage-table.md | 133 ++++ .../powershell/templates/_category_.yml | 1 + .../03-Features/powershell/templates/arm.md | 76 +++ .../version-v1.1.0-sidebars.json | 8 + docs/versions.json | 1 + 23 files changed, 2738 insertions(+) create mode 100644 docs/versioned_docs/version-v1.1.0/01-index.md create mode 100644 docs/versioned_docs/version-v1.1.0/02-Guidelines/Installation.md create mode 100644 docs/versioned_docs/version-v1.1.0/02-Guidelines/setting-arm-outputs-to-azure-devops-variable-group.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-active-directory.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-api-management.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-app-service.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-data-factory.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-devops.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-integration-account.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-key-vault.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-logic-apps.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-management.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-security.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-sql.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/_category_.yml create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/azure-storage-all.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/azure-storage-blob.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/azure-storage-fileshare.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/azure-storage-table.md create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/templates/_category_.yml create mode 100644 docs/versioned_docs/version-v1.1.0/03-Features/powershell/templates/arm.md create mode 100644 docs/versioned_sidebars/version-v1.1.0-sidebars.json diff --git a/docs/versioned_docs/version-v1.1.0/01-index.md b/docs/versioned_docs/version-v1.1.0/01-index.md new file mode 100644 index 00000000..4e5eec78 --- /dev/null +++ b/docs/versioned_docs/version-v1.1.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-v1.1.0/02-Guidelines/Installation.md b/docs/versioned_docs/version-v1.1.0/02-Guidelines/Installation.md new file mode 100644 index 00000000..cf6be6f3 --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/02-Guidelines/Installation.md @@ -0,0 +1,16 @@ +--- +title: "Installation" +layout: default +--- + +# Installation + +To have access to the Arcus Scripting features, you have to import the modules. +The best practice for usage in your build and release pipelines is to use the following commands: + +``` powershell +PS> Set-PSRepository -Name PSGallery -InstallationPolicy Trusted +PS> Install-Module -Name Arcus.Scripting.{Module} -AllowClobber +``` + +This drastically improves performance over using the `-Force` parameter and as such, usage of the `-Force` parameter is not recommended. \ No newline at end of file diff --git a/docs/versioned_docs/version-v1.1.0/02-Guidelines/setting-arm-outputs-to-azure-devops-variable-group.md b/docs/versioned_docs/version-v1.1.0/02-Guidelines/setting-arm-outputs-to-azure-devops-variable-group.md new file mode 100644 index 00000000..f3ca10c3 --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/02-Guidelines/setting-arm-outputs-to-azure-devops-variable-group.md @@ -0,0 +1,95 @@ +--- +title: "Setting ARM outputs to Azure DevOps variable group" +layout: default +--- + +# Setting ARM outputs to Azure DevOps variable group + +In ARM and Bicep templates it is possible to specify [output parameters](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/outputs), this enables you to return values from the deployed resources. + +To enable maximum re-use of these output parameters within your environment we developed [this script](https://scripting.arcus-azure.net/Features/powershell/azure-devops#setting-arm-outputs-to-azure-devops-variable-group) which is available in the `Arcus.Scripting.DevOps` PowerShell module. It allows you to store those output parameters in an Azure DevOps variable group. This helps you in making sure certain parameters are available throughout your Azure DevOps environment. + +For example, think of a use-case where your vital infrastructure components are deployed in a seperate Azure DevOps pipeline and need to be referenced from other components. Storing the necessary information such as identifiers, locations or names of these components in an Azure DevOps variable group allows you to easily use these values from other components. + +## Example +### Specify Output Parameters +So how does this work in practice? Let's take an example where we will deploy a very basic Application Insights instance and specify the `Id` and `ConnectionString` of the Application Insights instance as output parameters. + +Our Bicep template looks like this: +``` bicep +param location string = resourceGroup().location + +resource applicationInsight 'microsoft.insights/components@2020-02-02' = { + name: 'myAppInsights' + location: location + kind: 'other' + properties: { + Application_Type: 'other' + } +} + +output ApplicationInsights_Id string = applicationInsight.id +output ApplicationInsights_ConnectionString string = reference(applicationInsight.id, '2020-02-02').ConnectionString +``` + +This Bicep template will deploy the Application Insights instance and place the `Id` and `ConnectionString` in the output parameters. + +### Updating The Variable Group +Now all we need to do is execute our [script](../03-Features/powershell/azure-devops.md#setting-arm-outputs-to-azure-devops-variable-group) which will update the Azure DevOps variable group. + +From an Azure DevOps pipeline this can be done like so: +``` powershell +Set-PSRepository -Name PSGallery -InstallationPolicy Trusted +Install-Module -Name Arcus.Scripting.DevOps -AllowClobber + +Set-AzDevOpsArmOutputsToVariableGroup -VariableGroupName 'myVariableGroup' +``` + +### Combining It All In A Pipeline +Now that we have walked through both steps, let's take a look on how to combine all this into an Azure DevOps pipeline. +For this we use YAML and define two tasks, the first will deploy our Application Insights instance and the second will update our Azure DevOps variable group. + +``` yaml +- task: AzureResourceGroupDeployment@3 + displayName: 'Deploy Bicep template' + inputs: + azureResourceManagerConnection: 'myServiceConnection' + subscriptionId: 'mySubscriptionId' + resourceGroupName: 'myResourceGroup' + location: 'West Europe' + csmFile: 'applicationInsights.bicep' + csmParametersFile: 'applicationInsights.parameters.json' + deploymentOutputs: ArmOutputs + +- task: PowerShell@2 + displayName: 'Update Variable Group' + env: + system_accesstoken: $(System.AccessToken) + inputs: + targetType: 'inline' + script: | + Set-PSRepository -Name PSGallery -InstallationPolicy Trusted + Install-Module -Name Arcus.Scripting.DevOps -AllowClobber + + Set-AzDevOpsArmOutputsToVariableGroup -VariableGroupName 'myVariableGroup' -ArmOutputsEnvironmentVariableName 'ArmOutputs' -UpdateVariablesForCurrentJob +``` + +There are a few things worth noting. First of all we define `deploymentOutputs: ArmOutputs` during the `AzureResourceGroupDeployment@3` task. This means that the output parameters we specified in our Bicep template will be placed in a variable called `ArmOutputs`, this is then referenced during the execution of our script with `-ArmOutputsEnvironmentVariableName 'ArmOutputs'`. + +Secondly we use `-UpdateVariablesForCurrentJob` as a parameter when calling the script. This means that the output parameters from the Bicep file are also available as pipeline variables in the current running job. While not necessary in our example here, if you need to deploy another Bicep template that needs output parameters from an earlier deployed Bicep template this is the way to do it. + +Finally we use `system_accesstoken: $(System.AccessToken)` in the `Powershell@2` task, this is necessary because we need to use the security token used by the running build. + +## Closing Up +Using this setup we are able to deploy a Bicep template and update an Azure DevOps variable group with the specified output parameters! + +> ⚠ Before running your pipeline, make sure the variable group already exists in Azure DevOps and the permissions below are set: +> - Project Collection Build Service (``) - Administrator +> - `` Build Service (``) - Administrator + +## Further Reading +- [Arcus Scripting Azure DevOps documentation](../03-Features/powershell/azure-devops.md) + - [Setting ARM outputs to Azure DevOps variable group](../03-Features/powershell/azure-devops.md#setting-arm-outputs-to-azure-devops-variable-group) + - [Setting ARM outputs to Azure DevOps pipeline variables](../03-Features/powershell/azure-devops.md#setting-arm-outputs-to-azure-devops-pipeline-variables) +- [Bicep Outputs](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/outputs/) +- [Azure DevOps Variable Groups](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/variable-groups?view=azure-devops&tabs=yaml) diff --git a/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-active-directory.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-active-directory.md new file mode 100644 index 00000000..6d6acc93 --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-active-directory.md @@ -0,0 +1,122 @@ +--- +title: "Azure Active Directory" +layout: default +--- + +# Azure Active Directory + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +PS> Install-Module -Name Arcus.Scripting.ActiveDirectory +``` + +## Access Rights to Azure Active Directory + +To interact with Azure Active Directory these scripts use the [Microsoft.Graph.Applications](https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.applications/) module, import this module: + +```powershell +PS> Install-Module -Name Microsoft.Graph.Applications +``` + +After importing this module, make sure you are connected to Microsoft Graph with the following scopes: + +```powershell +PS> Connect-MgGraph -Scopes "Application.ReadWrite.All,AppRoleAssignment.ReadWrite.All" +``` + +## Listing the Roles and Role Assignments for an Azure Active Directory Application + +Lists the roles and role assignments for an Azure Active Directory Application. + +| Parameter | Mandatory | Description | +| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `ClientId` | yes | The client ID of the Azure Active Directory Application Registration for which the roles and assignments are retrieved. | +| `RolesAssignedToClientId` | no | The client ID of the Azure Active Directory Application Registration to which roles have been assigned, used when you only want to retrieve the assignments for this specific application. | + +**Example** + +Retrieving all information for a Client Id. + +```powershell +PS> List-AzADAppRoleAssignments ` +-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85" +#Found role 'FirstRole' on Active Directory Application 'main-application' +#Role 'FirstRole' is assigned to the Active Directory Application 'client-application-one' with ID '6ea09bbd-c21c-460c-b58a-f4a720f51826' +#Role 'FirstRole' is assigned to the Active Directory Application 'client-application-two' with ID 'ebafc99d-cbf4-4bd2-9295-f2b785cfc1a1' +#Found role 'SecondRole' on Active Directory Application 'arcus-scripting-test-main' +#Role 'SecondRole' is assigned to the Active Directory Application 'client-application-one' with ID '6ea09bbd-c21c-460c-b58a-f4a720f51826' +``` + +Retrieving all information for a Client Id and a specific role. + +```powershell +PS> List-AzADAppRoleAssignments ` +-ClientId 'b885c208-6067-44bd-aba9-4010c62b7d85' ` +-RolesAssignedToClientId '6ea09bbd-c21c-460c-b58a-f4a720f51826' +#Found role 'FirstRole' on Active Directory Application 'main-application' +#Role 'FirstRole' is assigned to the Active Directory Application 'client-application-one' with id '6ea09bbd-c21c-460c-b58a-f4a720f51826' +#Found role 'SecondRole' on Active Directory Application 'main-application' +#Role 'SecondRole' is assigned to the Active Directory Application 'client-application-one' with id '6ea09bbd-c21c-460c-b58a-f4a720f51826' +``` + +## Add a Role and Assignment for an Azure Active Directory Application + +Adds a role assignment for an Azure Active Directory Application. The role will be added to the Azure Active Directory Application Registration defined by the `ClientId` parameter, and a role assignment for this role will be added to the Azure Active Directory Application Registration defined by the `AssignRoleToClientId` parameter. + +| Parameter | Mandatory | Description | +| ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ClientId` | yes | The client ID of the Azure Active Directory Application Registration to which the role will be added if not present. | +| `Role` | yes | The name of the role. | +| `AssignRoleToClientId` | yes | The client ID of the Azure Active Directory Application Registration for which the role assignment will be created. The role assignment will be created based on the role added to the Azure Active Directory Application Registration defined by the `ClientId`. | + +**Example** + +```powershell +PS> Add-AzADAppRoleAssignment ` +-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85" ` +-Role "DummyRole" ` +-AssignRoleToClientId "6ea09bbd-c21c-460c-b58a-f4a720f51826" +#Active Directory Application 'main-application' does not contain the role 'DummyRole', adding the role +#Added Role 'DummyRole' to Active Directory Application 'main-application' +#Role Assignment for the role 'DummyRole' added to the Active Directory Application 'client-application-one' +``` + +## Remove a Role and Assignment from an Azure Active Directory Application + +Removes a role assignment for an Azure Active Directory Application. + +| Parameter | Mandatory | Description | +| ---------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ClientId` | yes | The client ID of the Azure Active Directory Application Registration containing the role for which the assignment must be removed. | +| `Role` | yes | The name of the role. | +| `RemoveRoleFromClientId` | yes | The client ID of the Azure Active Directory Application Registration for which the role assignment will be removed. | +| `RemoveRoleIfNoAssignmentsAreLeft` | no | Indicate whether to remove the role from the Azure Active Directory Application Registration defined by the `ClientId` parameter when no more role assignments remain for the role. | + +**Example** + +Removes a role assignment. + +```powershell +PS> Remove-AzADAppRoleAssignment ` +-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85" ` +-Role "DummyRole" ` +-RemoveRoleFromClientId "6ea09bbd-c21c-460c-b58a-f4a720f51826" ` +#Role assignment for 'DummyRole' has been removed from Active Directory Application 'client-application-one' +``` + +Removes a role assignment and removes the fole if no assignments are left on the role. + +```powershell +PS> Remove-AzADAppRoleAssignment ` +-ClientId "b885c208-6067-44bd-aba9-4010c62b7d85" ` +-Role "DummyRole" ` +-RemoveRoleFromClientId "6ea09bbd-c21c-460c-b58a-f4a720f51826" ` +-RemoveRoleIfNoAssignmentsAreLeft +#Role assignment for 'DummyRole' has been removed from Active Directory Application 'client-application-one' +#Role 'DummyRole' on Active Directory Application 'main-application' has been disabled as no more role assignments were left and the option 'RemoveRoleIfNoAssignmentsAreLeft' is set +#Role 'DummyRole' removed from Active Directory Application 'main-application' as no more role assignments were left and the option 'RemoveRoleIfNoAssignmentsAreLeft' is set +``` + diff --git a/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-api-management.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-api-management.md new file mode 100644 index 00000000..0594d1fe --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-api-management.md @@ -0,0 +1,382 @@ +--- +title: "Azure API Management" +layout: default +--- + +# Azure API Management + +## 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" +# New Azure storage context for storage account 'my-storage-account' with storage key created! +# Azure API management service 'my-service' in resource group 'my-resource-group' 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' was added on Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' +``` + +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' was added on Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' +# Updated policy of the operation '$OperationId' in API '$ApiId' of the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' +``` + +## Creating a new user in an Azure API Management service + +Sign-up 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 +# Invitation has been sent to $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' +``` + +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 +# Invitation has been sent to $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' +``` + +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 +# Invitation has been sent to $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' +``` + +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 +# Invitation has been sent to $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' +``` + +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 +# Account has been created for $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' +# 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 +# Account has been created for $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' +``` + +## 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 +# Removed the user account with e-mail '$MailAddress' and ID '1' for the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' +``` + +## 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 +# Successfully updated the product policy for the Azure API Management service $ServiceName in resource group $ResourceGroupName +``` + +## 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 +# Successfully updated API policy for the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' +``` + +## 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 +# USuccessfully updated the operation policy for the Azure API Management service $ServiceName in resource group $ResourceGroupName +``` + +## 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 +# Removed 'echo' API in the Azure API Management service $ServiceName in resource group $ResourceGroupName +# Removed 'starter' product in the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' +# Removed 'unlimited' product in the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' +``` + +## 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 +# Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' 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 +# Using API Management instance '$ServiceName' in resource group '$ResourceGroup' +# Subscription key header 'x-api-key' was assigned +# 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" +# Subscription key header 'my-api-key' was assigned for the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' +# Subscription key query parameter 'myApiKey' was assigned for the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' +``` + +## 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" +# Uploaded private certificate at 'C:\temp\certificate.pfx' for the Azure API Management service 'my-api-management-instance' in resource group 'my-resource-group' +``` diff --git a/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-app-service.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-app-service.md new file mode 100644 index 00000000..b6b03622 --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-app-service.md @@ -0,0 +1,42 @@ +--- +title: "Azure App Service" +layout: default +--- + +# 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-v1.1.0/03-Features/powershell/azure-data-factory.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-data-factory.md new file mode 100644 index 00000000..82099dc1 --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-data-factory.md @@ -0,0 +1,75 @@ +--- +title: " Azure Data Factory" +layout: default +--- + +# Azure Data Factory + +## 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" +# Started Azure Data Factory trigger 'my-data-factory-trigger-name' of data factory 'my-data-factory-name' in resource group 'my-resource-group' +``` + +```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" +# Stopped Azure Data Factory trigger 'my-data-factory-trigger-name' of data factory 'my-data-factory-name' in resource group 'my-resource-group' +``` + +```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-v1.1.0/03-Features/powershell/azure-devops.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-devops.md new file mode 100644 index 00000000..e8821856 --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-devops.md @@ -0,0 +1,230 @@ +--- +title: " Azure DevOps" +layout: default +--- + +# Azure DevOps + +## 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 | +| `AsSecret` | no | The switch to set the variable as a secret | + +**Example** + +Setting a variable: + +```powershell +PS> Set-AzDevOpsVariable "my-variable" "my-variable-value" +##vso[task.setvariable variable=my-variable] my-variable-value +``` + +Setting a variable as a secret: + +```powershell +PS> Set-AzDevOpsVariable "my-variable" "my-variable-value" -AsSecret +##vso[task.setvariable variable=my-variable;issecret=true] *** +``` + +## 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 +# Getting 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" +# Getting 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 | +| `DaysToKeep` | no | The number of days to keep the Azure DevOps pipeline run, if not supplied the Azure DevOps pipeline run will be saved indefinitely | + +**Example** + +Saving an Azure DevOps pipeline run indefinitely + +```powershell +PS> Save-AzDevOpsBuild ` +-ProjectId $(System.TeamProjectId) ` +-BuildId $(Build.BuildId) +# Saved Azure DevOps build indefinitely with build ID $BuildId in project $ProjectId +``` + +Saving an Azure DevOps pipeline run for 10 days + +```powershell +PS> Save-AzDevOpsBuild ` +-ProjectId $(System.TeamProjectId) ` +-BuildId $(Build.BuildId) ` +-DaysToKeep 10 +# Saved Azure DevOps build for 10 days with build ID $BuildId in project $ProjectId +``` + +> 💡 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-v1.1.0/03-Features/powershell/azure-integration-account.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-integration-account.md new file mode 100644 index 00000000..4ad387cf --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-integration-account.md @@ -0,0 +1,611 @@ +--- +title: "Azure Integration Account" +layout: default +--- + +# 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" +# 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 +# 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-' +# 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" +# Schema 'MyFirstSchema.xsd' has been uploaded 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 +# Schema 'MyFirstSchema' has been uploaded 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-' +# Schema 'dev-MyFirstSchema.xsd' has been uploaded 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" +# 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 +# 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-' +# 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" +# Map 'MyFirstMap.xslt' has been uploaded 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 +# Map 'MyFirstMap' has been uploaded 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-' +# Map 'dev-MyFirstMap.xslt' has been uploaded 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" +# 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-' +# 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" +# Assembly 'MyFirstAssembly.dll' has been uploaded 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-' +# Assembly 'dev-MyFirstAssembly.dll' has been uploaded 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" +# 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-' +# 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" +# Certificate 'MyFirstCertificate.cer' has been uploaded 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-' +# Certificate 'dev-MyFirstCertificate.cer' has been uploaded 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/' +# 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/' +# 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" +# 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-' +# 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" +# Partner 'MyFirstPartner.json' has been uploaded 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-' +# Partner 'dev-MyFirstPartner.json' has been uploaded 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" +# 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-' +# 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" +# Agreement 'MyFirstAgreement' has been uploaded 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-' +# Agreement 'dev-MyFirstAgreement' has been uploaded 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-v1.1.0/03-Features/powershell/azure-key-vault.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-key-vault.md new file mode 100644 index 00000000..262a196c --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-key-vault.md @@ -0,0 +1,101 @@ +--- +title: "Azure Key Vault" +layout: default +--- + +# 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" +# accessPolicies: {list: [{tenantId: ...,permissions: ...}]} +# Successfully retrieved Azure Key Vault access policies +``` + +```powershell +PS> $accessPolicies = Get-AzKeyVaultAccessPolicies ` +-KeyVaultName "my-key-vault" ` +-ResourceGroupName "my-resource-group" +# accessPolicies: {list: [{tenantId: ...,permissions: ...}]} +# Successfully retrieved Azure Key Vault access policies +``` + +## 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" +# Azure Key Vault secret 'my-secret' (Version: 'new-secret-version') has been created in Azure Key vault 'my-key-vault' +``` + +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" +# Azure Key Vault secret 'my-secret' (Version: 'new-secret-version') has been created in Azure Key vault 'my-key-vault' +``` + +## 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" +# Use BASE64 format as format to create Azure Key vault secret 'my-secret' in Azure Key vault 'my-key-vault' +# Azure Key Vault secret 'my-secret' (Version: 'new-secret-version') has been created in Azure Key vault 'my-key-vault' +``` + +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" +# Azure Key Vault secret 'my-secret' (Version: 'new-secret-version') has been created in Azure Key vault 'my-key-vault' +``` diff --git a/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-logic-apps.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-logic-apps.md new file mode 100644 index 00000000..7e1ea30a --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-logic-apps.md @@ -0,0 +1,429 @@ +--- +title: " Azure Logic Apps" +layout: default +--- + +# Azure Logic Apps + +## Installation + +To have access to the following features, you have to import the module: + +```powershell +PS> Install-Module -Name Arcus.Scripting.LogicApps +``` + +## Cancel running instances for an Azure Logic App + +Use this script to cancel all running instances for a specific Azure Logic App. + +| Parameter | Mandatory | Description | +| --------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure Logic App. | +| `LogicAppName` | yes | The name of the Azure Logic App for which the runs will be cancelled. | +| `MaximumFollowNextPageLink` | no | This sets the amount of pages (30 runs per page) of the Logic App run history (if any) that are retrieved. If not supplied the default value is 10. | + +**Example** + +Taking an example in which a specific Azure Logic App (`"rcv-shopping-order-sftp"`) needs to have all its runs cancelled. + +```powershell +PS> Cancel-AzLogicAppRuns ` +-ResourceGroupName "rg-common-dev" ` +-LogicAppName "rcv-shopping-order-sftp" +# Successfully cancelled all running instances for the Azure Logic App 'rcv-shopping-order-sftp' in resource group 'rg-common-dev' +``` + +## Resubmitting failed instances for an Azure Logic App + +Use this script to re-run a failed Azure Logic App run. + +| Parameter | Mandatory | Description | +| --------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure Logic App. | +| `LogicAppName` | yes | The name of the Azure Logic App for which the failed runs will be resubmitted. | +| `StartTime` | yes | The start time in UTC for retrieving the failed instances. | +| `EndTime` | no | The end time in UTC for retrieving the failed instances, if not supplied it will use the current datetime. | +| `MaximumFollowNextPageLink` | no | This sets the amount of pages (30 runs per page) of the Logic App run history (if any) that are retrieved. If not supplied the default value is 10. | + +**Example** + +Taking an example in which a specific Azure Logic App (`"rcv-shopping-order-sftp"`) needs to have all its failed runs resubmitted from 2023-05-01 00:00:00. + +```powershell +PS> Resubmit-FailedAzLogicAppRuns ` +-ResourceGroupName "rg-common-dev" ` +-LogicAppName "rcv-shopping-order-sftp" ` +-StartTime "2023-05-01 00:00:00" +# Successfully resubmitted all failed instances for the Azure Logic App 'rcv-shopping-order-sftp' in resource group 'rg-common-dev' from '2023-05-01 00:00:00' +``` + +Taking an example in which a specific Azure Logic App (`"rcv-shopping-order-sftp"`) needs to have all its failed runs resubmitted from 2023-05-01 00:00:00 until 2023-05-01 10:00:00. + +```powershell +PS> Resubmit-FailedAzLogicAppRuns ` +-ResourceGroupName "rg-common-dev" ` +-LogicAppName "rcv-shopping-order-sftp" ` +-StartTime "2023-05-01 00:00:00" ` +-EndTime "2023-05-01 10:00:00" +# Successfully resubmitted all failed instances for the Azure Logic App 'rcv-shopping-order-sftp' in resource group 'rg-common-dev' from '2023-05-01 00:00:00' and until '2023-05-01 10:00:00' +``` + +## Disable an Azure Logic App + +Use 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" +# Successfully disabled Azure Logic App 'rcv-shopping-order-sftp' in resource group 'rg-common-dev' +``` + +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 +# Successfully disabled Azure Logic App 'rcv-shopping-order-sftp' in resource group 'rg-common-dev' +``` + +## Enable an Azure Logic App + +Use 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" +# Successfully enabled Azure Logic App 'rcv-shopping-order-sftp' in resource group 'rg-common-dev' +``` + +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 +# Successfully enabled Azure Logic App 'rcv-shopping-order-sftp' in resource group 'rg-common-dev' +``` + +## 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. | +| MaximumFollowNextPageLink | `integer` | This sets the amount of pages (30 runs per page) of the Logic App run history (if any) that are retrieved. If not supplied the default value is 10. | +| 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", + "maximumFollowNextPageLink": 25, + "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' +# Successfully disabled Azure Logic App 'rcv-shopping-order-ftp' in resource group 'my-resource-group' + +# Executing StopType 'Immediate' for Logic App 'rcv-shopping-order-sftp' in resource group 'my-resource-group' +# Successfully disabled Azure Logic App 'rcv-shopping-order-sftp' in resource group 'my-resource-group' + +# Executing StopType 'Immediate' for Logic App 'rcv-shopping-order-file' in resource group 'my-resource-group' +# Successfully disabled Azure Logic App 'rcv-shopping-order-file' in resource group 'my-resource-group' +# 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' +# Successfully disabled Azure Logic App 'rcv-shopping-order' in resource group 'my-resource-group' +# 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' +# Successfully disabled Azure Logic App 'orc-shopping-order-processing' in resource group 'my-resource-group' +# 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' +# Successfully disabled Azure Logic App 'snd-shopping-order-smtp' in resource group 'my-resource-group' +# 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' +# Successfully disabled Azure Logic App 'la-cod-dev-we-rcv-shopping-order-ftp' in resource group 'my-resource-group' + +# Executing StopType 'Immediate' for Logic App 'la-cod-dev-we-rcv-shopping-order-sftp' in resource group 'my-resource-group' +# Successfully disabled Azure Logic App 'la-cod-dev-we-rcv-shopping-order-sftp' in resource group 'my-resource-group' + +# Executing StopType 'Immediate' for Logic App 'la-cod-dev-we-rcv-shopping-order-file' in resource group 'my-resource-group' +# Successfully disabled Azure Logic App 'la-cod-dev-we-rcv-shopping-order-file' in resource group 'my-resource-group' +# 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' +# Successfully disabled Azure Logic App 'la-cod-dev-we-rcv-shopping-order' in resource group 'my-resource-group' +# 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' +# Successfully disabled Azure Logic App 'la-cod-dev-we-orc-shopping-order-processing' in resource group 'my-resource-group' +# 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' +# Successfully disabled Azure Logic App 'la-cod-dev-we-snd-shopping-order-confirmation-smtp' in resource group 'my-resource-group' +# 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' +# Successfully enabled Azure Logic App 'snd-shopping-order-confirmation-smtp' in resource group 'my-resource-group' +# 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' +# Successfully enabled Azure Logic App 'orc-shopping-order-processing' in resource group 'my-resource-group' +# 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' +# Successfully enabled Azure Logic App 'rcv-shopping-order' in resource group 'my-resource-group' +# 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' +# Successfully enabled Azure Logic App 'rcv-shopping-order-ftp' in resource group 'my-resource-group' + +# Reverting StopType 'Immediate' for Logic App 'rcv-shopping-order-sftp' in resource group 'my-resource-group' +# Successfully enabled rcv-shopping-order-sftp + +# Reverting StopType 'Immediate' for Logic App 'rcv-shopping-order-file' in resource group 'my-resource-group' +# Successfully enabled Azure Logic App 'rcv-shopping-order-file' in resource group 'my-resource-group' +# 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' +# Successfully enabled Azure Logic App 'la-cod-dev-we-snd-shopping-order-confirmation-smtp' in resource group 'my-resource-group' +# 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' +# Successfully enabled Azure Logic App 'la-cod-dev-we-orc-shopping-order-processing' in resource group 'my-resource-group' +# 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' +# Successfully enabled Azure Logic App 'la-cod-dev-we-rcv-shopping-order' in resource group 'my-resource-group' +# 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' +# Successfully enabled Azure Logic App 'la-cod-dev-we-rcv-shopping-order-ftp' in resource group 'my-resource-group' + +# Reverting StopType 'Immediate' for Logic App 'la-cod-dev-we-rcv-shopping-order-sftp' in resource group 'my-resource-group' +# Successfully enabled Azure Logic App 'la-cod-dev-we-rcv-shopping-order-sftp' in resource group 'my-resource-group' + +# Reverting StopType 'Immediate' for Logic App 'la-cod-dev-we-rcv-shopping-order-file' in resource group 'my-resource-group' +# Successfully enabled Azure Logic App 'la-cod-dev-we-rcv-shopping-order-file' in resource group 'my-resource-group' +# Batch: 'Protocol Receiver(s)' has been executed +``` \ No newline at end of file diff --git a/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-management.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-management.md new file mode 100644 index 00000000..10d51c04 --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-management.md @@ -0,0 +1,60 @@ +--- +title: "Azure Management" +layout: default +--- + +# Azure Management + +## 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" +# Successfully removed the soft deleted Azure API Management service '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" +# Successfully restored the soft deleted API Management service 'my-apim' +``` diff --git a/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-security.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-security.md new file mode 100644 index 00000000..60c09d99 --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-security.md @@ -0,0 +1,107 @@ +--- +title: "Azure Security" +layout: default +--- + +# Azure Security + +## 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" +# Granted 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'! +``` diff --git a/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-sql.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-sql.md new file mode 100644 index 00000000..aac57796 --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-sql.md @@ -0,0 +1,82 @@ +--- +title: " Azure SQL" +layout: default +--- + +# Azure SQL + +## 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" +# DB migration 1.0.0 applied! +# Done migrating database. Current Database version is 1.0.0 +``` + +**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" +# DB migration 1.0.0 applied! +# Done migrating database. Current Database version is 1.0.0 +``` + +### 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-v1.1.0/03-Features/powershell/azure-storage/_category_.yml b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/_category_.yml new file mode 100644 index 00000000..9d1c82b6 --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/_category_.yml @@ -0,0 +1 @@ +label: 'Azure Storage' diff --git a/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/azure-storage-all.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/azure-storage-all.md new file mode 100644 index 00000000..c45bafcd --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-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-v1.1.0/03-Features/powershell/azure-storage/azure-storage-blob.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/azure-storage-blob.md new file mode 100644 index 00000000..b467407c --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/azure-storage-blob.md @@ -0,0 +1,54 @@ +--- +title: " Azure Blob Storage" +layout: default +--- + +# Azure Blob Storage + +## 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" +# Uploaded the file [file] to Azure Blob storage container: [Blob URL] +``` + +With non-existing blob container: + +```powershell +PS> Upload-AzFilesToBlobStorage ` +-ResourceGroupName "resource-group" ` +-StorageAccountName "account-name" ` +-TargetFolderPath "./directory" ` +-ContainerName "blob-container" +# Uploaded the file [file\ to Azure Blob storage container: [Blob URL] +``` diff --git a/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/azure-storage-fileshare.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/azure-storage-fileshare.md new file mode 100644 index 00000000..d80d9666 --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/azure-storage-fileshare.md @@ -0,0 +1,62 @@ +--- +title: " Azure Storage for file shares" +layout: default +--- + +# Azure Storage for file shares + +## 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" +# 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" +# 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-v1.1.0/03-Features/powershell/azure-storage/azure-storage-table.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/azure-storage-table.md new file mode 100644 index 00000000..79e4d039 --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/azure-storage/azure-storage-table.md @@ -0,0 +1,133 @@ +--- +title: " Azure Table Storage" +layout: default +--- + +# Azure Storage - Tables + +## 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 table 'products' does not exist yet in the Azure storage account 'admin', so will create one +# Azure storage table 'products' created in Azure storage account 'admin' +``` + +With existing table and re-create: + +```powershell +PS> Create-AzStorageTable ` +-ResourceGroupName "stock" ` +-StorageAccountName "admin" ` +-TableName "products" ` +-Recreate ` +-RetryIntervalSeconds 3 +# Azure storage table 'products' has been removed from Azure storage account 'admin' +# Failed to re-create the Azure storage table 'products' in Azure storage account 'admin', retrying in 5 seconds... +# Failed to re-create the Azure storage table 'products' in Azure storage account 'admin', retrying in 5 seconds... +# Azure storage table 'products' created in Azure storage account 'admin' +``` + + +## Set the entities in a table of an Azure Storage Account + +Deletes all entities of a specified table in an Azure Storage Account and creates new entities based on a configuration file. + +| Parameter | Mandatory | Description | +| ---------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group where the Azure Storage Account is located | +| `StorageAccountName` | yes | The name of the Azure Storage Account that contains the table | +| `TableName` | yes | The name of the table in which the entities should be set | +| `ConfigurationFile` | yes | Path to the JSON Configuration file containing all the entities to be set | + +**Configuration File** + +The configuration file is a simple JSON file that contains all of the entities that should be set on the specified table, the JSON file consists of an array of JSON objects (= your entities). Each object contains simple name-value pairs (string-string). + +Defining the PartitionKey and/or RowKey are optional, if not provided a random GUID will be set for these. + + The file needs to adhere to the following JSON schema: + +``` json +{ + "definitions": {}, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://scripting.arcus-azure.net/Features/powershell/azure-storage/azure-storage-table/config.json", + "type": "array", + "title": "The configuration JSON schema", + "items": [{ + "type": "object", + "patternProperties": { + "^.*$": { + "anyOf": [{ + "type": "string" + }, { + "type": "null" + } + ] + } + }, + "additionalProperties": false + } + ] +} +``` + +**Example Configuration File** + +```json +[ + { + "PartitionKey": "SystemA", + "RowKey": "100", + "ReadPath": "/home/in", + "ReadIntervalInSeconds": "30" + }, + { + "PartitionKey": "SystemA", + "RowKey": "200", + "ReadPath": "/data/in", + "ReadIntervalInSeconds": "10", + "HasSubdirectories": "true" + } +] +``` + +**Example** + +```powershell +PS> Set-AzTableStorageEntities ` +-ResourceGroupName "someresourcegroup" ` +-StorageAccountName "somestorageaccount" ` +-TableName "sometable" ` +-ConfigurationFile ".\config.json" +# Deleting all existing entities in Azure storage table 'sometable' for Azure storage account 'somestorageaccount' in resource group 'someresourcegroup'... +# Successfully deleted all existing entities in Azure storage table 'sometable' for Azure storage account 'somestorageaccount' in resource group 'someresourcegroup' +# Successfully added all entities in Azure storage table 'sometable' for Azure storage account 'somestorageaccount' in resource group 'someresourcegroup' +``` diff --git a/docs/versioned_docs/version-v1.1.0/03-Features/powershell/templates/_category_.yml b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/templates/_category_.yml new file mode 100644 index 00000000..b6d122a6 --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/templates/_category_.yml @@ -0,0 +1 @@ +label: 'Templates' diff --git a/docs/versioned_docs/version-v1.1.0/03-Features/powershell/templates/arm.md b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/templates/arm.md new file mode 100644 index 00000000..14611dba --- /dev/null +++ b/docs/versioned_docs/version-v1.1.0/03-Features/powershell/templates/arm.md @@ -0,0 +1,76 @@ +--- +title: "ARM Templates" +layout: default +--- + +# ARM + +## 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_sidebars/version-v1.1.0-sidebars.json b/docs/versioned_sidebars/version-v1.1.0-sidebars.json new file mode 100644 index 00000000..d3a9caf4 --- /dev/null +++ b/docs/versioned_sidebars/version-v1.1.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "version-v1.1.0/tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/docs/versions.json b/docs/versions.json index 5a86d83f..1497fb87 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,4 +1,5 @@ [ + "v1.1.0", "v1.0.0", "v0.8.0", "v0.7.0",