Modules need versions

[ChristopherGLewis]

Is your feature request related to a problem? Please describe.
As I've progressed in my first real-world Bicep deploy I've hit a point where it would be extremely helpful to have a module version.

While I'm able to maintain this through my code repo and in general just rewriting how my modules are used, I can see that some of my rewrites would be solved with a module version field.

I've got a repo set up like this:

\ Root
   +- Network
       +- modules
   +- VM
       +- modules

Both Network and VM ended up with a pip.bicep module. Network's pip was for Azure Bastion, and the VM's was for its NIC.

Initially, the PIP with the VM looked like this:

param pipName string
param pipSKU string {
   default: 'Basic'
   allowed: [
     'Basic'
     'Standard'
   ]
}

resource publicIp 'Microsoft.Network/publicIPAddresses@2020-06-01' = {
  name: pipName
  location: resourceGroup().location
  sku: {
     name: pipSKU
  }
  properties: {
    publicIPAllocationMethod: 'Dynamic'
  }
}

output id string = publicIp.id

Later, the Network pip required a passed in allocation method

param pipName string
param pipSKU string {
   default: 'Basic'
   allowed: [
     'Basic'
     'Standard'
   ]
}
param pipAllocationMethod string {
   default: 'Dynamic'
   allowed: [
     'Dynamic'
     'Static'
   ]
}
resource publicIp 'Microsoft.Network/publicIPAddresses@2020-06-01' = {
  name: pipName
  location: resourceGroup().location
  sku: {
     name: pipSKU

  }
  properties: {
    publicIPAllocationMethod: pipAllocationMethod
    //dnsSettings: {
    //  domainNameLabel: dnsLabelPrefix
    //}
  }
}

output id string = publicIp.id

Since these are in separate folders, not a problem. But I'm wanting to move towards a structure like this:

\ Root
   +- modules
   +- Network
   +- VM

with shared modules.

I can force this by naming my modules with a version (pip@1.0.bicep vs pip@1.1.bicep) but then I'd like bicep to also work with just pip.bicep or pip@latest.bicep. This might put a lot more pressure on Bicep to figure out versioning ( date vs semantic - is @2020.12.30 newer than @1.0 ?)

I did some reading of issue #58 and can see where this discussion went on implementing later, but I'd like to enter this for better tracking.

Describe the solution you'd like
I'd like to see a thought-out plan for this, that includes local repos, local shared libraries, the whole "Bicep Module Registry" and how modules look in an Azure object library.

[alex-frankel]

We definitely need to have a module versioning story as a prerequisite for the registry and external modules. What we are not yet clear on is the need for versions of a local module. For this specific case, would you say these are two different versions of the same module or two different modules for different use cases? It seems like the latter, so potentially these could have two different names like pip-for-vm.bicep and pip-for-network.bicep. Thoughts?

[ChristopherGLewis]

Yes, I can certainly see that pip-for-x.bicep working. What I am typically seeing is that I create a bicep/arm file as a minimum viable product, then over time it evolves in functionality and I update my files.

My thoughts on local modules are the same as a repository version - I'm on a team who share code, and in order to prevent a small change in a module from causing cascading changes or even breaking a build, I'd rather have a version stamp that would mimic proper library development.

And I strongly encourage semantic versioning as the way to go in the future. Date based versions are horrible for tracking functionality changes.

[ChristopherGLewis]

As I've been playing with this I've also been working on a major terraform project. Looking at TF right now, it's module version story took an interesting implementation path. Version is not embedded in code it's relying on an external git repo with git tagging. This causes all sorts of issues with source-based solutions since there's no way to version a module file.

For my bicep code, what I've settled on is embedding the version into the file name

\ Root
   +- Network
       +- modules
         + pip@2021-01-01.bicep
         + pip@2021-02-01.bicep  
   +- VM
       +- modules

Then referencing the module via

module pip './modules/pip@2021-01-01.bicep' = {
 name: 'aaa'
 params: {
 }
}

A couple of notes regarding this:

• adding a version to the name allows for multiple versions in a single directory. An alternative we looked at was:

\ Root
   +- Network
       +- modules
         +- pip
            +- 2021-01-01
                + pip.bicep
            +- 2021-02-01
                + pip.bicep

and

module pip './modules/pip/2021-01-01/pip.bicep' = {
 name: 'aaa'
 params: {
 }
}

• not having a field in the module definition bothers me. It's in the file name, but not anywhere else

moduleVersion: 2021-01-01  <---  I like this
param pipName string
param pipSKU string
param pipAllocationMethod string
resource publicIp 'Microsoft.Network/publicIPAddresses@2020-06-01' = {
  name: pipName
  location: resourceGroup().location
  sku: {
     name: pipSKU
  }
  properties: {
    publicIPAllocationMethod: pipAllocationMethod
  }
}
output id string = publicIp.id

• I know ARM uses date versions, but semantic versioning is much better. I do like terraform's version ranges, and I can't see that working well with YYYY-MM-DD (or is it YYYY-DD-MM?) formats. My challenge with embedding the filename is that this drives a nail into the version. I know there's a separate talk of using '@latest' formats for resources but I'm not sure how this would work with modules (do we enforce file name standards and only YYYY-MM-DD?) or do we parse a tree to find all modules, parse the module version field and get the latest?

[JustinGrote]

For now git submodules with version tags works really well, just import your other module repository in the existing repository as a git submodule and "pin" it to a specific version tag.

[alex-frankel]

Just stumbled across this one in a search result. We certainly now have module versions for in the registry :)