Change the directory structure of the `src/bicep` folder #561

brooke-hamilton · 2021-12-07T14:19:25Z

Benefit/Result/Outcome

Improved folder structure for the src/bicep folder.

Description

This is based on a discussion in #532.

Acceptance Criteria

Put modules in the core folder that are scoped to MLZ concepts, like spoke network, and call modules in the modules folder. Generally, modules in this folder will execute modules in the modules folder.
Put modules in the modules folder that are scoped to Azure concepts, like storage accounts. Generally, a module in this folder will not execute other modules.
Add a README.md to the core folder explaining the purpose of the templates in that folder.
Add a README.md to the modules folder explaining the purpose of the templates in that folder.
Update the naming convention for all Bicep files to use all lower case letters and add dashes to separate words (making the names consistent with the Terraform files.)
Change the name of newWorkload to tier3 to match the name of the Terraform template.
Change the Bicep directory structure to match the following (NOTE: the folder structure is what is specified. The exact file names may not match what is below.):

├── add-ons
│   ├── remote-access
│   │   ├── README.md
│   │   ├── main.json
│   │   └── remote-access.bicep
│   ├── tier3
│   │   ├── modules
│   │   │   └── hub-network-peering.bicep
│   │   ├── README.md
│   │   └── tier3.bicep
├── core
│   │── hub-network.bicep
│   │── hub-network-peerings.bicep
│   │── README.md
│   │── remote-access.bicep
│   │── spoke-network.bicep
│   └── spoke-network-peering.bicep
├── examples
│   ├── app-service-plan
│   │   ├── modules
│   │   │   ├── appServicePlan.bicep
│   │   │   └── appServiceSettings.bicep
│   │   ├── README.md
│   │   ├── app-service-plan.bicep
│   │   └── app-service-plan.json
│   ├── container-registry
│   │   ├── modules
│   │   │   └── container-registry.bicep
│   │   ├── README.md
│   │   └── container-registry.bicep
│   ├── inherit-tags
│   │   ├── README.md
│   │   └── inherit-tags.bicep
│   ├── keyvault
│   │   ├── modules
│   │   │   └── key-vault.bicep
│   │   ├── README.md
│   │   ├── key-vault.bicep
│   │   └── key-vault.json
│   ├── sentinel
│   │   ├── README.md
│   │   └── sentinel.tf
│   └── README.md
├── form
│   └── mlz.portal.json
├── modules
│   ├── policies
│   │   ├── CMMC-policyAssignmentParameters.json
│   │   ├── IL5-policyAssignmentParameters.json
│   │   └── NIST-policyAssignmentParameters.json
│   ├── bastion-host.bicep
│   ├── central-logging.bicep
│   ├── firewall.bicep
│   ├── linux-virtual-machine.bicep
│   ├── log-analytics-diagnostic-logging.bicep
│   ├── log-analytics-workspace.bicep
│   ├── network-interface.bicep
│   ├── network-security-group.bicep
│   ├── policy-assignment.bicep
│   ├── private-link.bicep
│   ├── public-ip-address.bicep
│   ├── README.md
│   ├── resource-group.bicep
│   ├── role-assignment.bicep
│   ├── route-table.bicep
│   ├── security-center.bicep
│   ├── storage-account.bicep
│   ├── subnet.bicep
│   ├── virtual-network-peering.bicep
│   ├── virtual-network.bicep
│   └── windows-virtual-machine.bicep
├── README.md
├── bicepconfig.json
├── mlz.bicep
├── mlz.json

The text was updated successfully, but these errors were encountered:

brooke-hamilton · 2021-12-13T16:15:34Z

Before implementing this, we need to do a couple of things with the proposed structure:

Update the names of the folders called 'core' and 'modules' to make sure the relationships are clear, i.e., things in core call things in modules, and modules are broadly reusable.
Make sure the initial experience of viewing this structure makes the purpose of the files and the folders obvious.

brooke-hamilton · 2022-01-10T14:00:32Z

Another input on this: we had feedback related to auto-generating documentation that each template should be in its own folder so that a README.md document can be generated within the same folder to show parameter docs. That would be in alignment with the Terraform templates.

brooke-hamilton · 2022-01-13T20:41:39Z

Based on discussions above, here's another proposal for the directory structure in src/bicep:

All Bicep files are lower case to be consistent with the Terraform files and to avoid casing issues between platforms in Bicep.
Added core folder to contain Bicep code that calls individual modules.
Put each core item into its own folder and added a README.md document.
Renamed newWorkload to tier3 to be consistent with the Terraform template.
Removed the build folder.

