Skip to content

Commit e81f77f

Browse files
michaeltlombardimichaeltlombardi
committed
(AB-85436) Cleanup machine config - links, length
This change updates the machine configuration articles for maintainability, focusing on reflowing the Markdown content to 100-character-wide lines and migrating the link syntax to reference links. This makes the Markdown more readable and easier to edit by: - Making the lines read mostly as plain language without having to parse around link URLs. - Reducing duplication by sharing reference definitions for links where possible. - Ensuring GitHub and other diffing tools can correctly parse a line for changes; they often break or malform on long lines. - Reducing the `% changed` metric for future changes as editing a single line can be separated from editing an entire paragraph.
1 parent d87da98 commit e81f77f

14 files changed

+1332
-1318
lines changed

‎articles/governance/machine-configuration/agent-notes.md

Lines changed: 52 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -6,25 +6,28 @@ ms.topic: conceptual
66
---
77
# Azure Automanage machine configuration agent release notes
88

9-
[!INCLUDE [Machine config rename banner](../includes/banner.md)]
9+
[!INCLUDE [Machine config rename banner][00]]
1010

1111
## About the guest configuration agent
1212

13-
The guest configuration agent receives improvements on an ongoing basis. To stay up to date with the most recent developments, this article provides you with information about:
13+
The guest configuration agent receives improvements on an ongoing basis. To stay up to date with
14+
the most recent developments, this article provides you with information about:
1415

1516
- The latest releases
1617
- Known issues
1718
- Bug fixes
1819

