Skip to content

Commit 41300de

Browse files
BernieWhiteBernieWhite
authored
Documentation updates (Azure#2662)
1 parent b6c90d1 commit 41300de

8 files changed

+207
-37
lines changed

‎docs/CHANGELOG-v1.md

+5-3
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,11 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
3232

3333
## Unreleased
3434

35-
- Updated rules:
36-
- Template file
37-
- Update `AZR-000212` to not fail with `languageVersion` 2.0 Templates
35+
What's changed since pre-release v1.33.0-B0088:
36+
37+
- Bug fixes:
38+
- Fixed `Azure.Template.TemplateFile` to support with `languageVersion` 2.0 template properties by @MrRoundRobin.
39+
[#2660](https://github.com/Azure/PSRule.Rules.Azure/issues/2660)
3840

3941
## v1.33.0-B0088 (pre-release)
4042

‎docs/en/rules/Azure.Template.TemplateFile.md

+33-4
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
---
2+
reviewed: 2024-01-27
23
severity: Important
34
pillar: Operational Excellence
4-
category: Repeatable infrastructure
5+
category: OE:05 Infrastructure as code
56
resource: All resources
67
online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.Template.TemplateFile/
78
---
@@ -23,8 +24,36 @@ If any of these sections are missing, ARM will not accept the template.
2324
Consider reviewing the requirements for this file.
2425
Also consider using Visual Studio Code to assist with authoring these files.
2526

27+
## EXAMPLES
28+
29+
### Configure with Azure template
30+
31+
To define Azure template files that pass this rule:
32+
33+
- Always specify the required properties `$schema`, `contentVersion` and `resources` properties.
34+
- Optional specify `languageVersion`, `definitions`, `metadata`, `parameters`, `functions`, `variables`, and `outputs` properties.
35+
- Avoid specifying any other properties.
36+
37+
For example:
38+
39+
```json
40+
{
41+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
42+
"contentVersion": "1.0.0.0",
43+
"parameters": { },
44+
"variables": { },
45+
"resources": [ ]
46+
}
47+
```
48+
49+
## NOTES
50+
51+
This rule is not applicable to Azure Bicep files as they have a different structure.
52+
If you are running analysis over pre-built Bicep files and they generate a rule failure,
53+
please raise an [issue](https://github.com/Azure/PSRule.Rules.Azure/issues/new/choose).
54+
2655
## LINKS
2756

28-
- [Automate deployments with ARM Templates](https://learn.microsoft.com/azure/architecture/framework/devops/automation-infrastructure#automate-deployments-with-arm-templates)
29-
- [Template file structure](https://docs.microsoft.com/azure/azure-resource-manager/templates/template-syntax)
30-
- [Define resources in Azure Resource Manager templates](https://docs.microsoft.com/azure/templates/)
57+
- [OE:05 Infrastructure as code](https://learn.microsoft.com/azure/well-architected/operational-excellence/infrastructure-as-code-design)
58+
- [Template file structure](https://learn.microsoft.com/azure/azure-resource-manager/templates/syntax)
59+
- [Define resources in Azure Resource Manager templates](https://learn.microsoft.com/azure/templates/)

‎docs/en/rules/Azure.Template.ValidSecretRef.md

+23-23
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
severity: Awareness
33
pillar: Operational Excellence
4-
category: Repeatable infrastructure
4+
category: OE:05 Infrastructure as code
55
resource: All resources
66
online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.Template.ValidSecretRef/
77
---
@@ -36,32 +36,32 @@ For example:
3636

3737
```json
3838
{
39-
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
40-
"contentVersion": "1.0.0.0",
41-
"parameters": {
42-
"gatewayName": {
43-
"value": "gateway-A"
39+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
40+
"contentVersion": "1.0.0.0",
41+
"parameters": {
42+
"gatewayName": {
43+
"value": "gateway-A"
44+
},
45+
"sku": {
46+
"value": "VpnGw1"
47+
},
48+
"subnetId": {
49+
"value": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/test-rg/providers/Microsoft.Network/virtualNetworks/vnet-A/subnets/GatewaySubnet"
50+
},
51+
"sharedKey": {
52+
"reference": {
53+
"keyVault": {
54+
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/test-rg/providers/Microsoft.KeyVault/vaults/kv-001"
4455
},
45-
"sku": {
46-
"value": "VpnGw1"
47-
},
48-
"subnetId": {
49-
"value": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/test-rg/providers/Microsoft.Network/virtualNetworks/vnet-A/subnets/GatewaySubnet"
50-
},
51-
"sharedKey": {
52-
"reference": {
53-
"keyVault": {
54-
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/test-rg/providers/Microsoft.KeyVault/vaults/kv-001"
55-
},
56-
"secretName": "valid-secret"
57-
}
58-
}
56+
"secretName": "valid-secret"
57+
}
5958
}
59+
}
6060
}
6161
```
6262

6363
## LINKS
6464

65-
- [Automate deployments with ARM Templates](https://learn.microsoft.com/azure/architecture/framework/devops/automation-infrastructure#automate-deployments-with-arm-templates)
66-
- [Reference secrets with static ID](https://docs.microsoft.com/azure/azure-resource-manager/templates/key-vault-parameter#reference-secrets-with-static-id)
67-
- [Create Resource Manager parameter file](https://docs.microsoft.com/azure/azure-resource-manager/templates/parameter-files)
65+
- [OE:05 Infrastructure as code](https://learn.microsoft.com/azure/well-architected/operational-excellence/infrastructure-as-code-design)
66+
- [Reference secrets with static ID](https://learn.microsoft.com/azure/azure-resource-manager/templates/key-vault-parameter#reference-secrets-with-static-id)
67+
- [Create Resource Manager parameter file](https://learn.microsoft.com/azure/azure-resource-manager/templates/parameter-files)

‎docs/en/rules/Azure.TrafficManager.Endpoints.md

+5-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
severity: Important
33
pillar: Reliability
4-
category: Load balancing and failover
4+
category: RE:05 Redundancy
55
resource: Traffic Manager
66
online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.TrafficManager.Endpoints/
77
---
@@ -26,5 +26,7 @@ Also consider, using endpoints deployed across different regions to provide high
2626

2727
## LINKS
2828

29-
- [What is Traffic Manager?](https://docs.microsoft.com/azure/traffic-manager/traffic-manager-overview)
30-
- [How Traffic Manager Works](https://docs.microsoft.com/azure/traffic-manager/traffic-manager-how-it-works)
29+
- [RE:05 Redundancy](https://learn.microsoft.com/azure/well-architected/reliability/redundancy)
30+
- [What is Traffic Manager?](https://learn.microsoft.com/azure/traffic-manager/traffic-manager-overview)
31+
- [How Traffic Manager Works](https://learn.microsoft.com/azure/traffic-manager/traffic-manager-how-it-works)
32+
- [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.network/trafficmanagerprofiles)

‎docs/en/rules/Azure.TrafficManager.Protocol.md

+63-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
---
2+
reviewed: 2024-01-27
23
severity: Important
34
pillar: Security
4-
category: Data protection
5+
category: SE:07 Encryption
56
resource: Traffic Manager
67
online version: https://azure.github.io/PSRule.Rules.Azure/en/rules/Azure.TrafficManager.Protocol/
78
---
@@ -30,7 +31,66 @@ but do not validate if the certificate is valid.
3031
Consider using HTTPS to monitor web-based endpoint health.
3132
HTTPS-based monitoring improves security and increases accuracy of health probes.
3233

34+
## EXAMPLES
35+
36+
### Configure with Azure template
37+
38+
To deploy Traffic Manager profiles that pass this rule:
39+
40+
- Set the `properties.monitorConfig.protocol` property to `HTTPS` for HTTP-based endpoints.
41+
42+
For example:
43+
44+
```json
45+
{
46+
"type": "Microsoft.Network/trafficmanagerprofiles",
47+
"apiVersion": "2022-04-01",
48+
"name": "[parameters('name')]",
49+
"location": "global",
50+
"properties": {
51+
"endpoints": "[parameters('endpoints')]",
52+
"trafficRoutingMethod": "Performance",
53+
"monitorConfig": {
54+
"protocol": "HTTPS",
55+
"port": 443,
56+
"intervalInSeconds": 30,
57+
"timeoutInSeconds": 5,
58+
"toleratedNumberOfFailures": 3,
59+
"path": "/healthz"
60+
}
61+
}
62+
}
63+
```
64+
65+
### Configure with Bicep
66+
67+
To deploy Traffic Manager profiles that pass this rule:
68+
69+
- Set the `properties.monitorConfig.protocol` property to `HTTPS` for HTTP-based endpoints.
70+
71+
For example:
72+
73+
```bicep
74+
resource profile 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = {
75+
name: name
76+
location: 'global'
77+
properties: {
78+
endpoints: endpoints
79+
trafficRoutingMethod: 'Performance'
80+
monitorConfig: {
81+
protocol: 'HTTPS'
82+
port: 443
83+
intervalInSeconds: 30
84+
timeoutInSeconds: 5
85+
toleratedNumberOfFailures: 3
86+
path: '/healthz'
87+
}
88+
}
89+
}
90+
```
91+
3392
## LINKS
3493

35-
- [Data encryption in Azure](https://learn.microsoft.com/azure/architecture/framework/security/design-storage-encryption#data-in-transit)
36-
- [Traffic Manager endpoint monitoring](https://docs.microsoft.com/azure/traffic-manager/traffic-manager-monitoring)
94+
- [SE:07 Encryption](https://learn.microsoft.com/azure/well-architected/security/encryption#data-in-transit)
95+
- [Traffic Manager endpoint monitoring](https://learn.microsoft.com/azure/traffic-manager/traffic-manager-monitoring)
96+
- [Azure deployment reference](https://learn.microsoft.com/azure/templates/microsoft.network/trafficmanagerprofiles)

‎docs/examples-trafficmanager.bicep

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
// Copyright (c) Microsoft Corporation.
2+
// Licensed under the MIT License.
3+
4+
// Bicep documentation examples
5+
6+
@description('The name of the resource.')
7+
param name string
8+
9+
@description('Endpoints to resolve for.')
10+
param endpoints object[]
11+
12+
// An example Traffic Manager Profile using the Performance routing method.
13+
resource profile 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = {
14+
name: name
15+
location: 'global'
16+
properties: {
17+
endpoints: endpoints
18+
trafficRoutingMethod: 'Performance'
19+
monitorConfig: {
20+
protocol: 'HTTPS'
21+
port: 443
22+
intervalInSeconds: 30
23+
timeoutInSeconds: 5
24+
toleratedNumberOfFailures: 3
25+
path: '/healthz'
26+
}
27+
}
28+
}

‎docs/examples-trafficmanager.json

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
{
2+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
3+
"languageVersion": "2.0",
4+
"contentVersion": "1.0.0.0",
5+
"metadata": {
6+
"_generator": {
7+
"name": "bicep",
8+
"version": "0.24.24.22086",
9+
"templateHash": "13648233826792444598"
10+
}
11+
},
12+
"parameters": {
13+
"name": {
14+
"type": "string",
15+
"metadata": {
16+
"description": "The name of the resource."
17+
}
18+
},
19+
"endpoints": {
20+
"type": "array",
21+
"items": {
22+
"type": "object"
23+
},
24+
"metadata": {
25+
"description": "Endpoints to resolve for."
26+
}
27+
}
28+
},
29+
"resources": {
30+
"profile": {
31+
"type": "Microsoft.Network/trafficmanagerprofiles",
32+
"apiVersion": "2022-04-01",
33+
"name": "[parameters('name')]",
34+
"location": "global",
35+
"properties": {
36+
"endpoints": "[parameters('endpoints')]",
37+
"trafficRoutingMethod": "Performance",
38+
"monitorConfig": {
39+
"protocol": "HTTPS",
40+
"port": 443,
41+
"intervalInSeconds": 30,
42+
"timeoutInSeconds": 5,
43+
"toleratedNumberOfFailures": 3,
44+
"path": "/healthz"
45+
}
46+
}
47+
}
48+
}
49+
}

‎docs/examples-vng.bicep

+1-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ param subnetId string
1515
@description('The resource ID of the public IP address to use.')
1616
param pipId string
1717

18-
// An example Virtual Network Gateway with availablity zone aware SKU.
18+
// An example Virtual Network Gateway with availability zone aware SKU.
1919
resource vng 'Microsoft.Network/virtualNetworkGateways@2023-06-01' = {
2020
name: name
2121
location: location

0 commit comments

Comments
 (0)