Merge pull request #233248 from GitHubber17/refresh-79519-guest-config

v-dirichards · web-flow · commit 27e18e94a1e8 · 2023-04-05T14:53:12.000-05:00
Freshness Pass for User Story: 79519
diff --git a/articles/virtual-machines/extensions/guest-configuration.md b/articles/virtual-machines/extensions/guest-configuration.md
@@ -1,106 +1,95 @@
 ---
-title: Guest configuration extension
-description: Learn about the extension used to audit / configure settings inside virtual machines
+title: Azure Automanage machine configuration (guest configuration)
+description: Learn about the machine configuration extension feature of Azure Automanage, and audit and configure settings for Azure virtual machines.
 ms.topic: article
 ms.service: virtual-machines
 ms.subservice: extensions
 author: mgreenegit
 ms.author: migreene
-ms.date: 04/15/2021
+ms.date: 04/05/2023
 ---
 
-# Overview of the guest configuration extension
+# Azure Automanage machine configuration extension
 
-The Guest Configuration extension is a component of Azure Policy that performs audit and configuration operations inside virtual machines.
-Policies such as security baseline definitions for
-[Linux](https://portal.azure.com/#blade/Microsoft_Azure_Policy/PolicyDetailBlade/definitionId/%2Fproviders%2FMicrosoft.Authorization%2FpolicyDefinitions%2Ffc9b3da7-8347-4380-8e70-0a0361d8dedd)
-and [Windows](https://portal.azure.com/#blade/Microsoft_Azure_Policy/PolicyDetailBlade/definitionId/%2Fproviders%2FMicrosoft.Authorization%2FpolicyDefinitions%2F72650e9f-97bc-4b2a-ab5f-9781a9fcecbc)
-can't check settings inside machines until the extension is installed.
+The machine configuration extension is a feature of Azure Automanage that performs audit and configuration operations inside virtual machines (VMs).
+
+To check policies inside VMs, such as Azure compute security baseline definitions for [Linux](https://portal.azure.com/#blade/Microsoft_Azure_Policy/PolicyDetailBlade/definitionId/%2Fproviders%2FMicrosoft.Authorization%2FpolicyDefinitions%2Ffc9b3da7-8347-4380-8e70-0a0361d8dedd) and [Windows](https://portal.azure.com/#blade/Microsoft_Azure_Policy/PolicyDetailBlade/definitionId/%2Fproviders%2FMicrosoft.Authorization%2FpolicyDefinitions%2F72650e9f-97bc-4b2a-ab5f-9781a9fcecbc), the machine configuration extension must be installed.
 
 ## Prerequisites
 
-For the machine to authenticate to the Guest Configuration service, the machine must have a
-[System-Assigned Managed Identity](../../active-directory/managed-identities-azure-resources/overview.md).
-The identity requirement on a virtual machine is met if the following property is set.
+To enable your VM to authenticate to the machine configuration service, your VM must have a [system-assigned managed identity](/azure/active-directory/managed-identities-azure-resources/overview). You can satisfy the identity requirement for your VM by setting the `"type": "SystemAssigned"` property:
 
-  ```json
-  "identity": {
-    "type": "SystemAssigned"
-  }
-  ```
+```json
+"identity": {
+   "type": "SystemAssigned"
+}
+```
 
-### Operating Systems
+### Operating systems
 
-Support for the Guest Configuration extension is the same as operating system support
-[documented for the end to end solution](../../governance/machine-configuration/overview.md#supported-client-types).
+Operating system support for the machine configuration extension is the same as documented [operating system support for the end-to-end solution](/azure/governance/machine-configuration/overview#supported-client-types).
 
 ### Internet connectivity
 
-The agent installed by the Guest Configuration extension must be able to reach
-content packages listed by Guest Configuration assignments,
-and report status to the Guest Configuration service.
-The machine can connect using outbound HTTPS over
-TCP port 443, or if a connection is provided through private networking.
+The agent installed by the machine configuration extension must be able to reach content packages listed by guest configuration assignments,
+and report status to the machine configuration service. The VM can connect by using outbound HTTPS over TCP port 443, or a connection provided through private networking.
+
 To learn more about private networking, see the following articles:
 
-- [Guest Configuration, communicate over private link in Azure](../../governance/machine-configuration/overview.md#communicate-over-private-link-in-azure)
-- [Use private endpoints for Azure Storage](../../storage/common/storage-private-endpoints.md)
+- [Azure Automanage machine configuration, Communicate over Azure Private Link](/azure/governance/machine-configuration/overview#communicate-over-private-link-in-azure)
+- [Use private endpoints for Azure Storage](/azure/storage/common/storage-private-endpoints)
 
-## How can I install the extension?
+## Install the extension
 
-The instance name of the extension must be set to
-"AzurePolicyforWindows" or "AzurePolicyforLinux",
-because the policies referenced above require these specific strings.
+You can install and deploy the machine configuration extension directly from the Azure CLI or PowerShell. Deployment templates are also available for Azure Resource Manager (ARM), Bicep, and Terraform. For deployment template details, see [Microsoft.GuestConfiguration guestConfigurationAssignments](/azure/templates/microsoft.guestconfiguration/guestconfigurationassignments?pivots=deployment-language-arm-template).
 
-By default, all deployments update to the latest version. The value
-of property _autoUpgradeMinorVersion_ defaults to "true" unless it is otherwise
-specified. You do not need to worry about updating your code when
-new versions of the extension are released.
+> [!NOTE]
+> In the following deployment examples, replace `<placeholder>` parameter values with specific values for your configuration.
 
-## Automatic upgrade
+### Deployment considerations
 
-The guest configuration extension supports property `enableAutomaticUpgrade`. When this
-property is set to `true`, Azure will automatically upgrade to the latest version
-of the extension as future releases become available. For more information, see the page
-[Automatic Extension Upgrade for VMs and Scale Sets in Azure](../automatic-extension-upgrade.md)
+Before you install and deploy the machine configuration extension, review the following considerations.
 
-### Azure Policy
+- **Instance name**. When you install the machine configuration extension, the instance name of the extension must be set to `AzurePolicyforWindows` or `AzurePolicyforLinux`. The security baseline definition policies described earlier require these specific strings.
 
-To deploy the latest version of the extension at scale including identity requirements,
-[assign](../../governance/policy/assign-policy-portal.md) the Azure Policy:
+- **Versions**. By default, all deployments update to the latest version. The value of the `autoUpgradeMinorVersion` property defaults to `true` unless otherwise specified. This feature helps to alleviate concerns about updating your code when new versions of the machine configuration extension are released.
 
-[Deploy prerequisites to enable Guest Configuration policies on virtual machines](https://github.com/Azure/azure-policy/blob/master/built-in-policies/policySetDefinitions/Guest%20Configuration/GuestConfiguration_Prerequisites.json).
+- **Automatic upgrade**. The machine configuration extension supports the `enableAutomaticUpgrade` property. When this property is set to `true`, Azure automatically upgrades to the latest version of the extension as future releases become available. For more information, see [Automatic Extension Upgrade for VMs and Virtual Machine Scale Sets in Azure](/azure/virtual-machines/automatic-extension-upgrade).
+
+- **Azure Policy**. To deploy the latest version of the machine configuration extension at scale including identity requirements, follow the steps in [Create a policy assignment to identify noncompliant resources](/azure/governance/policy/assign-policy-portal#create-a-policy-assignment). Create the following assignment with Azure Policy:
+   - [Deploy prerequisites to enable Guest Configuration policies on virtual machines](https://github.com/Azure/azure-policy/blob/master/built-in-policies/policySetDefinitions/Guest%20Configuration/GuestConfiguration_Prerequisites.json)
+
+- **Other properties**. You don't need to include any settings or protected-settings properties on the machine configuration extension. The agent retrieves this class of information from the Azure REST API [Guest Configuration assignment](/rest/api/guestconfiguration/guestconfigurationassignments) resources. For example, the [`ConfigurationUri`](/rest/api/guestconfiguration/guestconfigurationassignments/createorupdate#guestconfigurationnavigation), [`Mode`](/rest/api/guestconfiguration/guestconfigurationassignments/createorupdate#configurationmode), and [`ConfigurationSetting`](/rest/api/guestconfiguration/guestconfigurationassignments/createorupdate#configurationsetting) properties are each managed per-configuration rather than on the VM extension.
 
 ### Azure CLI
 
 To deploy the extension for Linux:
 
-
 ```azurecli
-az vm extension set  --publisher Microsoft.GuestConfiguration --name ConfigurationforLinux --extension-instance-name AzurePolicyforLinux --resource-group myResourceGroup --vm-name myVM --enable-auto-upgrade true
+az vm extension set  --publisher Microsoft.GuestConfiguration --name ConfigurationForLinux --extension-instance-name AzurePolicyforLinux --resource-group <myResourceGroup> --vm-name <myVM> --enable-auto-upgrade true
 ```
 
 To deploy the extension for Windows:
 
 ```azurecli
-az vm extension set  --publisher Microsoft.GuestConfiguration --name ConfigurationforWindows --extension-instance-name AzurePolicyforWindows --resource-group myResourceGroup --vm-name myVM --enable-auto-upgrade true
+az vm extension set  --publisher Microsoft.GuestConfiguration --name ConfigurationforWindows --extension-instance-name AzurePolicyforWindows --resource-group <myResourceGroup> --vm-name <myVM> --enable-auto-upgrade true
 ```
 
 ### PowerShell
 
 To deploy the extension for Linux:
 
 ```powershell
-Set-AzVMExtension -Publisher 'Microsoft.GuestConfiguration' -Type 'ConfigurationforLinux' -Name 'AzurePolicyforLinux' -TypeHandlerVersion 1.0 -ResourceGroupName 'myResourceGroup' -Location 'myLocation' -VMName 'myVM' -EnableAutomaticUpgrade $true
+Set-AzVMExtension -Publisher 'Microsoft.GuestConfiguration' -ExtensionType 'ConfigurationForLinux' -Name 'AzurePolicyforLinux' -TypeHandlerVersion 1.0 -ResourceGroupName '<myResourceGroup>' -Location '<myLocation>' -VMName '<myVM>' -EnableAutomaticUpgrade $true
 ```
 
 To deploy the extension for Windows:
 
 ```powershell
-Set-AzVMExtension -Publisher 'Microsoft.GuestConfiguration' -Type 'ConfigurationforWindows' -Name 'AzurePolicyforWindows' -TypeHandlerVersion 1.0 -ResourceGroupName 'myResourceGroup' -Location 'myLocation' -VMName 'myVM' -EnableAutomaticUpgrade $true
+Set-AzVMExtension -Publisher 'Microsoft.GuestConfiguration' -ExtensionType 'ConfigurationforWindows' -Name 'AzurePolicyforWindows' -TypeHandlerVersion 1.0 -ResourceGroupName '<myResourceGroup>' -Location '<myLocation>' -VMName '<myVM>' -EnableAutomaticUpgrade $true
 ```
 
-### Resource Manager template
+### ARM template
 
 To deploy the extension for Linux:
 
@@ -115,7 +104,7 @@ To deploy the extension for Linux:
   ],
   "properties": {
     "publisher": "Microsoft.GuestConfiguration",
-    "type": "ConfigurationforLinux",
+    "type": "ConfigurationForLinux",
     "typeHandlerVersion": "1.0",
     "autoUpgradeMinorVersion": true,
     "enableAutomaticUpgrade": true, 
@@ -148,7 +137,7 @@ To deploy the extension for Windows:
 }
 ```
 
-### Bicep
+### Bicep template
 
 To deploy the extension for Linux:
 
@@ -162,7 +151,7 @@ resource windowsVMGuestConfigExtension 'Microsoft.Compute/virtualMachines/extens
   location: resourceGroup().location
   properties: {
     publisher: 'Microsoft.GuestConfiguration'
-    type: 'ConfigurationforLinux'
+    type: 'ConfigurationForLinux'
     typeHandlerVersion: '1.0'
     autoUpgradeMinorVersion: true
     enableAutomaticUpgrade: true
@@ -194,16 +183,16 @@ resource windowsVMGuestConfigExtension 'Microsoft.Compute/virtualMachines/extens
 }
 ```
 
-### Terraform
+### Terraform template
 
 To deploy the extension for Linux:
 
 ```terraform
 resource "azurerm_virtual_machine_extension" "gc" {
   name                       = "AzurePolicyforLinux"
-  virtual_machine_id         = "myVMID"
+  virtual_machine_id         = "<myVMID>"
   publisher                  = "Microsoft.GuestConfiguration"
-  type                       = "ConfigurationforLinux"
+  type                       = "ConfigurationForLinux"
   type_handler_version       = "1.0"
   auto_upgrade_minor_version = "true"
 }
@@ -214,44 +203,32 @@ To deploy the extension for Windows:
 ```terraform
 resource "azurerm_virtual_machine_extension" "gc" {
   name                       = "AzurePolicyforWindows"
-  virtual_machine_id         = "myVMID"
+  virtual_machine_id         = "<myVMID>"
   publisher                  = "Microsoft.GuestConfiguration"
   type                       = "ConfigurationforWindows"
   type_handler_version       = "1.0"
   auto_upgrade_minor_version = "true"
 }
 ```
 
-## Settings
-
-There's no need to include any settings or protected-settings properties on the extension.
-All such information is retrieved by the agent from
-[Guest Configuration assignment](/rest/api/guestconfiguration/guestconfigurationassignments)
-resources. For example, the
-[ConfigurationUri](/rest/api/guestconfiguration/guestconfigurationassignments/createorupdate#guestconfigurationnavigation),
-[Mode](/rest/api/guestconfiguration/guestconfigurationassignments/createorupdate#configurationmode),
-and
-[ConfigurationSetting](/rest/api/guestconfiguration/guestconfigurationassignments/createorupdate#configurationsetting)
-properties are each managed per-configuration rather than on the VM extension.
-
-## Guest Configuration resource provider error codes
+## Error messages
 
-See below for a list of the possible error messages when enabling the extension
+The following table lists possible error messages related to enabling the Guest Configuration extension.
 
-|Error Code|Description|
-|-|-|
-|NoComplianceReport|VM has not reported the compliance data.|
-|GCExtensionMissing|Guest Configuration extension is missing.|
-|ManagedIdentityMissing|Managed identity is missing.|
-|UserIdentityMissing|User assigned identity is missing.|
-|GCExtensionManagedIdentityMissing|Guest Configuration extension and managed identity is missing.|
-|GCExtensionUserIdentityMissing|Guest Configuration extension and user identity is missing.|
-|GCExtensionIdentityMissing|Guest Configuration extension, managed identity and user identity are missing.|
+| Error code | Description |
+|---|---|
+| **NoComplianceReport** | The VM hasn't reported the compliance data. |
+| **GCExtensionMissing** | The machine configuration (guest configuration) extension is missing. |
+| **ManagedIdentityMissing** | The managed identity is missing. |
+| **UserIdentityMissing** | The user-assigned identity is missing. |
+| **GCExtensionManagedIdentityMissing** | The machine configuration (guest configuration) extension and managed identity are missing. |
+| **GCExtensionUserIdentityMissing** | The machine configuration (guest configuration) extension and user-assigned identity are missing. |
+| **GCExtensionIdentityMissing** | The machine configuration (guest configuration) extension, managed identity, and user-assigned identity are missing. |
 
 ## Next steps
 
-* For more information about Azure Policy's guest configuration, see [Understand Azure Policy's Guest Configuration](../../governance/machine-configuration/overview.md)
-* For more information about how the Linux Agent and extensions work, see [Azure VM extensions and features for Linux](features-linux.md).
-* For more information about how the Windows Guest Agent and extensions work, see [Azure VM extensions and features for Windows](features-windows.md).
-* To install the Windows Guest Agent, see [Azure Windows Virtual Machine Agent Overview](agent-windows.md).
-* To install the Linux Agent, see [Azure Linux Virtual Machine Agent Overview](agent-linux.md).
+- For more information about the machine configuration extension, see [Understand the machine configuration feature of Azure Automanage](/azure/governance/machine-configuration/overview).
+- For more information about how the Linux Agent and extensions work, see [Virtual machine extensions and features for Linux](features-linux.md).
+- For more information about how the Windows Guest Agent and extensions work, see [Virtual machine extensions and features for Windows](features-windows.md).
+- To install the Windows Guest Agent, see [Azure Virtual Machine Agent overview](agent-windows.md).
+- To install the Linux Agent, see [Understanding and using the Azure Linux Agent](agent-linux.md).