├── add-ons
│   ├── remote-access
│   │   ├── README.md
│   │   ├── main.json
│   │   └── remote-access.bicep
│   └── tier3
│       ├── modules
│       │   └── hub-network-peering.bicep
│       ├── README.md
│       └── tier3.bicep
├── core
│   ├── hub-network
│   │   ├── README.md
│   │   └── hub-network.bicep
│   ├── hub-network-peerings
│   │   ├── README.md
│   │   └── hub-network-peerings.bicep
│   ├── remote-access
│   │   ├── README.md
│   │   └── remote-access.bicep
│   ├── spoke-network
│   │   ├── README.md
│   │   └── spoke-network.bicep
│   └── spoke-network-peering
│       ├── README.md
│       └── spoke-network-peering.bicep
├── examples
│   ├── app-service-plan
│   │   ├── modules
│   │   │   ├── appServicePlan.bicep
│   │   │   └── appServiceSettings.bicep
│   │   ├── README.md
│   │   ├── app-service-plan.bicep
│   │   └── app-service-plan.json
│   ├── container-registry
│   │   ├── modules
│   │   │   └── container-registry.bicep
│   │   ├── README.md
│   │   └── container-registry.bicep
│   ├── inherit-tags
│   │   ├── README.md
│   │   └── inherit-tags.bicep
│   ├── keyvault
│   │   ├── modules
│   │   │   └── key-vault.bicep
│   │   ├── README.md
│   │   ├── key-vault.bicep
│   │   └── key-vault.json
│   ├── sentinel
│   │   ├── README.md
│   │   └── sentinel.tf
│   ├── README.md
│   └── deploymentVariables.json
├── form
│   └── mlz.portal.json
├── modules
│   ├── policies
│   │   ├── CMMC-policyAssignmentParameters.json
│   │   ├── IL5-policyAssignmentParameters.json
│   │   └── NIST-policyAssignmentParameters.json
│   ├── bastion-host.bicep
│   ├── central-logging.bicep
│   ├── firewall.bicep
│   ├── linux-virtual-machine.bicep
│   ├── log-analytics-diagnostic-logging.bicep
│   ├── log-analytics-workspace.bicep
│   ├── network-interface.bicep
│   ├── network-security-group.bicep
│   ├── policy-assignment.bicep
│   ├── private-link.bicep
│   ├── public-ip-address.bicep
│   ├── resource-group.bicep
│   ├── role-assignment.bicep
│   ├── route-table.bicep
│   ├── security-center.bicep
│   ├── storage-account.bicep
│   ├── subnet.bicep
│   ├── virtual-network-peering.bicep
│   ├── virtual-network.bicep
│   └── windows-virtual-machine.bicep
├── README.md
├── bicepconfig.json
├── mlz.bicep
├── mlz.json

shawngib · 2022-01-13T21:14:57Z

Seems to cross streams between opinion and none opinion in modules, also appears very busy with separate folders in core and separate read me. Can't core modules just include comments and descriptions.

vidyambala · 2022-01-13T23:03:31Z

Looks really great. Out of curiosity, do we need a hub-network-peering.bicep module in tiers as we have same module in core directory?

brooke-hamilton · 2022-01-14T14:08:26Z

Seems to cross streams between opinion and none opinion in modules, also appears very busy with separate folders in core and separate read me. Can't core modules just include comments and descriptions.

Good point that it's inconsistent to have each template in a subfolder in core and not do that in modules. We could choose one of these options:

Remove the subfolders in core and not have README docs for every module--just have parameter decorators in the template.
Add subfolders and README files to modules. We talked about modules being the reusable templates, so maybe those should have READMEs.
Have a different folder layout between core and modules.

I'm 100% OK with any of these options. It's true that having subfolders for every module is busy and causes longer paths.

brooke-hamilton · 2022-01-14T14:12:55Z

Looks really great. Out of curiosity, do we need a hub-network-peering.bicep module in tiers as we have same module in core directory?

Good call: those two modules appear to be nearly exact copies. Yes I think we can remove the one in tier3/modules and use the one in core instead.

brooke-hamilton · 2022-02-06T17:08:26Z

Proposed updates to acceptance criteria and updated folder structure:

Add a README.md to the core folder explaining the purpose of the templates in that folder.
Add a README.md to the modules folder explaining the purpose of the templates in that folder.
Update the naming convention for all Bicep files to use all lower case letters and add dashes to separate words (making the names consistent with the Terraform files.)
Change the name of newWorkload to tier3 to match the name of the Terraform template.
Change the Bicep directory structure to match the following:

