Document F12 for Bicep Registry

[puicchan]

1. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/private-module-registry?tabs=azure-cli#publish-files-to-registry: mention it is now possible to publish Bicep modules with source code. Commands: ps: Publish-AzBicepModule -FilePath ./storage.bicep -Target br:exampleregistry.azurecr.io/bicep/modules/storage:v1 -DocumentationUri https://www.contoso.com/exampleregistry.html -WithSource az cli: az bicep publish --file {bicep_file} --target "br:{registry}/{module_path}:{tag}" --documentationUri {documentationUri} --with-source

2. Document F12 in https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/visual-studio-code?tabs=CLI#restore-bicep-modules. If a module is published with source code to a registry, you can use F12 (Go to Definition) to see the Bicep Code. Note that if the Bicep module references a module in a Private Registry, the ACR end point will be visible. To hide the full end point, you can configure an alias for the private registry.

Related to https://github.com/Azure/bicep/issues/13782

[StephenWeatherford]

NOTES:

THe first article (Create private registry for Bicep module - Azure Resource Manager | Microsoft Learn) goes into how the files look in the ACR. We should probably show what it looks like if it has source code published (there's another layer in the manifest containing the source.tgz file, which will also end up in the local registry cache when the module is restored).

Document F12 in https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/visual-studio-code?tabs=CLI#restore-bicep-modules. If a module is published with source code to a registry, you can use F12 (Go to Definition) to see the Bicep Code. Note that if the Bicep module references a module in a Private Registry, the ACR end point will be visible. To hide the full end point, you can configure an alias for the private registry.

Example: Suppose the module you're publishing is named 'module1' and it references a separate, private module 'module2' eg:

module module2 'br:myregistry.azurecr.io/myrepo/mymodule2:v1' = {
  name: 'module2'
}

If module1 is published with source, then clients that reference module1 will be able to F12 to see module1's source. Thus they will see the string br:myregistry.azurecr.io/myrepo/mymodule2:v1 which contains the registry ID. If they don't like that, they can add an alias to the bicepconfig.json file, e.g.:

{
  "moduleAliases": {
    "br": {
      "myprivatereg": {
        "registry": "myregistry.azurecr.io",
        "modulePath": "myrepo"
      }
    }
  }
}

and then instead reference module2 like this:

module module2 'br/myprivateregistry:mymodule2:v1' = {
  name: 'module2'
}

The bicepconfig.json is not published with the sources, so clients of module1 will not be able to see module2's registry id.

Note however that they will be able to F12 and see module's compiled JSON source (it will be part of module1's compiled JSON so can't be hidden). This is not new, it's always been like this.

Also, if module2 was published with source as well, then clients of module1 can theoretically see module2's registry ID because it's required in order for module1 clients with access to module2's registry to be able to F12 on module2 and see its source. The registry ID will be located in the __metadatafile file inside the source.tgz file.

Feel free to set up a meeting for questions.

[StephenWeatherford]

Also, note that the ability to use --with-source is currently under an experimental flag (https://github.com/Azure/bicep/issues/13782), so not sure if you want to push the docs before we remove it (likely the v0.27 release at beginning of May).

[StephenWeatherford]

NOTE: the experimental flag has been removed, so --with-source will officially ship as part of 0.27

[mumian]

@puicchan, @StephenWeatherford - I have a module published with two different versions, one with WithSource and the other without the WithSource switch. I am able to see the source by clicking F12 from VSCode for both versions.

[puicchan]

@mumian, did you see Bicep code for both versions? You should see Bicep code only for the version published with (Bicep) source, else you see the compiled JSON.

[mumian]

@puicchan - I realize 0.27 is not released yet. Also, do you know what versions of the Azure PowerShell and Azure CLI support the withSource switch?

[mumian]

@StephenWeatherford, @puicchan - If you hover over a symbolic name, it gives the context menu where you can click "View Documentation". Are you going to do the same for "Go to definition"?