Azure/bicep

integrate bicep CLI into az CLI and az powershell

alex-frankel opened this issue · 11 comments

The following commands should all work in Az CLI and Azure PowerShell respectively:

Compile and deploy a bicep file without emitting a main.json file

az deployment group create -f ./main.bicep -g my-rg
New-AzResourceGroupDeployment -TemplateFile ./main.bicep -ResourceGroupName my-rg

Run what-if and ask for confirmation before deploying:

az deployment group create -f ./main.bicep -g my-rg -c
New-AzResourceGroupDeployment -TemplateFile ./main.bicep -ResourceGroupName my-rg -Confirm

Transpile a .bicep file to its equivalent .json file

az bicep build ./main.bicep
Invoke-AzBicepBuild -File ./main.bicep

Both command line tools should check if the bicep exe is installed on the machine. If it's not, the user should be prompted to do so in an easy way. Similar to how kubectl is handled today for AKS command-line scenarios.

*** added 1/6 ***

Decompile an ARM Template into it's equivalent .bicep file

az bicep decompile ./main.json
Invoke-AzBicepDecompile -File ./main.json

Needs to support source-mapping of some kind. Since end user's wont' be interfacing with template JSON anymore, we need to make sure that errors returned during a deployment are mapped to the relevant spot in the bicep file. It should degrade gracefully.

  • If there is a line number in the JSON, that should map to a line number in bicep
  • If there is no line number, but there is a resource name and type, we should be able to point you there in the bicep file

Described in more detail in #855

Discussed with PowerShell and Az CLI team, and our plan will be to follow the AKS/kubectl model which does the following:

  • There is a dedicated cmdlet/command for installing kubectl (az aks install-cli)
  • Any commands that need kubectl will expect the binary to exist in a well-known location. If there, it will call the binary. If it is not there, the user will be prompted to run the above command.

As part of this issue, we should aim to start #800 in parallel.

Discussed with @rynowak, who brought up that it would be helpful to be able to point to a custom install location of bicep so that you can use private or pre-release builds of bicep if you want to opt in. Not sure how AKS implements it, but if it is just pointing to well known PATHs, then it should be straightforward for user's to replace the binary manually and not build anything additional.

miqm commented

@alex-frankel - will bicep be included in cli docker image?

Good question. I think if we do nothing, it'll have the default version of Az CLI installed, so you will be prompted to install bicep when a relevant deployment command is invoked. I will add a note to see if we can have this installed on the image so that step doesn't need to happen.

@alex-frankel Would this also include support for validating deployments (az deployment group validate) or just the creation of deployments?

It should include any cli command/cmdlet that uses the --template-file/-TemplateFile, so the validation commands should be covered. Thanks for the reminder as we have a bad tendency to forget about this command!

What is the progress with supporting deploying .bicep files using Az PowerShell and AZ CLI? What support can we expect as a first step? I looked at the code implemented so far and open PRs, and it seems that Azure CLI will support a lot more things thanks to @shenglol.

Also created an issue in the azure-powershell repo with some findings on the code implemented so far, Azure/azure-powershell#14289.

The initial scope of support is to install the bicep CLI if it is not present and to automatically transpile the bicep code if it is provided as the value for the -TemplateFile parameter. PowerShell team is a bit more resource constrained so their implementation is going to be less feature rich than Az CLI at least to start. Let's see what powershell team has to say about the issue you filed - thank you for reporting the issues you've found.

Both Az CLI and Az PS support should be available in the next release that is set for the first week of March

Both PS and CLI work for this has been merged and will be available on 3/2.

There is a slight difference in functionality. In Az CLI, we will install a self-contained version of bicep for CLI to use the first time you use a command that requires bicep. In Az PS, you need to manage the install of bicep yourself and ensure it is available on the PATH. We are planning to add an Install-AzBicep cmdlet, but this will not be in the first release.

@tfitzmac - I think it will be important to doc these discrepancies. Do you want me to update the installation instructions that are in this repo or will you plan to take care of this as part of the move to MS Docs?

@alex-frankel - I think we should update in the Bicep repo. When the doc has been published, we can decide if we want to maintain both places.

Just tested the Azure CLI code using the installer from the PR build. It works great! Only found one minor issue, Azure/azure-cli#17083.

@alex-frankel I agree that it's very important to doc the difference between Azure CLI and Az PowerShell. And also write a note about the install path for the self-contained version installed by Azure CLI in %userprofile%\.Azure\bin\. Depending on how you've been installing Bicep CLI you might end up with bicep.exe in three different directories, and possibly different versions for Windows users (PowerShell script installer, Windows installer and Azure CLI installed).