├── add-ons
│   ├── remote-access
│   │   ├── README.md
│   │   ├── main.json
│   │   └── remote-access.bicep
│   └── tier3
│       ├── modules
│       │   └── hub-network-peering.bicep
│       ├── README.md
│       └── tier3.bicep
├── core
│   │── hub-network.bicep
│   │── hub-network-peerings.bicep
│   │── README.md
│   │── remote-access.bicep
│   │── spoke-network.bicep
│   └── spoke-network-peering.bicep
├── examples
│   ├── app-service-plan
│   │   ├── modules
│   │   │   ├── appServicePlan.bicep
│   │   │   └── appServiceSettings.bicep
│   │   ├── README.md
│   │   ├── app-service-plan.bicep
│   │   └── app-service-plan.json
│   ├── container-registry
│   │   ├── modules
│   │   │   └── container-registry.bicep
│   │   ├── README.md
│   │   └── container-registry.bicep
│   ├── inherit-tags
│   │   ├── README.md
│   │   └── inherit-tags.bicep
│   ├── keyvault
│   │   ├── modules
│   │   │   └── key-vault.bicep
│   │   ├── README.md
│   │   ├── key-vault.bicep
│   │   └── key-vault.json
│   ├── sentinel
│   │   ├── README.md
│   │   └── sentinel.tf
│   ├── README.md
│   └── deploymentVariables.json
├── form
│   └── mlz.portal.json
├── modules
│   ├── policies
│   │   ├── CMMC-policyAssignmentParameters.json
│   │   ├── IL5-policyAssignmentParameters.json
│   │   └── NIST-policyAssignmentParameters.json
│   ├── bastion-host.bicep
│   ├── central-logging.bicep
│   ├── firewall.bicep
│   ├── linux-virtual-machine.bicep
│   ├── log-analytics-diagnostic-logging.bicep
│   ├── log-analytics-workspace.bicep
│   ├── network-interface.bicep
│   ├── network-security-group.bicep
│   ├── policy-assignment.bicep
│   ├── private-link.bicep
│   ├── public-ip-address.bicep
│   ├── README.md
│   ├── resource-group.bicep
│   ├── role-assignment.bicep
│   ├── route-table.bicep
│   ├── security-center.bicep
│   ├── storage-account.bicep
│   ├── subnet.bicep
│   ├── virtual-network-peering.bicep
│   ├── virtual-network.bicep
│   └── windows-virtual-machine.bicep
├── README.md
├── bicepconfig.json
├── mlz.bicep
├── mlz.json

glennmusa · 2022-02-07T14:42:27Z

I think that's a step in the right direction and is actionable today.

Glancing into the crystal ball, if there's ever intent to machine generate parameters.json or READMEs for the individual modules, the separate folder for each deployable unit might make sense:

