Update create-policy-definition.md

[kwirkykat]

• Switched the flow of the document by adding the Requirements section, moving the metadata section towards the end, and adding the Parameters and Examples section headers
• Fixed parameter descriptions. Removed Category parameter that does not exist. Added missing parameters. Copied parameter descriptions from help text in code

[prmerger-automator]

@kwirkykat : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change.

[kwirkykat]

@MutemwaRMasheke

[learn-build-service-prod]

Learn Build status updates of commit cd24b46:

✅ Validation status: passed

File	Status	Preview URL	Details
articles/governance/machine-configuration/how-to/create-policy-definition.md	✅Succeeded

For more details, please refer to the build report.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel

[prmerger-automator]

PRMerger Results

Issue	Description
File Change Percent	This PR contains file(s) with more than 30% file change.

[v-dirichards]

@kwirkykat @michaeltlombardi This content requires automated and human checks available only in the private repository. Please close this PR (#please-close) and move the commits to the private repository. If you need help moving the commits, contact the publicprs alias.

[prmerger-automator]

@kwirkykat : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change.

[michaeltlombardi]

Suggested some changes for rewording/styling - please let me know whether the changes remain technically correct or require further modification.

[michaeltlombardi]

Rewording and updating formatting:

Suggested change

	- **DisplayName**: The display name of the policy to create. The display name has a maximum length of 128 characters.
	- **Description**: The description of the policy to create. The description has a maximum length of 512 characters.
	- **PolicyId**: The unique GUID of this policy definition. If you are trying to update an existing policy definition, then this ID must match the 'name' field in the existing definition. For new definitions, generate a new GUID using the `New-GUID`
	cmdlet.
	- **PolicyVersion**: The version of the policy definition.
	If you are updating an existing policy definition, then this version should be greater than
	the value in the 'metadata.version' field in the existing definition.
	Note: This is NOT the version of the Guest Configuration package.
	You can validate the Guest Configuration package version via the ContentVersion parameter.
	- **ContentUri**: The public HTTP or HTTPS URI of the Guest Configuration package (.zip) to run via the created policy.
	Example: https://github.com/azure/auditservice/release/AuditService.zip
	Note: If you are using an Azure storage account to store the custom machine configuration package artifact, you have two options for access:
	1. Generate a blob shared access signature (SAS) token with read access and provide the full blob URI with the SAS token for the ContentUri parameter.
	2. Create a user-assigned managed identity with read access to the storage account blob containing the package.
	Provide the resource ID of the managed identity, a local path to the zipped package, a URI to the package without a SAS token and the ExcludeArcMachines parameter.
	With this option, once the generated policy is applied, the managed identity will be used to download the package onto the target machine.
	- **DisplayName**: The display name of the policy. The maximum length for this value is 128
	characters.
	- **Description**: The description of the policy. The maximum length for this value is 512
	characters.
	- **PolicyId**: The unique GUID for the policy definition. If you're updating an existing
	policy definition, then this ID must match the `name` field in the existing definition. For new
	definitions, generate a new GUID using the `New-GUID` cmdlet.
	- **PolicyVersion**: The version of the policy definition. If you're updating an existing policy
	definition, this version should be greater than the value in the 'metadata.version' field in the
	existing definition.
	This version is separate from the version of the Guest Configuration package. You can validate
	the Guest Configuration package version with the **ContentVersion** parameter.
	- **ContentUri**: The public HTTP or HTTPS URI of the Guest Configuration package (.zip) to use for
	the policy, such as `https://github.com/azure/auditservice/release/AuditService.zip`.
	If you're using an Azure storage account to store the custom machine configuration package
	artifact, you have two options for access:
	1. Generate a blob shared access signature (SAS) token with read access and provide the full
	blob URI with the SAS token for the **ContentUri** parameter.
	1. Create a user-assigned managed identity with read access to the storage account blob
	containing the package. Provide the resource ID of the managed identity, a local path to the
	zipped package, a URI to the package without a SAS token and the **ExcludeArcMachines**
	parameter. With this option, once the generated policy is applied, Machine Configuration
	uses the managed identity to download the package onto the target machine.

[michaeltlombardi]

Rewording and updating formatting:

Suggested change

	- **ManagedIdentityResourceId**: The `resourceId` of the User Assigned Managed Identity that has read access to the Azure Storage blob containing the `.zip` Machine Configuration package file.
	This parameter is required if you're using a User Assigned Managed Identity to provide access to an Azure Storage blob. This is the identity that is used to download the package from storage account container instead of using SaS url.
	The value for this parameter needs to be the resource id of the managed identity.
	This is an option to use when the package is stored in a storage account and the storage account is protected by a managed identity.
	Note: optional parameter. If this is specified, LocalContentPath and ExcludeArcMachines must also be specified.
	- **LocalContentPath**: This is the path to the local package zip file. This is used to calculate the hash of the package.
	The value of this parameter is not used in the policy definition.
	Note: optional parameter. If this is specified, ManagedIdentityResourceId must also be specified.
	- **ContentVersion**: If specified, the version of the Guest Configuration package (.zip) downloaded via the content URI must match this value.
	This is for validation only.
	Note: This is NOT the version of the policy definition.
	You can define the policy definition version via the PolicyVersion parameter.
	- **Path**: The path to the folder under which to create the new policy definition file.
	The default value is the 'definitions' folder under your GuestConfiguration module path.
	Note: Don't specify this parameter as the path to a local copy of the package.
	- **Platform**: The target platform (Windows or Linux) for the policy.
	The default value is Windows.
	- **ManagedIdentityResourceId**: The `resourceId` of the User Assigned Managed Identity that has
	read access to the Azure Storage blob containing the `.zip` Machine Configuration package file.
	This parameter is required if you're using a User Assigned Managed Identity to provide access to
	an Azure Storage blob. This is the identity that is used to download the package from storage
	account container instead of using SaS url.
	The value for this parameter must be the resource id of the managed identity. Use this parameter
	when the package is stored in a storage account and the storage account is protected by a managed
	identity.
	When you specify this parameter, you must also specify the **LocalContentPath** and
	**ExcludeArcMachines** parameters.
	- **LocalContentPath**: The path to the local package zip file. Machine Configuration uses this
	parameter to calculate the cryptographic hash of the package. The value of this parameter isn't
	used in the policy definition.
	This parameter is optional. If you specify this parameter, you must also specify the
	**ManagedIdentityResourceId** and **ExcludeArcMachines** parameters.
	- **ContentVersion**: Specifies that the version of the Guest Configuration package (.zip)
	downloaded from the content URI must match this value. This is for validation only. This
	parameter is optional.
	This value for this parameter is separate from defining the version of the policy definition. To
	define the policy definition version, use the **PolicyVersion** parameter.
	- **Path**: The path to the folder to create the new policy definition file in. The default value
	is the `definitions` folder under the **GuestConfiguration** module path.
	Don't specify this parameter as the path to a local copy of the package.
	- **Platform**: The target platform (`Windows` or `Linux`) for the policy. The default value is
	`Windows`.

[michaeltlombardi]

Suggested change

	- **Mode**: (case sensitive: `ApplyAndMonitor`, `ApplyAndAutoCorrect`, `Audit`) Defines the mode under which this policy should run the package on the machine. The default value is Audit. If the package has been created as Audit-only, you cannot create an Apply policy with that package. The package will need to be re-created in AuditAndSet mode.
	Allowed modes:
	Audit: Monitors the machine only. Will not make modifications to the machine.
	ApplyAndMonitor: Modifies the machine once if it does not match the expected state.
	Then monitors the machine only until another remediation task is triggered via Azure Policy.
	Will make modifications to the machine.
	ApplyAndAutoCorrect: Modifies the machine any time it does not match the expected state.
	You will need trigger a remediation task via Azure Policy to start modifications the first time.
	Will make modifications to the machine.
	- **Tag**: A hashtable of the tags that should be on machines to apply this policy to.
	If this is specified, the created policy will only be applied to machines with all the specified tags.
	- **IncludeVMSS**: Indicates that VMSS machines should be included in the policy. True by default. You will need to set this to false if publishing policies in clouds that do not have the VMSS resource provider available.
	- **ExcludeArcMachines**: Specifies that the Policy definition should exclude Arc machines. This parameter needs to be specified if the New-GuestConfigurationPolicy is using a User Assigned Identity.
	Enabling this parameter will signal that users are aware of exclusion of Arc enabled servers in the definition.
	- **Mode**: Defines the mode under which this policy should run the package on the machine. The
	default value is `Audit`.
	The following list defines the valid values for this parameter. The values are case-sensitive.
	- `Audit` - Only monitors the machine only.
	In this mode, Machine Configuration doesn't modify the machine.
	- `ApplyAndMonitor` - Modifies the machine once if it doesn't match the expected state, then
	monitors the state.
	In this mode, Machine Configuration monitors the machine after the operation. To enforce the
	desired state after the initial modification, trigger a remediation task with Azure Policy.
	- `ApplyAndAutoCorrect` - Modifies the machine any time it doesn't match the expected state.
	Trigger a remediation task with Azure Policy after defining the policy. Afterward, Machine
	Configuration will regularly inspect the machine and modify state as needed.
	If the package has been created as Audit-only, you cannot create an Apply policy with that
	package. Instead, re-create the policy with this parameter set to `AuditAndSet`.
	- **Tag**: A hashtable of the tags that should be on machines to apply this policy to.
	When you specify this parameter, Machine configuration only applies the policy to machines with
	every specified tag.
	- **IncludeVMSS**: Indicates that VMSS machines should be included in the policy. The default value
	for this parameter is `$true`. Set this parameter to `$false` when publishing policies in clouds
	that do not have the VMSS resource provider available.
	- **ExcludeArcMachines**: Specifies that the Policy definition should exclude Arc machines. This
	parameter is required when using a User Assigned Identity.
	Enabling this parameter signals that users are aware of exclusion of Arc-enabled servers in the
	definition.
	If you specify this parameter, you must also specify the **ManagedIdentityResourceId** and
	**LocalContentPath** parameters.

[michaeltlombardi]

Suggested change

	- **Parameter**: The parameters to expose on the policy.
	All parameters passed to the policy must be single string values.
	Example:
	```powershell
	$policyParameters = @(
	@{
	Name = 'ServiceName' # Required
	DisplayName = 'Windows Service Name' # Required
	Description = 'Name of the windows service to be audited.' # Required
	ResourceType = 'Service' # Required
	ResourceId = 'windowsService' # Required
	ResourcePropertyName = 'Name' # Required
	DefaultValue = 'winrm' # Optional
	AllowedValues = @('wscsvc', 'WSearch', 'wcncsvc', 'winrm') # Optional
	},
	@{
	Name = 'ServiceState' # Required
	DisplayName = 'Windows Service State' # Required
	Description = 'State of the windows service to be audited.' # Required
	ResourceType = 'Service' # Required
	ResourceId = 'windowsService' # Required
	ResourcePropertyName = 'State' # Required
	DefaultValue = 'Running' # Optional
	AllowedValues = @('Running', 'Disabled') # Optional
	}
	)
	```
	- **Parameter**: The parameters to expose on the policy. All parameters passed to the policy must
	be single string values. For example:
	```powershell
	$policyParameters = @(
	@{
	Name = 'ServiceName' # Required
	DisplayName = 'Windows Service Name' # Required
	Description = 'Name of the windows service to be audited.' # Required
	ResourceType = 'Service' # Required
	ResourceId = 'windowsService' # Required
	ResourcePropertyName = 'Name' # Required
	DefaultValue = 'winrm' # Optional
	AllowedValues = @('wscsvc', 'WSearch', 'wcncsvc', 'winrm') # Optional
	},
	@{
	Name = 'ServiceState' # Required
	DisplayName = 'Windows Service State' # Required
	Description = 'State of the windows service to be audited.' # Required
	ResourceType = 'Service' # Required
	ResourceId = 'windowsService' # Required
	ResourcePropertyName = 'State' # Required
	DefaultValue = 'Running' # Optional
	AllowedValues = @('Running', 'Disabled') # Optional
	}
	)
	```

[michaeltlombardi]

Suggested change

	The `New-GuestConfigurationPolicy` cmdlet handles this for you, but here is more information on the internals of the generated policy definitions.
	The policy definition **metadata** section must include two properties for the machine
	configuration service to automate provisioning and reporting of guest configuration assignments.
	The **category** property must be set to `Guest Configuration` and a section named
	**guestConfiguration** must contain information about the machine configuration assignment.
	The following example demonstrates the **metadata** section that's automatically created by
	`New-GuestConfigurationPolicy`.
	```json
	"metadata": {
	"category": "Guest Configuration",
	"guestConfiguration": {
	"name": "test",
	"version": "1.0.0",
	"contentType": "Custom",
	"contentUri": "CUSTOM-URI-HERE",
	"contentHash": "CUSTOM-HASH-VALUE-HERE",
	"configurationParameter": {}
	}
	}
	```
	If the definition effect is set to `DeployIfNotExists`, the **then** section must contain
	deployment details about a machine configuration assignment. The `New-GuestConfigurationPolicy`
	cmdlet creates this text automatically.
	This section describes the internals of the generated policy definitions. The `New-GuestConfigurationPolicy` cmdlet handles the prerequisites when generating a policy.
	The policy definition `metadata` section must include two properties for the Machine Configuration
	service to automate provisioning and reporting of Guest Configuration assignments:
	1. The `category` property must be set to `Guest Configuration`.
	1. The `guestConfiguration` property must contain information about the machine configuration
	assignment.
	The following example shows the `metadata` section that the `New-GuestConfigurationPolicy`
	automatically creates.
	```json
	"metadata": {
	"category": "Guest Configuration",
	"guestConfiguration": {
	"name": "test",
	"version": "1.0.0",
	"contentType": "Custom",
	"contentUri": "CUSTOM-URI-HERE",
	"contentHash": "CUSTOM-HASH-VALUE-HERE",
	"configurationParameter": {}
	}
	}
	```
	If the definition effect is set to `DeployIfNotExists`, the `then` field must contain deployment
	details about a machine configuration assignment. The `New-GuestConfigurationPolicy` cmdlet defines
	this information automatically.

[v-dirichards]

@kwirkykat Can you respond to the edits above?

[v-dirichards]

Nudging @kwirkykat

[v-ccolin]

I sent an email to the content owner today.

@MicrosoftDocs/public-repo-pr-review-team

[PMEds28]

@kwirkykat

Can you review this old PR and determine whether it needs to be closed or merged?

@MicrosoftDocs/public-repo-pr-review-team

[v-dirichards]

Nudging @kwirkykat, thanks.

[ttorble]

I sent email to the contributor today.

@MicrosoftDocs/public-repo-pr-review-team

[v-ccolin]

I sent an email to the content owner today.

@MicrosoftDocs/public-repo-pr-review-team

[Copilot]

Pull Request Overview

This PR restructures the machine configuration policy definition documentation to improve readability and flow. The document is reorganized with a new Requirements section upfront, detailed parameter descriptions with proper formatting, and better section organization.

Key changes:

• Added a Requirements section at the beginning with prerequisites and setup steps
• Expanded the Parameters section with comprehensive descriptions copied from help text
• Moved the metadata/policy requirements section to the end as implementation details

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

There's a typo in 'preqrequisite' - it should be 'prerequisite'.

Suggested change

	2. Ensure that the Machine Configuration preqrequisite policies are applied to any machines to which you would like to also apply your custom policies
	2. Ensure that the Machine Configuration prerequisite policies are applied to any machines to which you would like to also apply your custom policies

[Copilot]

The cmdlet name should be New-Guid (with lowercase 'uid') to match PowerShell naming conventions.

Suggested change

	- **PolicyId**: The unique GUID of this policy definition. If you are trying to update an existing policy definition, then this ID must match the 'name' field in the existing definition. For new definitions, generate a new GUID using the `New-GUID`
	- **PolicyId**: The unique GUID of this policy definition. If you are trying to update an existing policy definition, then this ID must match the 'name' field in the existing definition. For new definitions, generate a new GUID using the `New-Guid`