From 2ef64f2a0a76f6a5ed6e4e18fa62bf821234fb0b Mon Sep 17 00:00:00 2001 From: Bernie White Date: Tue, 2 Apr 2024 04:54:02 +1000 Subject: [PATCH] Add support for AVM references (#2794) --- CONTRIBUTING.md | 18 ++++++---- .../rules/Azure.EventGrid.DisableLocalAuth.md | 2 ++ .../rules/Azure.EventGrid.ManagedIdentity.md | 2 ++ .../Azure.EventGrid.TopicPublicAccess.md | 2 ++ docs/hooks/shortcodes.py | 35 +++++++++++++++++++ 5 files changed, 53 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 394c0aaa01..285df8badf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 ``. + 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 diff --git a/docs/en/rules/Azure.EventGrid.DisableLocalAuth.md b/docs/en/rules/Azure.EventGrid.DisableLocalAuth.md index 7aed4c856b..1994e2c133 100644 --- a/docs/en/rules/Azure.EventGrid.DisableLocalAuth.md +++ b/docs/en/rules/Azure.EventGrid.DisableLocalAuth.md @@ -76,6 +76,8 @@ resource eventGrid 'Microsoft.EventGrid/topics@2022-06-15' = { } ``` + + ### Configure with Azure Policy To address this issue at runtime use the following policies: diff --git a/docs/en/rules/Azure.EventGrid.ManagedIdentity.md b/docs/en/rules/Azure.EventGrid.ManagedIdentity.md index 8f350420a4..fd0fc67fd8 100644 --- a/docs/en/rules/Azure.EventGrid.ManagedIdentity.md +++ b/docs/en/rules/Azure.EventGrid.ManagedIdentity.md @@ -75,6 +75,8 @@ resource eventGrid 'Microsoft.EventGrid/topics@2022-06-15' = { } ``` + + ## LINKS - [SE:05 Identity and access management](https://learn.microsoft.com/azure/well-architected/security/identity-access) diff --git a/docs/en/rules/Azure.EventGrid.TopicPublicAccess.md b/docs/en/rules/Azure.EventGrid.TopicPublicAccess.md index 3a8da8f0d4..d5252b986b 100644 --- a/docs/en/rules/Azure.EventGrid.TopicPublicAccess.md +++ b/docs/en/rules/Azure.EventGrid.TopicPublicAccess.md @@ -73,6 +73,8 @@ resource eventGrid 'Microsoft.EventGrid/topics@2022-06-15' = { } ``` + + ## LINKS - [SE:06 Network controls](https://learn.microsoft.com/azure/well-architected/security/networking) diff --git a/docs/hooks/shortcodes.py b/docs/hooks/shortcodes.py index c012d6526f..b427ca3ac5 100644 --- a/docs/hooks/shortcodes.py +++ b/docs/hooks/shortcodes.py @@ -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"", + 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}:`" + )