Introducing Utility Modules #947
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
microsoft-github-policy-service
bot
added
the
Needs: Triage 🔍
matebarabas
added
Type: Documentation 📄
matt-FFFFFF
reviewed
May 22, 2024
|
|
||
| {{< hint title="PREVIEW" >}} | ||
|
|
||
| The concept of **Utility Modules** will be introduced gradually, through some initial examples. The definition above is subject to change as additional details are worked out. The required automated tests and other workflow elements will be derived from the Pattern Modules' CI environment as the concept matures. Utility modules will be kept under the `avm/utl` folder in the respective Bicep or Terraform repository. Related documentation (functional and non-functional requirements, etc.) will also be published along the way. |
There was a problem hiding this comment.
This is very Bicep specific. Can we remove or move to Bicep specific section?
There is no pattern module CI environment for TF
There was a problem hiding this comment.
This is just a temporary hint until more specific information is available. There's no place else (for now) to move anything to, so I would leave this here, however:
- I'll rephrase the sentence with the
avm/utlfolder, as indeed, that's bicep specific. - Let's tweak that CI environment sentence if you have any suggestions. Even if it's not a full-blown CI environment, there are certain tests that we run for TF ptn modules, right?
I think the rest of the note applies on both languages.
There was a problem hiding this comment.
@matt-FFFFFF, I've updated the text, please take another look. Thanks!
| | --------------------- | ---------- | -------------- | | ||
| |**Resource Module** | Deploys a primary resource with WAF high priority/impact best practice configurations set by default, e.g., RBAC, Locks, Private Endpoints etc. (if supported). See [What does AVM mean by “WAF Aligned”?](/Azure-Verified-Modules/faq/#what-does-avm-mean-by-waf-aligned) <br><br> They MAY include related resources, e.g. VM contains disk & NIC. Focus should be on customer experience. A customer would expect that a VM module would include all required resources to provision a VM. <br><br> Furthermore, Resource Modules MUST NOT deploy external dependencies for the primary resource. E.g. a VM needs a vNet and Subnet to be deployed into, but the vNet will not be created by the VM Resource Module. <br><br> Finally, a resource can be anything such as Microsoft Defender for Cloud Pricing Plans, these are still resources in ARM and can therefore be created as a Resource Module. | People that want to craft bespoke architectures that default to WAF best practices, where appropriate, for each resource. <br><br> People that want to create pattern modules. | | ||
| | **Pattern Module** | Deploys multiple resources, usually using Resource Modules. They can be any size but should help accelerate a common task/deployment/architecture. <br><br> Good candidates for pattern modules are those architectures that exist in [Azure Architecture Center](https://learn.microsoft.com/en-us/azure/architecture/), or other official documentation. <br><br> *Note:* It is feasible that pattern modules can contain other pattern modules, however, pattern modules MUST NOT contain references to non-AVM modules. | People that want to easily deploy patterns (architectures) using WAF best practices. | | ||
| |**Resource Module** | Deploys a primary resource with WAF high priority/impact best practice configurations set by default, e.g., RBAC, Locks, Private Endpoints etc. (if supported). See [What does AVM mean by "WAF Aligned"?](/Azure-Verified-Modules/faq/#what-does-avm-mean-by-waf-aligned) <br><br> They MAY include related resources, e.g. VM contains disk & NIC. Focus should be on customer experience. A customer would expect that a VM module would include all required resources to provision a VM. <br><br> Furthermore, Resource Modules MUST NOT deploy external dependencies for the primary resource. E.g. a VM needs a vNet and Subnet to be deployed into, but the vNet will not be created by the VM Resource Module.<br><br> Finally, a resource can be anything such as Microsoft Defender for Cloud Pricing Plans, these are still resources in ARM and can therefore be created as a Resource Module. | People who want to craft bespoke architectures that default to WAF best practices, where appropriate, for each resource. <br><br> People who want to create pattern modules. | |
There was a problem hiding this comment.
I know this definition has been around for a while, but I'm not sure whether we should call out RBAC & Private Endpoints as examples for 'set by default' as nothing about the 2 is actually set by default. Also, we opted that setting 'Locks' is not contributing to WAF-alignment.
Instead, I'd recommend to call out items like 'Entra ID authentication', 'Firewalls' or 'Availability Zones'.
There was a problem hiding this comment.
The rest (including the utility definition) reads well.
| | **Pattern Module** | Deploys multiple resources, usually using Resource Modules. They can be any size but should help accelerate a common task/deployment/architecture. <br><br> Good candidates for pattern modules are those architectures that exist in [Azure Architecture Center](https://learn.microsoft.com/en-us/azure/architecture/), or other official documentation. <br><br> *Note:* It is feasible that pattern modules can contain other pattern modules, however, pattern modules MUST NOT contain references to non-AVM modules. | People that want to easily deploy patterns (architectures) using WAF best practices. | | ||
| |**Resource Module** | Deploys a primary resource with WAF high priority/impact best practice configurations set by default, e.g., RBAC, Locks, Private Endpoints etc. (if supported). See [What does AVM mean by "WAF Aligned"?](/Azure-Verified-Modules/faq/#what-does-avm-mean-by-waf-aligned) <br><br> They MAY include related resources, e.g. VM contains disk & NIC. Focus should be on customer experience. A customer would expect that a VM module would include all required resources to provision a VM. <br><br> Furthermore, Resource Modules MUST NOT deploy external dependencies for the primary resource. E.g. a VM needs a vNet and Subnet to be deployed into, but the vNet will not be created by the VM Resource Module.<br><br> Finally, a resource can be anything such as Microsoft Defender for Cloud Pricing Plans, these are still resources in ARM and can therefore be created as a Resource Module. | People who want to craft bespoke architectures that default to WAF best practices, where appropriate, for each resource. <br><br> People who want to create pattern modules. | | ||
| | **Pattern Module** | Deploys multiple resources, usually using Resource Modules. They can be any size but should help accelerate a common task/deployment/architecture. <br><br> Good candidates for pattern modules are those architectures that exist in [Azure Architecture Center](https://learn.microsoft.com/en-us/azure/architecture/), or other official documentation. <br><br> *Note:* Pattern modules can contain other pattern modules, however, pattern modules MUST NOT contain references to non-AVM modules. | People who want to easily deploy patterns (architectures) using WAF best practices. | | ||
| | **Utility Module**<br>(draft,<br>see below) | Implements a function or routine that can be flexibly reused in resource or pattern modules - e.g., a function that retrieves the endpoint of an API or portal of a given environment. <br><br>It MUST NOT deploy any Azure resources other than deployment scripts. | People who want to leverage commonly used functions/routines/helpers in their module, instead of re-implementing them locally. | |
There was a problem hiding this comment.
One thing we 'could' call out regarding the deployment scripts though (unless it overcomplicating the definition) is that while the module should ONLY implement the deployment script - it should enable the user of the module to deploy it in a secure way by, for example, exposing the entire interface of the deployment script as per the AVM module (e.g., enable setting a subnet for private networking).
Just a thought as I'd expert a contributor to wonder how to actually implement the deployment script in a good, standadized way.
There was a problem hiding this comment.
As discussed in the call today, details at this level will be further elaborated on at the related funtional/non-functional requirements pages.
ChrisSidebotham
approved these changes
May 30, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Overview/Summary
Introducing Utility Modules.
This PR fixes/adds/changes/removes
Breaking Changes
n/a
As part of this Pull Request I have
mainbranch