Add support for AVM references (#2794)

This commit is contained in:
Bernie White 2024-04-02 04:54:02 +10:00 коммит произвёл GitHub
Родитель 9bb5589bd1
Коммит 2ef64f2a0a
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: B5690EEEBB952194
5 изменённых файлов: 53 добавлений и 6 удалений

Просмотреть файл

@ -71,7 +71,8 @@ Rule documentation requires the following annotations for use with PSRule for Az
Available severities are:
- `Critical` - A 'must have' if the solution is to be considered 'fit for purpose', secure, well governed and managed inline with the Microsoft Azure [Well-Architected Framework](https://learn.microsoft.com/azure/well-architected/).
- `Important` - A 'to be considered' within the context of the solution and domain. In some cases, can introduce cost or complexity that should be considered as a trade off and explicity documented as a [Key Design Decision](https://learn.microsoft.com/azure/cloud-adoption-framework/decision-guides/).
- `Important` - A 'to be considered' within the context of the solution and domain.
In some cases, can introduce cost or complexity that should be considered as a trade off and explicitly documented as a [Key Design Decision](https://learn.microsoft.com/azure/cloud-adoption-framework/decision-guides/).
- `Awareness` - A 'good to have' feature, normally reserved for solutions with the highest [non-functional requirements](https://learn.microsoft.com/azure/well-architected/reliability/checklist).
- `pillar` - A Azure Well-Architected Framework pillar.
@ -83,16 +84,21 @@ Rule documentation requires the following annotations for use with PSRule for Az
When authoring and improving rule documentation, please follow these guidelines:
- Provide documentation links to the Azure service and Well-Architected Framework pillar.
- **Reference the WAF** — by the pillar recommendation.
For example if the rule relates to redundancy in the Reliability pillar you could reference [RE:05 Redundancy](https://learn.microsoft.com/azure/well-architected/reliability/redundancy).
- **Add relevant links** — to the Azure service documentation.
Examples of good documentation links include:
- Best practices for the Azure service.
- Instructions on how to configure the Azure service.
- [Azure deployment reference](https://learn.microsoft.com/azure/templates/).
- For links to _https://learn.microsoft.com/_ remove culture from path to make it more generic.
- **Remove culture** — from links to _https://learn.microsoft.com/_ to make it more generic.
This will allow the link to redirect to a language based on the user's settings.
For example _https://learn.microsoft.com/azure/aks/concepts-scale_ instead of _https://learn.microsoft.com/en-us/azure/aks/concepts-scale_.
- Add examples of a Azure resource that would pass the rule.
At a minimum where applicable provide an example of a Azure template resource.
Also consider including example Bicep code.
- **Add examples** — of a Azure resource that would pass the rule.
For rules that apply to pre-flight checks provide an example in Azure Bicep _and_ Azure template format.
- Additionally if a pre-built Azure Verified Module is available, reference after the Bicep example using a short-code.
The short-code format is `<!-- external:avm <module_path> <params> -->`.
For more information see the [example](https://github.com/Azure/PSRule.Rules.Azure/blob/9bb5589bd1ddb01197866d5199f3954cf6f9206b/docs/en/rules/Azure.ContainerApp.MinReplicas.md?plain=1#L113).
[4]: https://microsoft.github.io/PSRule/latest/authoring/writing-rule-help/#writing-markdown-documentation

Просмотреть файл

@ -76,6 +76,8 @@ resource eventGrid 'Microsoft.EventGrid/topics@2022-06-15' = {
}
```
<!-- external:avm avm/res/event-grid/topic disableLocalAuth -->
### Configure with Azure Policy
To address this issue at runtime use the following policies:

Просмотреть файл

@ -75,6 +75,8 @@ resource eventGrid 'Microsoft.EventGrid/topics@2022-06-15' = {
}
```
<!-- external:avm avm/res/event-grid/topic managedIdentities -->
## LINKS
- [SE:05 Identity and access management](https://learn.microsoft.com/azure/well-architected/security/identity-access)

Просмотреть файл

@ -73,6 +73,8 @@ resource eventGrid 'Microsoft.EventGrid/topics@2022-06-15' = {
}
```
<!-- external:avm avm/res/event-grid/topic publicNetworkAccess -->
## LINKS
- [SE:06 Network controls](https://learn.microsoft.com/azure/well-architected/security/networking)

Просмотреть файл

@ -49,6 +49,24 @@ def module(markdown: str, page: Page, config: MkDocsConfig, files: Files) -> str
replace, markdown, flags = re.I | re.M
)
def external(markdown: str, page: Page, config: MkDocsConfig, files: Files) -> str:
'''Replace external shortcodes in markdown.'''
# Callback for regular expression replacement.
def replace(match: re.Match) -> str:
type, args = match.groups()
args = args.strip()
if type == "avm":
return _external_reference_avm(args)
raise RuntimeError(f"Unknown shortcode external:{type}")
# Replace external shortcodes.
return re.sub(
r"<!-- external:(\w+)(.*?) -->",
replace, markdown, flags = re.I | re.M
)
def _relative_uri(path: str, page: Page, files: Files) -> str:
'''Get relative URI for a file including anchor.'''
@ -120,3 +138,20 @@ def _badge_for_configuration(text: str, page: Page, files: Files) -> str:
icon = f"[:{icon}:]({href} 'Applies to configuration setting')",
text = f"[{text}]({href})"
)
def _reference_block(style: str, title: str, text: str = "") -> str:
'''Add an external reference block.'''
lines = text.replace('\r\n', '\n').replace('\r', '\n').replace('\n', '\n ').strip()
return f"!!! {style} \"{title}\"\n {lines}"
def _external_reference_avm(text: str) -> str:
'''Create a reference to AVM.'''
avm_path = text.split(' ')[0]
return _reference_block(
style = "Example",
title = f"Configure with [Azure Verified Modules](https://github.com/Azure/bicep-registry-modules/tree/main/{avm_path})",
text = f"A pre-built module is avilable on the Azure Bicep public registry.\nTo reference the module, please use the following syntax: `br/public:{avm_path}:<version>`"
)