From 930298d0582d9616e4ba10af20b526f540e106b0 Mon Sep 17 00:00:00 2001 From: Erika Gressi Date: Thu, 3 Mar 2022 16:31:49 +0100 Subject: [PATCH 1/6] interoperability --- ...eroperability - Bicep to ARM conversion.md | 31 ++++++++++++++ ...teroperability - Register ADO pipelines.md | 0 ... - Transition to Azure DevOps Pipelines.md | 40 +++++++++++++++++++ docs/wiki/Interoperability.md | 11 +++++ 4 files changed, 82 insertions(+) delete mode 100644 docs/wiki/Interoperability - Register ADO pipelines.md create mode 100644 docs/wiki/Interoperability - Transition to Azure DevOps Pipelines.md diff --git a/docs/wiki/Interoperability - Bicep to ARM conversion.md b/docs/wiki/Interoperability - Bicep to ARM conversion.md index e69de29bb2..fe2be99806 100644 --- a/docs/wiki/Interoperability - Bicep to ARM conversion.md +++ b/docs/wiki/Interoperability - Bicep to ARM conversion.md @@ -0,0 +1,31 @@ +Bicep is a relatively new Domain-specific language (DSL) and, at the time of writing, not yet in version 1.0.0. For this reason, some people may want to wait for Bicep's _General Availability_ and prefer to use ARM/JSON for the time being. + +For these scenarios, the CARML library provides a script that uses the Bicep Toolkit translator/compiler to support the conversion of CARML Bicep modules to ARM/JSON Templates. +This page documents the conversion utility and how to use it. + +--- + +### _Navigation_ + +- [Location](#location) +- [How it works](#what-it-does) +- [How to use it](#how-to-use-it) + +--- +# Location + +You can find the script under `/utilities/tools/ConvertTo-ARMTemplate.ps1` + +# How it works + +The script finds all `deploy.bicep` files and converts them to json-based ARM templates by using the following steps: +1. Remove existing deploy.json files from folders where deploy.bicep files are also present. +1. Convert .bicep files to .json +1. Remove bicep metadata from the coverted .json files +1. Remove .bicep files and folders +1. Update pipeline files - Replace .bicep with .json in pipeline files + +# How to use it + +For details on how to use the function please refer to the script's local documentation. +> **Note:** The script must be loaded before the function can be invoked diff --git a/docs/wiki/Interoperability - Register ADO pipelines.md b/docs/wiki/Interoperability - Register ADO pipelines.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/wiki/Interoperability - Transition to Azure DevOps Pipelines.md b/docs/wiki/Interoperability - Transition to Azure DevOps Pipelines.md new file mode 100644 index 0000000000..3d5480cabd --- /dev/null +++ b/docs/wiki/Interoperability - Transition to Azure DevOps Pipelines.md @@ -0,0 +1,40 @@ +Not all customers may be using GitHub repos and/or GitHub Actions. CARML is able to be hosted in a GitHub repo and deployed with Azure DevOps Pipelines or it can completely be ran out of Azure DevOps. + +Use this script to automatically register all specified Azure DevOps pipelines in a target Azure DevOps project. This is especially useful to register the initial module pipelines as there is one for each module in the repository. + +--- + +### _Navigation_ + +- [Location](#location) +- [How it works](#what-it-does) +- [How to use it](#how-to-use-it) + +--- +# Location + +You can find the script under `/utilities/tools/AzureDevOps/Register-AzureDevOpsPipeline.ps1` + +# How it works + +1. Get all pipelines in a given target folder (for example `.azuredevops/modulePipelines`) +1. Fetch all currently registered pipelines in the target Azure DevOps project +1. Compare the local defined and remote-registered pipelines to detect which need to be created and which skipped +1. Create all pipelines that are missing +1. Optionally register the pipelines also for build validation (i.e. they registered to be required for Pull Requests) + +# How to use it + +> **Note:** You'll need the 'azure-devops' extension to run this function: `az extension add --upgrade -n azure-devops` + +The steps you'd want to follow are +1. (if pipelines are in GitHub) Create a service connection to the target GitHub repository using e.g. oAuth +1. Create a PAT token for the Azure DevOps environment in which you want to register the pipelines in +1. Run this script with the corresponding input parameters +1. Create any required element required to execute the pipelines. For example: + - Library group(s) used in the pipeline(s) + - Service connection(s) used in the pipeline(s) + - Agent pool(s) used in the pipeline(s) if not using the default available agents + +For further details on how to use the function please refer to the script's local documentation. +> **Note:** The script must be loaded before the function can be invoked diff --git a/docs/wiki/Interoperability.md b/docs/wiki/Interoperability.md index e69de29bb2..6223fdcec7 100644 --- a/docs/wiki/Interoperability.md +++ b/docs/wiki/Interoperability.md @@ -0,0 +1,11 @@ +This section explores how CARML is able to operate between ARM JSON Templates & Bicep and Azure DevOps Pipelines & GitHub Action to meet different customer scenarios. + +This is how you will run different scripts and set up a module in either ARM JSON Template or Bicep syntax and configure a CI/CD pipeline using Azure DevOps or GitHub. + +--- + +### _Navigation_ +- [Bicep to ARM/JSON conversion](./Interoperability%20-%20Bicep%20to%20ARM%20conversion) +- [Transition to Azure DevOps Pipelines](./Interoperability%20-%20Transition%20to%20Azure%20DevOps%20Pipelines) + +--- From 6ce71e6f3c259aaa8f31665c875caa105cdcb136 Mon Sep 17 00:00:00 2001 From: Erika Gressi Date: Thu, 3 Mar 2022 16:43:16 +0100 Subject: [PATCH 2/6] interoperability home toc --- docs/wiki/Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index d095cc8123..57c5b754c7 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -59,7 +59,7 @@ If you're unfamiliar with Infrastructure as Code, or wonder how you can use the - [Pipeline usage](./The%20CI%20environment%20-%20Pipeline%20usage) - [Interoperability](./Interoperability) - [Bicep to ARM/JSON conversion](./Interoperability%20-%20Bicep%20to%20ARM%20conversion) - - [Register ADO pipelines](./Interoperability%20-%20Register%20ADO%20pipelines) + - [Transition to Azure DevOps Pipelines](./Interoperability%20-%20Transition%20to%20Azure%20DevOps%20Pipelines) - [Contribution guide](./Contribution%20guide) - [Generate module Readme](./Contribution%20guide%20-%20Generate%20module%20Readme) - [Get formatted RBAC roles](./Contribution%20guide%20-%20Get%20formatted%20RBAC%20roles) From 8e5feb9123ca81e24c123264c4f8c901629ce0cd Mon Sep 17 00:00:00 2001 From: Erika Gressi <56914614+eriqua@users.noreply.github.com> Date: Fri, 4 Mar 2022 13:10:44 +0100 Subject: [PATCH 3/6] Update docs/wiki/Interoperability - Transition to Azure DevOps Pipelines.md Co-authored-by: Alexander Sehr --- .../Interoperability - Transition to Azure DevOps Pipelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki/Interoperability - Transition to Azure DevOps Pipelines.md b/docs/wiki/Interoperability - Transition to Azure DevOps Pipelines.md index 3d5480cabd..5b4a9f9152 100644 --- a/docs/wiki/Interoperability - Transition to Azure DevOps Pipelines.md +++ b/docs/wiki/Interoperability - Transition to Azure DevOps Pipelines.md @@ -1,4 +1,4 @@ -Not all customers may be using GitHub repos and/or GitHub Actions. CARML is able to be hosted in a GitHub repo and deployed with Azure DevOps Pipelines or it can completely be ran out of Azure DevOps. +Not all customers may be using GitHub repos and/or GitHub Actions. CARML can be hosted in a GitHub repo and deployed using Azure DevOps Pipelines or run entirely through Azure DevOps. Use this script to automatically register all specified Azure DevOps pipelines in a target Azure DevOps project. This is especially useful to register the initial module pipelines as there is one for each module in the repository. From 2bbdc11502e50a4d3258008d0c5ff01b1234ebc9 Mon Sep 17 00:00:00 2001 From: Erika Gressi <56914614+eriqua@users.noreply.github.com> Date: Fri, 4 Mar 2022 13:11:06 +0100 Subject: [PATCH 4/6] Update docs/wiki/Interoperability.md Co-authored-by: Alexander Sehr --- docs/wiki/Interoperability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki/Interoperability.md b/docs/wiki/Interoperability.md index 6223fdcec7..b5ee945957 100644 --- a/docs/wiki/Interoperability.md +++ b/docs/wiki/Interoperability.md @@ -1,4 +1,4 @@ -This section explores how CARML is able to operate between ARM JSON Templates & Bicep and Azure DevOps Pipelines & GitHub Action to meet different customer scenarios. +This section explores how CARML can work with both Bicep & ARM JSON templates as well as GitHub Actions & Azure DevOps Pipelines to meet different customer scenarios. This is how you will run different scripts and set up a module in either ARM JSON Template or Bicep syntax and configure a CI/CD pipeline using Azure DevOps or GitHub. From 626e6cfe3248e94588842a5ff3e5f52fdaf84889 Mon Sep 17 00:00:00 2001 From: Erika Gressi Date: Fri, 4 Mar 2022 13:23:39 +0100 Subject: [PATCH 5/6] register ADO --- docs/wiki/Home.md | 2 +- ...md => Interoperability - Register Azure DevOps Pipelines.md} | 0 docs/wiki/Interoperability.md | 2 +- 3 files changed, 2 insertions(+), 2 deletions(-) rename docs/wiki/{Interoperability - Transition to Azure DevOps Pipelines.md => Interoperability - Register Azure DevOps Pipelines.md} (100%) diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index 57c5b754c7..16dabc9924 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -59,7 +59,7 @@ If you're unfamiliar with Infrastructure as Code, or wonder how you can use the - [Pipeline usage](./The%20CI%20environment%20-%20Pipeline%20usage) - [Interoperability](./Interoperability) - [Bicep to ARM/JSON conversion](./Interoperability%20-%20Bicep%20to%20ARM%20conversion) - - [Transition to Azure DevOps Pipelines](./Interoperability%20-%20Transition%20to%20Azure%20DevOps%20Pipelines) + - [Register Azure DevOps Pipelines](./Interoperability%20-%20Register%20Azure%20DevOps%20Pipelines) - [Contribution guide](./Contribution%20guide) - [Generate module Readme](./Contribution%20guide%20-%20Generate%20module%20Readme) - [Get formatted RBAC roles](./Contribution%20guide%20-%20Get%20formatted%20RBAC%20roles) diff --git a/docs/wiki/Interoperability - Transition to Azure DevOps Pipelines.md b/docs/wiki/Interoperability - Register Azure DevOps Pipelines.md similarity index 100% rename from docs/wiki/Interoperability - Transition to Azure DevOps Pipelines.md rename to docs/wiki/Interoperability - Register Azure DevOps Pipelines.md diff --git a/docs/wiki/Interoperability.md b/docs/wiki/Interoperability.md index 6223fdcec7..3bad48c593 100644 --- a/docs/wiki/Interoperability.md +++ b/docs/wiki/Interoperability.md @@ -6,6 +6,6 @@ This is how you will run different scripts and set up a module in either ARM JSO ### _Navigation_ - [Bicep to ARM/JSON conversion](./Interoperability%20-%20Bicep%20to%20ARM%20conversion) -- [Transition to Azure DevOps Pipelines](./Interoperability%20-%20Transition%20to%20Azure%20DevOps%20Pipelines) +- [Register Azure DevOps Pipelines](./Interoperability%20-%20Register%20Azure%20DevOps%20Pipelines) --- From 51b562ce13339e51b0b231a2df75d2970b6db2da Mon Sep 17 00:00:00 2001 From: Erika Gressi Date: Fri, 4 Mar 2022 13:25:16 +0100 Subject: [PATCH 6/6] register ADO p --- docs/wiki/Home.md | 2 +- docs/wiki/Interoperability.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index 16dabc9924..1948398e9f 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -59,7 +59,7 @@ If you're unfamiliar with Infrastructure as Code, or wonder how you can use the - [Pipeline usage](./The%20CI%20environment%20-%20Pipeline%20usage) - [Interoperability](./Interoperability) - [Bicep to ARM/JSON conversion](./Interoperability%20-%20Bicep%20to%20ARM%20conversion) - - [Register Azure DevOps Pipelines](./Interoperability%20-%20Register%20Azure%20DevOps%20Pipelines) + - [Register Azure DevOps pipelines](./Interoperability%20-%20Register%20Azure%20DevOps%20pipelines) - [Contribution guide](./Contribution%20guide) - [Generate module Readme](./Contribution%20guide%20-%20Generate%20module%20Readme) - [Get formatted RBAC roles](./Contribution%20guide%20-%20Get%20formatted%20RBAC%20roles) diff --git a/docs/wiki/Interoperability.md b/docs/wiki/Interoperability.md index 960be00186..dbe0dd2ffb 100644 --- a/docs/wiki/Interoperability.md +++ b/docs/wiki/Interoperability.md @@ -6,6 +6,6 @@ This is how you will run different scripts and set up a module in either ARM JSO ### _Navigation_ - [Bicep to ARM/JSON conversion](./Interoperability%20-%20Bicep%20to%20ARM%20conversion) -- [Register Azure DevOps Pipelines](./Interoperability%20-%20Register%20Azure%20DevOps%20Pipelines) +- [Register Azure DevOps pipelines](./Interoperability%20-%20Register%20Azure%20DevOps%20pipelines) ---