Condividi tramite

Come creare definizioni di criteri di configurazione del computer personalizzati

Prima di iniziare, è consigliabile leggere la pagina di panoramica per la configurazione del computer e i dettagli sulle opzioni di correzione della configurazione del computer.

Important

L'estensione di configurazione del computer è necessaria per le macchine virtuali di Azure. Per distribuire l'estensione su larga scala in tutti i computer, assegnare l'iniziativa di criteri seguente: Deploy prerequisites to enable machine configuration policies on virtual machines

Per usare i pacchetti di configurazione macchina che applicano le configurazioni, è necessaria l'estensione di configurazione guest della macchina virtuale di Azure versione 1.26.24 o successiva oppure l'agente ARC 1.10.0 o versione successiva.

Le definizioni dei criteri di configurazione macchina personalizzate che usano AuditIfNotExists o DeployIfNotExists si trovano nello stato di supporto disponibile a livello generale (GA).

Usare la procedura seguente per creare criteri personalizzati che controllano la conformità o gestiscono lo stato dei computer abilitati per Azure o ARC.

Installare PowerShell 7 e i moduli di PowerShell necessari

Prima di tutto, configurare un ambiente di creazione della configurazione del computer per installare la versione necessaria di PowerShell per il sistema operativo e il modulo GuestConfiguration.

Creare e pubblicare un artefatto del pacchetto di configurazione macchina

Se non è già stato fatto, creare e pubblicare un pacchetto di configurazione del computer personalizzato seguendo la procedura descritta in Come creare artefatti del pacchetto di configurazione del computer personalizzato. Convalidare quindi il pacchetto nell'ambiente di sviluppo seguendo la procedura descritta in Come testare gli artefatti del pacchetto di configurazione del computer.

Note

Il codice di esempio in questo articolo fa riferimento alla variabile $contentUri. Se si usa la stessa sessione di PowerShell delle esercitazioni precedenti per la creazione e il test degli artefatti del pacchetto, tale variabile potrebbe già disporre dell'URI per il pacchetto.

Se la variabile $contentUri non è impostata sull'URI per il pacchetto nella sessione di PowerShell, è necessario impostarla. In questo esempio viene usata la stringa di connessione di un account di archiviazione e il cmdlet New-AzStorageContext per creare un contesto di archiviazione. Ottiene quindi il BLOB di archiviazione per il pacchetto pubblicato e usa le proprietà dell'oggetto per ottenere l'URI del contenuto.

$connectionString = '<storage-account-connection-string>'
$context = New-AzStorageContext -ConnectionString $connectionString
$getParams = @{
    Context   = $context
    Container = '<container-name>'
    Blob      = '<published-package-file-name>'
}
$blob = Get-AzStorageBlob @getParams
$contentUri = $blob.ICloudBlob.Uri.AbsoluteUri

Requisiti dei criteri per la configurazione del computer

La sezione dei metadati della definizione dei criteri deve includere due proprietà per il servizio di configurazione del computer per automatizzare il provisioning e la creazione di report delle assegnazioni di configurazione guest. La proprietà category deve essere impostata su Guest Configuration e una sezione denominata guestConfiguration deve contenere informazioni sull'assegnazione della configurazione macchina. Il cmdlet New-GuestConfigurationPolicy crea automaticamente questo testo.

Nell'esempio seguente viene illustrata la sezione dei metadati creata automaticamente da New-GuestConfigurationPolicy.

"metadata": {
    "category": "Guest Configuration",
    "guestConfiguration": {
        "name": "test",
        "version": "1.0.0",
        "contentType": "Custom",
        "contentUri": "CUSTOM-URI-HERE",
        "contentHash": "CUSTOM-HASH-VALUE-HERE",
        "configurationParameter": {}
    }
}

Se l'effetto di definizione è impostato su DeployIfNotExists, la sezione successiva deve contenere i dettagli della distribuzione relativi a un'assegnazione di configurazione macchina. Il cmdlet New-GuestConfigurationPolicy crea automaticamente questo testo.

Creare una definizione di Criteri di Azure

Dopo aver creato e caricato un pacchetto di criteri personalizzati di configurazione macchina, creare la definizione dei criteri di configurazione macchina. Il cmdlet New-GuestConfigurationPolicy accetta un pacchetto di criteri personalizzati e crea una definizione dei criteri.

