-
Notifications
You must be signed in to change notification settings - Fork 63
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Introducing Utility Modules #947
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
lgtm
|
||
{{< 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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/utl
folder, 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The rest (including the utility definition) reads well.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Updated.
| **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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As discussed in the call today, details at this level will be further elaborated on at the related funtional/non-functional requirements pages.
Overview/Summary
Introducing Utility Modules.
This PR fixes/adds/changes/removes
Breaking Changes
n/a
As part of this Pull Request I have
main
branch