19-
For information on release notes for the connected machine agent, please see [What's new with the connected machine agent](../../azure-arc/servers/agent-release-notes.md).
20+
For information on release notes for the connected machine agent, please see
21+
[What's new with the connected machine agent][01].
2022

2123
## Release notes
2224

2325
### Version 1.29.48 - January 2023
2426

2527
#### New Features
2628

27-
- In this release we have added support for Linux distributions such as Red Hat Enterprise Linux (RHEL) 9, Mariner 1&2, Alma 9, and Rocky 9.
29+
- In this release we have added support for Linux distributions such as Red Hat Enterprise Linux
30+
(RHEL) 9, Mariner 1&2, Alma 9, and Rocky 9.
2831

2932
#### Fixed
3033

@@ -33,34 +36,61 @@ For information on release notes for the connected machine agent, please see [Wh
3336

3437
### Guest Configuration Linux Extension version 1.26.38
3538

36-
In this release, various improvements were made.
39+
In this release, various improvements were made.
3740

38-
- You can now restrict which URLs can be used to download machine configuration packages by setting the allowedGuestConfigPkgUrls tag on the server resource and providing a comma-separated list of URL patterns to allow. If the tag exists, the agent will only allow custom packages to be downloaded from the specified URLs. Built-in packages are unaffected by this feature.
41+
- You can now restrict which URLs can be used to download machine configuration packages by setting
42+
the allowedGuestConfigPkgUrls tag on the server resource and providing a comma-separated list of
43+
URL patterns to allow. If the tag exists, the agent will only allow custom packages to be
44+
downloaded from the specified URLs. Built-in packages are unaffected by this feature.
3945

4046
## Fixed
4147

42-
- Resolves local elevation of privilege vulnerability [CVE-2022-38007](https://msrc.microsoft.com/update-guide/vulnerability/CVE-2022-38007).
43-
- If you're currently running an older version of the AzurePolicyforLinux extension, use the PowerShell or Azure CLI commands below to update your extension to the latest version.
48+
- Resolves local elevation of privilege vulnerability [CVE-2022-38007][03].
49+
- If you're currently running an older version of the AzurePolicyforLinux extension, use the
50+
PowerShell or Azure CLI commands below to update your extension to the latest version.
4451

4552
```powershell
46-
Set-AzVMExtension -Publisher 'Microsoft.GuestConfiguration' -Type 'ConfigurationforLinux' -Name 'AzurePolicyforLinux' -TypeHandlerVersion 1.26.38 -ResourceGroupName 'myResourceGroup' -Location 'myLocation' -VMName 'myVM' -EnableAutomaticUpgrade $true
53+
$params = @{
54+
Publisher = 'Microsoft.GuestConfiguration'
55+
Type = 'ConfigurationforLinux'
56+
Name = 'AzurePolicyforLinux'
57+
TypeHandlerVersion = '1.26.38'
58+
ResourceGroupName = '<resource-group>'
59+
Location = '<location>'
60+
VMName = '<vm-name>'
61+
EnableAutomaticUpgrade = $true
62+
}
63+
Set-AzVMExtension @params
4764
```
4865

4966
```azurecli
50-
az vm extension set --publisher Microsoft.GuestConfiguration --name ConfigurationforLinux --extension-instance-name AzurePolicyforLinux --resource-group myResourceGroup --vm-name myVM --version 1.26.38 --enable-auto-upgrade true
67+
az vm extension set \
68+
--publisher Microsoft.GuestConfiguration \
69+
--name ConfigurationforLinux \
70+
--extension-instance-name AzurePolicyforLinux \
71+
--resource-group <resource-group> \
72+
--vm-name <vm-name> \
73+
--version 1.26.38 \
74+
--enable-auto-upgrade true
5175
```
5276

5377
## Next steps
5478

55-
- Set up a custom machine configuration package [development environment](./machine-configuration-create-setup.md).
56-
- [Create a package artifact](./machine-configuration-create.md)
57-
for machine configuration.
58-
- [Test the package artifact](./machine-configuration-create-test.md)
59-
from your development environment.
60-
- Use the `GuestConfiguration` module to
61-
[create an Azure Policy definition](./machine-configuration-create-definition.md)
62-
for at-scale management of your environment.
63-
- [Assign your custom policy definition](../policy/assign-policy-portal.md) using
64-
Azure portal.
65-
- Learn how to view
66-
[compliance details for machine configuration](../policy/how-to/determine-non-compliance.md) policy assignments.
79+
- Set up a custom machine configuration package [development environment][04].
80+
- [Create a package artifact][05] for machine configuration.
81+
- [Test the package artifact][06] from your development environment.
82+
- Use the `GuestConfiguration` module to [create an Azure Policy definition][07] for at-scale
83+
management of your environment.
84+
- [Assign your custom policy definition][08] using Azure portal.
85+
- Learn how to view [compliance details for machine configuration][09] policy assignments.
86+
87+
<!-- Reference link definitions -->
88+
[00]: ../includes/banner.md
89+
[01]: ../../azure-arc/servers/agent-release-notes.md
90+
[03]: https://msrc.microsoft.com/update-guide/vulnerability/CVE-2022-38007
91+
[04]: ./machine-configuration-create-setup.md
92+
[05]: ./machine-configuration-create.md
93+
[06]: ./machine-configuration-create-test.md
94+
[07]: ./machine-configuration-create-definition.md
95+
[08]: ../policy/assign-policy-portal.md
96+
[09]: ../policy/how-to/determine-non-compliance.md

‎articles/governance/machine-configuration/machine-configuration-assignments.md

Lines changed: 59 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -8,47 +8,48 @@ ms.topic: conceptual
88

99
[!INCLUDE [Machine config rename banner](../includes/banner.md)]
1010

11-
When an Azure Policy is assigned, if it's in the category "Guest Configuration"
12-
there's metadata included to describe a guest assignment.
11+
When an Azure Policy is assigned, if it's in the category "Guest Configuration" there's metadata
12+
included to describe a guest assignment.
1313

14-
[A video walk-through of this document is available](https://youtu.be/DmCphySEB7A).
14+
[A video walk-through of this document is available][01].
1515

16-
You can think of a guest assignment as a link between a machine and an Azure
17-
Policy scenario. For example, the following snippet associates the Azure Windows
18-
Baseline configuration with minimum version `1.0.0` to any machines in scope of
19-
the policy.
16+
You can think of a guest assignment as a link between a machine and an Azure Policy scenario. For
17+
example, the following snippet associates the Azure Windows Baseline configuration with minimum
18+
version `1.0.0` to any machines in scope of the policy.
2019

2120
```json
2221
"metadata": {
23-
"category": "Guest Configuration",
24-
"guestConfiguration": {
25-
"name": "AzureWindowsBaseline",
26-
"version": "1.*"
27-
}
28-
//additional metadata properties exist
22+
"category": "Guest Configuration",
23+
"guestConfiguration": {
24+
"name": "AzureWindowsBaseline",
25+
"version": "1.*"
26+
}
27+
//additional metadata properties exist
28+
}
2929
```
3030

3131
## How Azure Policy uses machine configuration assignments
3232

33-
The metadata information is used by the machine configuration service to
34-
automatically create an audit resource for definitions with either
35-
**AuditIfNotExists** or **DeployIfNotExists** policy effects. The resource type
36-
is `Microsoft.GuestConfiguration/guestConfigurationAssignments`. Azure Policy
37-
uses the **complianceStatus** property of the guest assignment resource to
38-
report compliance status. For more information, see
39-
[getting compliance data](../policy/how-to/get-compliance-data.md).
33+
The metadata information is used by the machine configuration service to automatically create an
34+
audit resource for definitions with either **AuditIfNotExists** or **DeployIfNotExists** policy
35+
effects. The resource type is `Microsoft.GuestConfiguration/guestConfigurationAssignments`. Azure
36+
Policy uses the **complianceStatus** property of the guest assignment resource to report compliance
37+
status. For more information, see [getting compliance data][02].
4038

4139
### Deletion of guest assignments from Azure Policy
4240

43-
When an Azure Policy assignment is deleted, if a machine configuration assignment
44-
was created by the policy, the machine configuration assignment is also deleted.
41+
When an Azure Policy assignment is deleted, if a machine configuration assignment was created by
42+
the policy, the machine configuration assignment is also deleted.
4543

46-
When an Azure Policy assignment is deleted from an initiative, if a machine configuration assignment was created by the policy, you will need to manually delete the corresponding machine configuration assignment. This can be done by navigating to the guest assignments page on Azure portal and deleting the assignment there.
44+
When an Azure Policy assignment is deleted from an initiative, if a machine configuration
45+
assignment was created by the policy, you will need to manually delete the corresponding machine
46+
configuration assignment. This can be done by navigating to the guest assignments page on Azure
47+
portal and deleting the assignment there.
4748

4849
## Manually creating machine configuration assignments
4950

50-
Guest assignment resources in Azure Resource Manager can be created by Azure
51-
Policy or any client SDK.
51+
Guest assignment resources in Azure Resource Manager can be created by Azure Policy or any client
52+
SDK.
5253

5354
An example deployment template:
5455

@@ -79,31 +80,30 @@ An example deployment template:
7980

8081
The following table describes each property of guest assignment resources.
8182

82-
| Property | Description |
83-
|-|-|
84-
| name | Name of the configuration inside the content package MOF file. |
85-
| contentUri | HTTPS URI path to the content package (.zip). |
86-
| contentHash | A SHA256 hash value of the content package, used to verify it has not changed. |
87-
| version | Version of the content package. Only used for built-in packages and not used for custom content packages. |
88-
| assignmentType | Behavior of the assignment. Allowed values: `Audit`, `ApplyandMonitor`, and `ApplyandAutoCorrect`. |
83+
| Property | Description |
84+
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
85+
| name | Name of the configuration inside the content package MOF file. |
86+
| contentUri | HTTPS URI path to the content package (`.zip`). |
87+
| contentHash | A SHA256 hash value of the content package, used to verify it has not changed. |
88+
| version | Version of the content package. Only used for built-in packages and not used for custom content packages. |
89+
| assignmentType | Behavior of the assignment. Allowed values: `Audit`, `ApplyandMonitor`, and `ApplyandAutoCorrect`. |
8990
| configurationParameter | List of DSC resource type, name, and value in the content package MOF file to be overridden after it's downloaded in the machine. |
9091

9192
### Deletion of manually created machine configuration assignments
9293

93-
Machine configuration assignments created through any manual approach (such as
94-
an Azure Resource Manager template deployment) must be deleted manually.
95-
Deleting the parent resource (virtual machine or Arc-enabled machine) will also
96-
delete the machine configuration assignment.
94+
Machine configuration assignments created through any manual approach (such as an Azure Resource
95+
Manager template deployment) must be deleted manually. Deleting the parent resource (virtual
96+
machine or Arc-enabled machine) will also delete the machine configuration assignment.
9797

98-
To manually delete a machine configuration assignment, use the following
99-
example. Make sure to replace all example strings, indicated by "\<\>" brackets.
98+
To manually delete a machine configuration assignment, use the following example. Make sure to
99+
replace all example strings, indicated by `<>` brackets.
100100

101101
```PowerShell
102102
# First get details about the machine configuration assignment
103103
$resourceDetails = @{
104-
ResourceGroupName = '<myResourceGroupName>'
104+
ResourceGroupName = '<resource-group-name>'
105105
ResourceType = 'Microsoft.Compute/virtualMachines/providers/guestConfigurationAssignments/'
106-
ResourceName = '<myVMName>/Microsoft.GuestConfiguration'
106+
ResourceName = '<vm-name>/Microsoft.GuestConfiguration'
107107
ApiVersion = '2020-06-25'
108108
}
109109
$guestAssignment = Get-AzResource @resourceDetails
@@ -117,16 +117,22 @@ $guestAssignment | Remove-AzResource
117117

118118
## Next steps
119119

120-
- Read the [machine configuration overview](./overview.md).
121-
- Setup a custom machine configuration package [development environment](./machine-configuration-create-setup.md).
122-
- [Create a package artifact](./machine-configuration-create.md)
123-
for machine configuration.
124-
- [Test the package artifact](./machine-configuration-create-test.md)
125-
from your development environment.
126-
- Use the `GuestConfiguration` module to
127-
[create an Azure Policy definition](./machine-configuration-create-definition.md)
128-
for at-scale management of your environment.
129-
- [Assign your custom policy definition](../policy/assign-policy-portal.md) using
130-
Azure portal.
131-
- Learn how to view
132-
[compliance details for machine configuration](../policy/how-to/determine-non-compliance.md) policy assignments.
120+
- Read the [machine configuration overview][03].
121+
- Setup a custom machine configuration package [development environment][04].
122+
- [Create a package artifact][05] for machine configuration.
123+
- [Test the package artifact][06] from your development environment.
124+
- Use the `GuestConfiguration` module to [create an Azure Policy definition][07] for at-scale
125+
management of your environment.
126+
- [Assign your custom policy definition][08] using Azure portal.
127+
- Learn how to view [compliance details for machine configuration][09] policy assignments.
128+
129+
<!-- Reference link definitions -->
130+
[01]: https://youtu.be/DmCphySEB7A
131+
[02]: ../policy/how-to/get-compliance-data.md
132+
[03]: ./overview.md
133+
[04]: ./machine-configuration-create-setup.md
134+
[05]: ./machine-configuration-create.md
135+
[06]: ./machine-configuration-create-test.md
136+
[07]: ./machine-configuration-create-definition.md
137+
[08]: ../policy/assign-policy-portal.md
138+
[09]: ../policy/how-to/determine-non-compliance.md

0 commit comments

Comments
 (0)