v0.4.0 Lab 9 Interoperability

In this lab you will explore how CARML is able to operate with both ARM JSON Templates & Bicep as well as with both Azure DevOps Pipelines & GitHub Workflows to meet different customer scenarios.

There may be reasons why a customer may not want to use Bicep or GitHub workflows just yet:

• Bicep is still a relatively new DSL and not yet version 1.0.0
• GitHub workflows are likewise relatively new compared to Azure DevOps pipelines and not yet on par with it

Fortunately, CARML supports both GitHub & Azure DevOps and either pipeline is compatible with both ARM JSON as well as Bicep.

Navigation

• Step 1 - Create a new branch
• Step 2 - Convert to ARM
• Step 3 - (Optional) Leverage Azure DevOps Pipelines

---

Step 1 - Create a new branch

First, navigate back to your local CARML fork.

To not interfere with your current setup, you should make sure to perform this lab in a dedicated branch.

You can achieve this in two ways:

Alternative 1: Via VSCode's terminal

1. If a Terminal is not in sight, you can alternatively open it by expanding the Terminal-dropdown on the top, and selecting New Terminal

2. Now, execute the following PowerShell commands:

   git checkout -b 'interoperability'
   git push --set-upstream 'origin' 'interoperability'

Alternative 2: Via VSCode's UI

1. Select the current branch on the bottom left of VSCode

   

2. Select + Create new branch in the opening dropdown

   

3. Enter the new branch name interoperability

4. Push the new branch to your GitHub fork by selecting Publish Branch to the left in the 'Source Control' tab

   

Step 2 - Convert to ARM

In this step, you will use one of CARML's utilities to convert the repository from Bicep-based to ARM-based. This includes the conversion of the templates themselves, the update of the pipelines that use them, as well as the cleanup of both metadata & redundant Bicep-specific folders.

1. Navigate to the utilities/tools folder. You will find a PowerShell file titled ConvertTo-ARMTemplate.ps1. The script allows you to do the following:

   • Remove existing deploy.json files
   • Take the modules written in Bicep within your CARML library and convert them to ARM JSON syntax (Excludes child-modules by default).
   • Remove Bicep metadata from the new JSON files
   • Remove Bicep files and folders
   • Update existing GitHub workflow as well as ADO pipeline YAML files to replace .bicep with .json so that deployments now use the newly created .json files

2. First you need to load the script. There are different ways to do this, but for our purposes, right-click on the ConvertTo-ARMTemplate.ps1 file, and select Copy Path.

   

3. Open an existing or new PowerShell terminal session and execute the following snippet:

   . '<path of script>' -ConvertChildren
   
   # For example
   . 'C:/dev/Carml-lab/ResourceModules/utilities/ConvertTo-ARMTemplate.ps1' -ConvertChildren

   Upon hitting enter the script will start running. You will notice several Bicep 'Warnings' as part of the output. This is normal and the script will continue.

4. By default, the script will take all the modules found under the arm folder that contain a .bicep file, begin converting from Bicep to JSON, and conduct all the optional functions highlighted before.

5. Once finished, you will see that your Bicep files have now all been converted to ARM Templates. These ARM Templates will work with your existing parameter files and workflows!

   

Step 3 - (Optional) Leverage Azure DevOps Pipelines

Similar to Bicep's adoption, 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 from Azure DevOps. The following demonstrates how CARML can enable users to perform Infrastructure-as-Code deployments using Azure DevOps Pipelines:

1. Before starting, make sure that you have the following installed:

   • Azure CLI
   • Azure CLI Extension: Azure DevOps
   • An Azure DevOps Project

2. Go to the Azure DevOps Portal and log in.

3. To create a new DevOps project, choose the organization that you wish to create the project under. Then select + New Project on the top right corner of the page.

4. Go to your Azure DevOps project and select Pipelines on the left-hand side

   

5. Next, click the more actions : icon and select Manage Security

   

6. The pipeline permissions for the project will appear. Scroll to the bottom and find the <ProjectName> Build Service under Users. Select the Build Service. Locate the Edit build pipeline setting and change it from Not Set to Allow

   

   The changes will automatically be saved/updated and you can close the permissions panel once done.

7. The next step(s) should only be done when the repo is in GitHub. We will be establishing a service connection between Azure DevOps and GitHub:

   1. Next, click on Project Settings on the bottom-left corner of the page. Scroll towards the bottom of the Project Settings panel, locate the Service Connections tab

      

   2. Click Create New Service Connection

   3. Scroll, find, and select GitHub and click next.

      

      Note if an organization is using GitHub Enterprise to host their repository, GitHub Enterprise must be selected instead.

   4. Make sure Grant Authorization is selected under Authentication Method. Then open the drop-down under OAuth Configuration and select AzurePipelines.

   5. Click Authorize.

   6. A new window will appear taking you to GitHub. If you are already logged into GitHub, it will automatically authenticate and authorize the service connection. If not, it will prompt you. Follow the steps and once finished you should see the user as part of the service connection:

      

   7. The name of the service connection will be automatically populated. For simplicity of this lab, rename the service connection to GitHubConnection. You will need this name later. Click save once finished.

   8. You will be returned to the Service Connection settings page and should see your GitHub connection.

8. We will now need a Service Connection between Azure DevOps and our Azure Subscription. Click on New Service Connection at the top right corner:

   1. Scroll, find, and select AzureResourceManager and click next.
   2. For this lab we will be using Service Principal (manual) which allows you to re-use the same service principal you used for GitHub.
   3. Fill in all the required data.
   4. Name your Service Connection AzureConnection. You will need this later. Click Verify and save on the bottom right. corner.

9. You should now have two (2) Service Connections under your DevOps project, the GitHubConnection and the AzureConnection.

10. Return to your Visual Studio Code window. Make sure you are still located on your fork of CARML and in your interoperability branch.

11. Navigate to the .azuredevops/pipelineVariables folder. You will find a YAML file titled global.variables.yml. Open the file and update the serviceConnection to AzureConnection and save the file. This variable is passed to the pipeline jobs, which in turn automatically use the previously created service connection.

12. Navigate to the tools/AzureDevOps folder. You will find a PowerShell file titled Register-AzureDevOpsPipeline.ps1.

13. Right-click on the Register-AzureDevOpsPipeline.ps1 file, and select Copy Path

14. Open an existing or new PowerShell terminal session and execute the following snippet:

    . 'Register-AzureDevOpsPipeline.ps1'
    
    # For example
    . 'C:/dev/Carml-lab/ResourceModules/utilities/Register-AzureDevOpsPipeline.ps1'

    Upon hitting enter the script will load the function(s) specified in the file into your Powershell session.

15. Update and copy the following code block:

        $inputObject = @{
            OrganizationName                 = '<Name of your DevOps Organization>'
            ProjectName                      = '<Name of your DevOps Project>'
            SourceRepository                 = '<Forked Github Repo Name>'
            Branch                           = '<Name of source branch>' 
            GitHubServiceConnectionName      = 'GitHubConnection'
            AzureDevOpsPAT                   = '<Placeholder>'
        }
        Register-AzureDevOpsPipeline @inputObject

16. Paste the code block into the PowerShell terminal and hit enter

17. Once executed, the script will run and create Azure DevOps pipelines based on the YAML files you have in the .azuredevops/modulePipelines folder. Once finished you will be able to go to the Azure DevOps portal and see pipelines that were created as part of this process.

18. This script is re-deployable, as all existing pipeline will not be affected. You can use this process to automatically create new pipelines for new modules/workloads!