From 41300decf3f3eb82a95e29525a504335ef3c12a8 Mon Sep 17 00:00:00 2001 From: Bernie White Date: Sat, 27 Jan 2024 18:49:38 +1000 Subject: [PATCH] Documentation updates (#2662) --- docs/CHANGELOG-v1.md | 8 ++- docs/en/rules/Azure.Template.TemplateFile.md | 37 +++++++++-- .../en/rules/Azure.Template.ValidSecretRef.md | 46 ++++++------- .../rules/Azure.TrafficManager.Endpoints.md | 8 ++- .../en/rules/Azure.TrafficManager.Protocol.md | 66 ++++++++++++++++++- docs/examples-trafficmanager.bicep | 28 ++++++++ docs/examples-trafficmanager.json | 49 ++++++++++++++ docs/examples-vng.bicep | 2 +- 8 files changed, 207 insertions(+), 37 deletions(-) create mode 100644 docs/examples-trafficmanager.bicep create mode 100644 docs/examples-trafficmanager.json diff --git a/docs/CHANGELOG-v1.md b/docs/CHANGELOG-v1.md index e9622e0d1e7..3b547cb4385 100644 --- a/docs/CHANGELOG-v1.md +++ b/docs/CHANGELOG-v1.md @@ -32,9 +32,11 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers ## Unreleased -- Updated rules: - - Template file - - Update `AZR-000212` to not fail with `languageVersion` 2.0 Templates +What's changed since pre-release v1.33.0-B0088: + +- Bug fixes: + - Fixed `Azure.Template.TemplateFile` to support with `languageVersion` 2.0 template properties by @MrRoundRobin. + [#2660](https://github.com/Azure/PSRule.Rules.Azure/issues/2660) ## v1.33.0-B0088 (pre-release) diff --git a/docs/en/rules/Azure.Template.TemplateFile.md b/docs/en/rules/Azure.Template.TemplateFile.md index c7523838b8d..a1f17d8930d 100644 --- a/docs/en/rules/Azure.Template.TemplateFile.md +++ b/docs/en/rules/Azure.Template.TemplateFile.md @@ -1,7 +1,8 @@ --- +reviewed: 2024-01-27 severity: Important pillar: Operational Excellence -category: Repeatable infrastructure +category: OE:05 Infrastructure as code resource: All resources online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.Template.TemplateFile/ --- @@ -23,8 +24,36 @@ If any of these sections are missing, ARM will not accept the template. Consider reviewing the requirements for this file. Also consider using Visual Studio Code to assist with authoring these files. +## EXAMPLES + +### Configure with Azure template + +To define Azure template files that pass this rule: + +- Always specify the required properties `$schema`, `contentVersion` and `resources` properties. +- Optional specify `languageVersion`, `definitions`, `metadata`, `parameters`, `functions`, `variables`, and `outputs` properties. +- Avoid specifying any other properties. + +For example: + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "parameters": { }, + "variables": { }, + "resources": [ ] +} +``` + +## NOTES + +This rule is not applicable to Azure Bicep files as they have a different structure. +If you are running analysis over pre-built Bicep files and they generate a rule failure, +please raise an [issue](https://github.com/Azure/PSRule.Rules.Azure/issues/new/choose). + ## LINKS -- [Automate deployments with ARM Templates](https://learn.microsoft.com/azure/architecture/framework/devops/automation-infrastructure#automate-deployments-with-arm-templates) -- [Template file structure](https://docs.microsoft.com/azure/azure-resource-manager/templates/template-syntax) -- [Define resources in Azure Resource Manager templates](https://docs.microsoft.com/azure/templates/) +- [OE:05 Infrastructure as code](https://learn.microsoft.com/azure/well-architected/operational-excellence/infrastructure-as-code-design) +- [Template file structure](https://learn.microsoft.com/azure/azure-resource-manager/templates/syntax) +- [Define resources in Azure Resource Manager templates](https://learn.microsoft.com/azure/templates/) diff --git a/docs/en/rules/Azure.Template.ValidSecretRef.md b/docs/en/rules/Azure.Template.ValidSecretRef.md index c7828198920..58cca459584 100644 --- a/docs/en/rules/Azure.Template.ValidSecretRef.md +++ b/docs/en/rules/Azure.Template.ValidSecretRef.md @@ -1,7 +1,7 @@ --- severity: Awareness pillar: Operational Excellence -category: Repeatable infrastructure +category: OE:05 Infrastructure as code resource: All resources online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.Template.ValidSecretRef/ --- @@ -36,32 +36,32 @@ For example: ```json { - "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", - "contentVersion": "1.0.0.0", - "parameters": { - "gatewayName": { - "value": "gateway-A" + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", + "contentVersion": "1.0.0.0", + "parameters": { + "gatewayName": { + "value": "gateway-A" + }, + "sku": { + "value": "VpnGw1" + }, + "subnetId": { + "value": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/test-rg/providers/Microsoft.Network/virtualNetworks/vnet-A/subnets/GatewaySubnet" + }, + "sharedKey": { + "reference": { + "keyVault": { + "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/test-rg/providers/Microsoft.KeyVault/vaults/kv-001" }, - "sku": { - "value": "VpnGw1" - }, - "subnetId": { - "value": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/test-rg/providers/Microsoft.Network/virtualNetworks/vnet-A/subnets/GatewaySubnet" - }, - "sharedKey": { - "reference": { - "keyVault": { - "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/test-rg/providers/Microsoft.KeyVault/vaults/kv-001" - }, - "secretName": "valid-secret" - } - } + "secretName": "valid-secret" + } } + } } ``` ## LINKS -- [Automate deployments with ARM Templates](https://learn.microsoft.com/azure/architecture/framework/devops/automation-infrastructure#automate-deployments-with-arm-templates) -- [Reference secrets with static ID](https://docs.microsoft.com/azure/azure-resource-manager/templates/key-vault-parameter#reference-secrets-with-static-id) -- [Create Resource Manager parameter file](https://docs.microsoft.com/azure/azure-resource-manager/templates/parameter-files) +- [OE:05 Infrastructure as code](https://learn.microsoft.com/azure/well-architected/operational-excellence/infrastructure-as-code-design) +- [Reference secrets with static ID](https://learn.microsoft.com/azure/azure-resource-manager/templates/key-vault-parameter#reference-secrets-with-static-id) +- [Create Resource Manager parameter file](https://learn.microsoft.com/azure/azure-resource-manager/templates/parameter-files) diff --git a/docs/en/rules/Azure.TrafficManager.Endpoints.md b/docs/en/rules/Azure.TrafficManager.Endpoints.md index 7b891bf3e13..cc1cd774849 100644 --- a/docs/en/rules/Azure.TrafficManager.Endpoints.md +++ b/docs/en/rules/Azure.TrafficManager.Endpoints.md @@ -1,7 +1,7 @@ --- severity: Important pillar: Reliability -category: Load balancing and failover +category: RE:05 Redundancy resource: Traffic Manager online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.TrafficManager.Endpoints/ --- @@ -26,5 +26,7 @@ Also consider, using endpoints deployed across different regions to provide high ## LINKS -- [What is Traffic Manager?](https://docs.microsoft.com/azure/traffic-manager/traffic-manager-overview) -- [How Traffic Manager Works](https://docs.microsoft.com/azure/traffic-manager/traffic-manager-how-it-works) +- [RE:05 Redundancy](https://learn.microsoft.com/azure/well-architected/reliability/redundancy) +- [What is Traffic Manager?](https://learn.microsoft.com/azure/traffic-manager/traffic-manager-overview) +- [How Traffic Manager Works](https://learn.microsoft.com/azure/traffic-manager/traffic-manager-how-it-works) +- [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.network/trafficmanagerprofiles) diff --git a/docs/en/rules/Azure.TrafficManager.Protocol.md b/docs/en/rules/Azure.TrafficManager.Protocol.md index 38528447cd2..7de9b80051b 100644 --- a/docs/en/rules/Azure.TrafficManager.Protocol.md +++ b/docs/en/rules/Azure.TrafficManager.Protocol.md @@ -1,7 +1,8 @@ --- +reviewed: 2024-01-27 severity: Important pillar: Security -category: Data protection +category: SE:07 Encryption resource: Traffic Manager online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.TrafficManager.Protocol/ --- @@ -30,7 +31,66 @@ but do not validate if the certificate is valid. Consider using HTTPS to monitor web-based endpoint health. HTTPS-based monitoring improves security and increases accuracy of health probes. +## EXAMPLES + +### Configure with Azure template + +To deploy Traffic Manager profiles that pass this rule: + +- Set the `properties.monitorConfig.protocol` property to `HTTPS` for HTTP-based endpoints. + +For example: + +```json +{ + "type": "Microsoft.Network/trafficmanagerprofiles", + "apiVersion": "2022-04-01", + "name": "[parameters('name')]", + "location": "global", + "properties": { + "endpoints": "[parameters('endpoints')]", + "trafficRoutingMethod": "Performance", + "monitorConfig": { + "protocol": "HTTPS", + "port": 443, + "intervalInSeconds": 30, + "timeoutInSeconds": 5, + "toleratedNumberOfFailures": 3, + "path": "/healthz" + } + } +} +``` + +### Configure with Bicep + +To deploy Traffic Manager profiles that pass this rule: + +- Set the `properties.monitorConfig.protocol` property to `HTTPS` for HTTP-based endpoints. + +For example: + +```bicep +resource profile 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: name + location: 'global' + properties: { + endpoints: endpoints + trafficRoutingMethod: 'Performance' + monitorConfig: { + protocol: 'HTTPS' + port: 443 + intervalInSeconds: 30 + timeoutInSeconds: 5 + toleratedNumberOfFailures: 3 + path: '/healthz' + } + } +} +``` + ## LINKS -- [Data encryption in Azure](https://learn.microsoft.com/azure/architecture/framework/security/design-storage-encryption#data-in-transit) -- [Traffic Manager endpoint monitoring](https://docs.microsoft.com/azure/traffic-manager/traffic-manager-monitoring) +- [SE:07 Encryption](https://learn.microsoft.com/azure/well-architected/security/encryption#data-in-transit) +- [Traffic Manager endpoint monitoring](https://learn.microsoft.com/azure/traffic-manager/traffic-manager-monitoring) +- [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.network/trafficmanagerprofiles) diff --git a/docs/examples-trafficmanager.bicep b/docs/examples-trafficmanager.bicep new file mode 100644 index 00000000000..02a71ee83d7 --- /dev/null +++ b/docs/examples-trafficmanager.bicep @@ -0,0 +1,28 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT License. + +// Bicep documentation examples + +@description('The name of the resource.') +param name string + +@description('Endpoints to resolve for.') +param endpoints object[] + +// An example Traffic Manager Profile using the Performance routing method. +resource profile 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: name + location: 'global' + properties: { + endpoints: endpoints + trafficRoutingMethod: 'Performance' + monitorConfig: { + protocol: 'HTTPS' + port: 443 + intervalInSeconds: 30 + timeoutInSeconds: 5 + toleratedNumberOfFailures: 3 + path: '/healthz' + } + } +} diff --git a/docs/examples-trafficmanager.json b/docs/examples-trafficmanager.json new file mode 100644 index 00000000000..0902cf1718e --- /dev/null +++ b/docs/examples-trafficmanager.json @@ -0,0 +1,49 @@ +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "languageVersion": "2.0", + "contentVersion": "1.0.0.0", + "metadata": { + "_generator": { + "name": "bicep", + "version": "0.24.24.22086", + "templateHash": "13648233826792444598" + } + }, + "parameters": { + "name": { + "type": "string", + "metadata": { + "description": "The name of the resource." + } + }, + "endpoints": { + "type": "array", + "items": { + "type": "object" + }, + "metadata": { + "description": "Endpoints to resolve for." + } + } + }, + "resources": { + "profile": { + "type": "Microsoft.Network/trafficmanagerprofiles", + "apiVersion": "2022-04-01", + "name": "[parameters('name')]", + "location": "global", + "properties": { + "endpoints": "[parameters('endpoints')]", + "trafficRoutingMethod": "Performance", + "monitorConfig": { + "protocol": "HTTPS", + "port": 443, + "intervalInSeconds": 30, + "timeoutInSeconds": 5, + "toleratedNumberOfFailures": 3, + "path": "/healthz" + } + } + } + } +} \ No newline at end of file diff --git a/docs/examples-vng.bicep b/docs/examples-vng.bicep index 47937600666..2d476c561b6 100644 --- a/docs/examples-vng.bicep +++ b/docs/examples-vng.bicep @@ -15,7 +15,7 @@ param subnetId string @description('The resource ID of the public IP address to use.') param pipId string -// An example Virtual Network Gateway with availablity zone aware SKU. +// An example Virtual Network Gateway with availability zone aware SKU. resource vng 'Microsoft.Network/virtualNetworkGateways@2023-06-01' = { name: name location: location