Il parametro PolicyId di New-GuestConfigurationPolicy richiede una stringa univoca. È necessario un identificatore univoco globale (GUID). Per le nuove definizioni, generare un nuovo GUID utilizzando il cmdlet New-GUID. Quando si apportano aggiornamenti alla definizione, usare la stessa stringa univoca per PolicyId per assicurarsi che la definizione corretta venga aggiornata.

Parametri del cmdlet New-GuestConfigurationPolicy:

  • PolicyId: GUID.

  • ContentUri: URI HTTP pubblico del pacchetto di contenuto della configurazione macchina.

  • DisplayName: nome visualizzato dei criteri.

  • Descrizione: descrizione dei criteri.

  • Parametro: parametri dei criteri forniti in una tabella hash.

  • PolicyVersion: versione dei criteri.

  • Percorso: percorso di destinazione in cui vengono create le definizioni dei criteri. Non specificare questo parametro come percorso di una copia locale del pacchetto.

  • Piattaforma: piattaforma di destinazione (Windows/Linux) per i criteri di configurazione macchina e il pacchetto di contenuto.

  • Modalità: (con distinzione tra maiuscole e minuscole: ApplyAndMonitor, ApplyAndAutoCorrect, Audit) scegliere se il criterio deve controllare o distribuire la configurazione. Il valore predefinito è Audit.

  • Tag aggiunge uno o più filtri di tag alla definizione dei criteri.

  • Category imposta il campo dei metadati della categoria nella definizione dei criteri.

  • LocalContentPath: percorso della copia locale del file .zip del pacchetto di configurazione macchina. Tale parametro è obbligatorio se si usa un'identità gestita assegnata dall'utente per fornire l'accesso a un BLOB di archiviazione di Azure.

  • ManagedIdentityResourceId: il resourceId dell'identità gestita assegnata dall'utente con accesso in lettura al BLOB di Archiviazione di Azure contenente il file .zip del pacchetto di configurazione macchina. Tale parametro è obbligatorio se si usa un'identità gestita assegnata dall'utente per fornire l'accesso a un BLOB di archiviazione di Azure.

  • ExcludeArcMachines: specifica che la definizione dei criteri deve escludere i computer ARC. Tale parametro è obbligatorio se si usa un'identità gestita assegnata dall'utente per fornire l'accesso a un BLOB di archiviazione di Azure.

  • UseSystemAssignedIdentity: questa è l'opzione per usare l'identità assegnata dal sistema per scaricare il pacchetto dal contenitore dell'account di archiviazione anziché usare l'URL SaS.

    Non è possibile usare questa opzione con ManagedIdentityResourceId. Le opzioni si escludono a vicenda.

    È possibile usare questo parametro senza l'opzione ExcludeArcMachines perché l'identità assegnata dal sistema è disponibile per i computer Arc.

Important

A differenza delle macchine virtuali di Azure, i computer connessi ad ARC attualmente non supportano le identità gestite assegnate dall'utente. Di conseguenza, il flag -ExcludeArcMachines è necessario per garantire l'esclusione di tali computer dalla definizione dei criteri. Affinché la macchina virtuale di Azure scarichi il pacchetto assegnato e applichi i criteri, l'agente di configurazione guest deve essere versione 1.29.82.0 o successiva per Windows e versione 1.26.76.0 o successiva per Linux.

Per i computer connessi ad Arc, è anche possibile usare identità gestite assegnate dal sistema per scaricare i pacchetti.

Per altre informazioni sul parametro Mode, vedere la pagina Come configurare le opzioni di correzione per la configurazione macchina.

Creare una definizione di criteri che controlla usando un pacchetto di configurazione personalizzato, in un percorso specificato:

$PolicyConfig      = @{
  PolicyId      = '_My GUID_'
  ContentUri    = $contentUri
  DisplayName   = 'My audit policy'
  Description   = 'My audit policy'
  Path          = './policies/auditIfNotExists.json'
  Platform      = 'Windows'
  PolicyVersion = 1.0.0
}

New-GuestConfigurationPolicy @PolicyConfig

Creare una definizione di criteri che applica un pacchetto di configurazione personalizzato, in un percorso specificato:

$PolicyConfig2      = @{
  PolicyId      = '_My GUID_'
  ContentUri    = $contentUri
  DisplayName   = 'My deployment policy'
  Description   = 'My deployment policy'
  Path          = './policies/deployIfNotExists.json'
  Platform      = 'Windows'
  PolicyVersion = 1.0.0
  Mode          = 'ApplyAndAutoCorrect'
}

New-GuestConfigurationPolicy @PolicyConfig2