├── add-ons
│   ├── remote-access
│   │   ├── README.md (with auto-gen'd docs)
│   │   ├── parameters.json (with auto-gen'd values)
│   │   ├── main.json
│   │   └── main.bicep
│   └── tier3
│       ├── modules
│       │   └── hub-network-peering.bicep
│       ├── README.md (with auto-gen'd docs)
│       ├── parameters.json (with auto-gen'd values)
│       ├── main.json
│       └── main.bicep
├── core
│   │── hub-network
│   │   ├── README.md (with auto-gen'd docs)
│   │   ├── parameters.json (with auto-gen'd values)
│   │   ├── main.json
│   │   └── main.bicep
│   │── hub-network-peerings
│   │   ├── README.md (with auto-gen'd docs)
│   │   ├── parameters.json (with auto-gen'd values)
│   │   ├── main.json
│   │   └── main.bicep

I want to say this is similar to the out-of-the-box directory structure required for some of the Terraform docs generations tools, but @Chambras can correct me where I'm wrong.

brooke-hamilton · 2022-02-07T15:47:46Z

I think we need the folders for the add-ons and examples, for the reasons you said, and also because we are going to implement a standard pattern for those which provides examples for several ways to set parameters.

For the core and modules folders, will anyone call those things separately? I think we want to get to a place where the Bicep files in core are reusable elements of MLZ that can be deployed together or separately. The Bicep files in modules should also be reusable, and mostly they are.

However, the drawback of creating the folders in core and modules is the extra-long paths and nesting it creates. If nobody ever reuses those Bicep files then having the folders and generated docs/parameters files is unnecessary complexity and a pain to navigate when someone is trying to understand the relationships among the Bicep files.

We could say YAGNI for now and add the folders when we need them, which would have the benefit of being simple now and the drawback of maybe having yet another folder structure change later (better to do it all at once.)

Or we could say do it now because we think nested folders will be needed, which would have the benefit of preventing two separate refactorings and the drawback of complexity that isn't useful right away.

brooke-hamilton · 2022-02-07T16:42:52Z

Based on team consensus we will have no subfolders in core and modules until we find a need for having subfolders.

I will update the acceptance criteria to align with this.

brooke-hamilton · 2022-02-09T21:38:50Z

Based on team consensus we will have no subfolders in core and modules until we find a need for having subfolders.

I will update the acceptance criteria to align with this.

Done.

brooke-hamilton added core New feature or request needs triage labels Dec 7, 2021

brooke-hamilton mentioned this issue Dec 7, 2021

Modify Directory structure to reflect shareable components and dependencies #532

Closed

brooke-hamilton added the bicep Related to Bicep code label Dec 7, 2021

brooke-hamilton removed the needs triage label Feb 3, 2022

brooke-hamilton added this to Mission Landing Zone 2022 Feb 3, 2022

brooke-hamilton moved this to Triage in Mission Landing Zone 2022 Feb 3, 2022

brooke-hamilton self-assigned this Feb 7, 2022

brooke-hamilton moved this from Triage to Backlog in Mission Landing Zone 2022 Feb 7, 2022

brooke-hamilton moved this from Backlog to Deferred in Mission Landing Zone 2022 Feb 7, 2022

brooke-hamilton removed their assignment Feb 10, 2022

brooke-hamilton moved this from Future Backlog to Current Backlog in Mission Landing Zone 2022 Feb 14, 2022

brooke-hamilton mentioned this issue Mar 1, 2022

Roadmap for Mission LZ #645

Closed

Breanna-Stryker self-assigned this Mar 4, 2022

Breanna-Stryker moved this from Current Backlog to In Progress in Mission Landing Zone 2022 Mar 4, 2022

lisamurphy-msft mentioned this issue Mar 30, 2022

Update storageAccount.bicep to require minimum TLS 1.2 #696

Closed

Breanna-Stryker mentioned this issue Mar 31, 2022

Breestryker/restructure code #699

Merged

4 tasks

lisamurphy-msft closed this as completed in #699 Apr 4, 2022

Repository owner moved this from In Progress to Done in Mission Landing Zone 2022 Apr 4, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Change the directory structure of the `src/bicep` folder #561

Change the directory structure of the `src/bicep` folder #561

brooke-hamilton commented Dec 7, 2021 •

edited

Loading

brooke-hamilton commented Dec 13, 2021 •

edited

Loading

brooke-hamilton commented Jan 10, 2022 •

edited

Loading

brooke-hamilton commented Jan 13, 2022

shawngib commented Jan 13, 2022

vidyambala commented Jan 13, 2022

brooke-hamilton commented Jan 14, 2022

brooke-hamilton commented Jan 14, 2022

brooke-hamilton commented Feb 6, 2022

glennmusa commented Feb 7, 2022 •

edited

Loading

brooke-hamilton commented Feb 7, 2022

brooke-hamilton commented Feb 7, 2022

brooke-hamilton commented Feb 9, 2022

Change the directory structure of the src/bicep folder #561

Change the directory structure of the src/bicep folder #561

Comments

brooke-hamilton commented Dec 7, 2021 • edited Loading

Benefit/Result/Outcome

Description

Acceptance Criteria

brooke-hamilton commented Dec 13, 2021 • edited Loading

brooke-hamilton commented Jan 10, 2022 • edited Loading

brooke-hamilton commented Jan 13, 2022

shawngib commented Jan 13, 2022

vidyambala commented Jan 13, 2022

brooke-hamilton commented Jan 14, 2022

brooke-hamilton commented Jan 14, 2022

brooke-hamilton commented Feb 6, 2022

glennmusa commented Feb 7, 2022 • edited Loading

brooke-hamilton commented Feb 7, 2022

brooke-hamilton commented Feb 7, 2022

brooke-hamilton commented Feb 9, 2022

Change the directory structure of the `src/bicep` folder #561

Change the directory structure of the `src/bicep` folder #561

brooke-hamilton commented Dec 7, 2021 •

edited

Loading

brooke-hamilton commented Dec 13, 2021 •

edited

Loading

brooke-hamilton commented Jan 10, 2022 •

edited

Loading

glennmusa commented Feb 7, 2022 •

edited

Loading