diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index d095cc8123..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 ADO pipelines](./Interoperability%20-%20Register%20ADO%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 - 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 - Register Azure DevOps Pipelines.md b/docs/wiki/Interoperability - Register Azure DevOps Pipelines.md new file mode 100644 index 0000000000..5b4a9f9152 --- /dev/null +++ b/docs/wiki/Interoperability - Register Azure DevOps Pipelines.md @@ -0,0 +1,40 @@ +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. + +--- + +### _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..dbe0dd2ffb 100644 --- a/docs/wiki/Interoperability.md +++ b/docs/wiki/Interoperability.md @@ -0,0 +1,11 @@ +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. + +--- + +### _Navigation_ +- [Bicep to ARM/JSON conversion](./Interoperability%20-%20Bicep%20to%20ARM%20conversion) +- [Register Azure DevOps pipelines](./Interoperability%20-%20Register%20Azure%20DevOps%20pipelines) + +---