Skip to content

Commit

Permalink
Documentation updates (#2662)
Browse files Browse the repository at this point in the history
  • Loading branch information
BernieWhite authored Jan 27, 2024
1 parent b6c90d1 commit 41300de
Show file tree
Hide file tree
Showing 8 changed files with 207 additions and 37 deletions.
8 changes: 5 additions & 3 deletions docs/CHANGELOG-v1.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
37 changes: 33 additions & 4 deletions docs/en/rules/Azure.Template.TemplateFile.md
Original file line number Diff line number Diff line change
@@ -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/
---
Expand All @@ -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/)
46 changes: 23 additions & 23 deletions docs/en/rules/Azure.Template.ValidSecretRef.md
Original file line number Diff line number Diff line change
@@ -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/
---
Expand Down Expand Up @@ -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)
8 changes: 5 additions & 3 deletions docs/en/rules/Azure.TrafficManager.Endpoints.md
Original file line number Diff line number Diff line change
@@ -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/
---
Expand All @@ -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)
66 changes: 63 additions & 3 deletions docs/en/rules/Azure.TrafficManager.Protocol.md
Original file line number Diff line number Diff line change
@@ -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/
---
Expand Down Expand Up @@ -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)
28 changes: 28 additions & 0 deletions docs/examples-trafficmanager.bicep
Original file line number Diff line number Diff line change
@@ -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'
}
}
}
49 changes: 49 additions & 0 deletions docs/examples-trafficmanager.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
}
}
2 changes: 1 addition & 1 deletion docs/examples-vng.bicep
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 41300de

Please sign in to comment.