Creare una definizione di criteri che applica un pacchetto di configurazione personalizzato usando un'identità gestita assegnata dall'utente:

$PolicyConfig3      = @{
  PolicyId                  = '_My GUID_'
  ContentUri                = $contentUri
  DisplayName               = 'My deployment policy'
  Description               = 'My deployment policy'
  Path                      = './policies/deployIfNotExists.json'
  Platform                  = 'Windows'
  PolicyVersion             = 1.0.0
  Mode                      = 'ApplyAndAutoCorrect'
  LocalContentPath          = "C:\Local\Path\To\Package"      # Required parameter for managed identity
  ManagedIdentityResourceId = "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}" # Required parameter for managed identity
}

New-GuestConfigurationPolicy @PolicyConfig3 -ExcludeArcMachines

Per questo scenario, è necessario disabilitare l'impostazione Consenti accesso anonimo BLOB e assegnare il ruolo Lettore dati BLOB di archiviazione nell'account di archiviazione all'identità.

Creare una definizione di criteri che applica un pacchetto di configurazione personalizzato usando un'identità gestita assegnata dal sistema:

$PolicyConfig4      = @{
  PolicyId                  = '_My GUID_'
  ContentUri                = $contentUri
  DisplayName               = 'My deployment policy'
  Description               = 'My deployment policy'
  Path                      = './policies/deployIfNotExists.json'
  Platform                  = 'Windows'
  PolicyVersion             = 1.0.0
  Mode                      = 'ApplyAndAutoCorrect'
  LocalContentPath          = "C:\Local\Path\To\Package"      # Required parameter for managed identity
}
New-GuestConfigurationPolicy @PolicyConfig4 -UseSystemAssignedIdentity

Per questo scenario, è necessario disabilitare l'impostazione Consenti l'accesso anonimo ai BLOB e assegnare all'identità di sistema il ruolo Lettore dati BLOB di archiviazione nell'account di archiviazione.

Note

È possibile recuperare il valore resourceId di un'identità gestita usando il cmdlet Get-AzUserAssignedIdentity di PowerShell.

L'output del cmdlet restituisce un oggetto contenente il nome visualizzato della definizione e il percorso dei file dei criteri. I file JSON di definizione che creano definizioni dei criteri di controllo hanno il nome auditIfNotExists.json e i file che creano definizioni di criteri per applicare le configurazioni hanno il nome deployIfNotExists.json.

Filtro dei criteri di configurazione dei computer tramite tag

Le definizioni dei criteri create dai cmdlet nel modulo GuestConfiguration possono includere facoltativamente un filtro per i tag. Il parametro Tag di New-GuestConfigurationPolicy supporta una matrice di tabelle hash contenenti singole voci di tag. I tag vengono aggiunti alla sezione if della definizione dei criteri e non possono essere modificati da un'assegnazione di criteri.

Segue un frammento di esempio di una definizione di criteri che filtra per tag.

"if": {
  "allOf" : [
    {
      "allOf": [
        {
          "field": "tags.Owner",
          "equals": "BusinessUnit"
        },
        {
          "field": "tags.Role",
          "equals": "Web"
        }
      ]
    },
    {
      // Original machine configuration content
    }
  ]
}

Uso dei parametri nelle definizioni dei criteri di configurazione del computer personalizzato

La configurazione del computer supporta l'override delle proprietà di una configurazione DSC in fase di esecuzione. Ciò significa che i valori nel file MOF del pacchetto non devono essere considerati statici. I valori di override vengono forniti tramite Criteri di Azure e non modificano la modalità di creazione o compilazione delle configurazioni DSC.

La configurazione del computer supporta i tipi di valore seguenti per i parametri:

  • String
  • Boolean
  • Double
  • Float

I cmdlet New-GuestConfigurationPolicy e Get-GuestConfigurationPackageComplianceStatus includono un parametro denominato Parameter. Tale parametro accetta una definizione di tabella hash, inclusi tutti i dettagli su ogni parametro e crea le sezioni necessarie di ogni file usato per la definizione di Criteri di Azure.

Nell'esempio seguente viene creata una definizione dei criteri per controllare un servizio, in cui l'utente seleziona un'opzione in un elenco al momento dell'assegnazione dei criteri.

# This DSC resource definition...
Service 'UserSelectedNameExample' {
    Name   = 'ParameterValue'
    Ensure = 'Present'
    State  = 'Running'
}

# ...can be converted to a hash table:
$PolicyParameterInfo     = @(
  @{
    # Policy parameter name (mandatory)
    Name                 = 'ServiceName'
    # Policy parameter display name (mandatory)
    DisplayName          = 'windows service name.'
    # Policy parameter description (optional)
    Description          = 'Name of the windows service to be audited.'
    # DSC configuration resource type (mandatory)
    ResourceType         = 'Service'
    # DSC configuration resource id (mandatory)
    ResourceId           = 'UserSelectedNameExample'
    # DSC configuration resource property name (mandatory)
    ResourcePropertyName = 'Name'
    # Policy parameter default value (optional)
    DefaultValue         = 'winrm'
    # Policy parameter allowed values (optional)
    AllowedValues        = @('BDESVC','TermService','wuauserv','winrm')
  })

# ...and then passed into the `New-GuestConfigurationPolicy` cmdlet
$PolicyParam = @{
  PolicyId      = 'My GUID'
  ContentUri    = $contentUri
  DisplayName   = 'Audit Windows Service.'
  Description   = "Audit if a Windows Service isn't enabled on Windows machine."
  Path          = '.\policies\auditIfNotExists.json'
  Parameter     = $PolicyParameterInfo
  PolicyVersion = 1.0.0
}

New-GuestConfigurationPolicy @PolicyParam

Pubblicare la definizione di Criteri di Azure

Infine, è possibile pubblicare le definizioni dei criteri usando il cmdlet New-AzPolicyDefinition. I comandi seguenti pubblicano i criteri di configurazione macchina nel Centro criteri.

Per eseguire il comando New-AzPolicyDefinition, è necessario accedere per creare le definizioni di criteri in Azure. I requisiti di autorizzazione specifici sono documentati nella pagina Panoramica di Criteri di Azure. Il ruolo predefinito consigliato è Resource Policy Contributor.

New-AzPolicyDefinition -Name 'mypolicydefinition' -Policy '.\policies\auditIfNotExists.json'

In alternativa, se i criteri sono una distribuzione qualora non esistano criteri (DINE), usano questo comando:

New-AzPolicyDefinition -Name 'mypolicydefinition' -Policy '.\policies\deployIfNotExists.json'

Con la definizione dei criteri creata in Azure, l'ultimo passaggio consiste nell'assegnare la definizione. Informazioni su come assegnare la definizione con il portale, l'interfaccia della riga di comando di Azure e Azure PowerShell.

Policy lifecycle

Se si vuole rilasciare un aggiornamento alla definizione dei criteri, apportare la modifica sia per il pacchetto di configurazione guest sia per i dettagli della definizione di Criteri di Azure.

Note

La proprietà version dell'assegnazione della configurazione macchina influisce solo sui pacchetti ospitati da Microsoft. La procedura consigliata per il controllo delle versioni del contenuto personalizzato consiste nell'includere la versione nel nome file.

In primo luogo, quando si esegue New-GuestConfigurationPackage, specificare un nome per il pacchetto che lo rende univoco rispetto alle versioni precedenti. È possibile includere un numero di versione nel nome, ad esempio PackageName_1.0.0. Il numero in questo esempio viene usato solo per rendere univoco il pacchetto, non per specificare che il pacchetto deve essere considerato più recente o precedente rispetto ad altri pacchetti.

In secondo luogo, aggiornare i parametri usati con il cmdlet New-GuestConfigurationPolicy seguendo ognuna delle spiegazioni seguenti.

  • Versione: quando si esegue il cmdlet New-GuestConfigurationPolicy, è necessario specificare un numero di versione maggiore di quello attualmente pubblicato.
  • contentUri: quando si esegue il cmdlet New-GuestConfigurationPolicy, è necessario specificare un URI per il percorso del pacchetto. L'inclusione di una versione del pacchetto nel nome file garantisce che il valore di questa proprietà cambi in ogni versione.
  • contentHash: il cmdlet New-GuestConfigurationPolicy aggiorna automaticamente questa proprietà. Si tratta di un valore hash del pacchetto creato da New-GuestConfigurationPackage. La proprietà deve essere corretta per il file .zip da pubblicare. Se viene aggiornata solo la proprietà contentUri, l'estensione rifiuta il pacchetto di contenuto.

Il modo più semplice per rilasciare un pacchetto aggiornato consiste nel ripetere il processo descritto in questo articolo e specificare un numero di versione aggiornato. Questo processo garantisce che tutte le proprietà siano state aggiornate correttamente.

Next steps

  • Last updated on