Erstellen benutzerdefinierter Richtliniendefinitionen für die Computerkonfiguration

Bevor Sie beginnen, sollten Sie die Übersichtsseite zu Computerkonfiguration und die Details zu den Wartungsoptionen für die Computerkonfiguration lesen.

Führen Sie die folgenden Schritte aus, um eigene Richtlinien zu erstellen, die die Konformität überwachen oder den Zustand von Azure- oder Arc-fähigen Computern verwalten.

Installieren von PowerShell 7 und erforderlichen PowerShell-Modulen

Richten Sie zunächst eine Erstellungsumgebung für „Computerkonfiguration“ ein, um die erforderliche Version von PowerShell für Ihr Betriebssystem und das Modul GuestConfiguration zu installieren.

Erstellen und Veröffentlichen eines Computerkonfigurationspaketartefakts

Falls noch nicht geschehen, erstellen und veröffentlichen Sie ein benutzerdefiniertes Paket für „Computerkonfiguration“, indem Sie die Schritte unter Erstellen benutzerdefinierter Paketartefakte für „Computerkonfiguration“ ausführen. Überprüfen Sie dann das Paket in Ihrer Entwicklungsumgebung, indem Sie die Schritte unter Testen von Paketartefakten für „Computerkonfiguration“ ausführen.

$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

Richtlinienanforderungen für die Computerkonfiguration

Der Abschnitt metadata der Richtliniendefinition muss zwei Eigenschaften für den Dienst „Computerkonfiguration“ enthalten, um die Bereitstellung von und Berichterstellung zu Computerkonfigurationszuweisungen zu automatisieren. Die Eigenschaft category muss auf Guest Configuration festgelegt werden, und ein Abschnitt mit dem Namen guestConfiguration muss Informationen zur Computerkonfigurationszuweisung enthalten. Mit dem New-GuestConfigurationPolicy-Cmdlet wird dieser Text automatisch erstellt.

Im folgenden Beispiel wird der Abschnitt metadata veranschaulicht, der automatisch von New-GuestConfigurationPolicy erstellt wird.

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

Wenn der Definitionseffekt auf DeployIfNotExists festgelegt ist, muss der Abschnitt then Bereitstellungsdetails zu einer Computerkonfigurationszuweisung enthalten. Mit dem New-GuestConfigurationPolicy-Cmdlet wird dieser Text automatisch erstellt.

Erstellen einer Azure Policy-Definition

Nachdem ein benutzerdefiniertes Richtlinienpaket für Gastkonfigurationen erstellt und hochgeladen wurde, erstellen Sie die Richtliniendefinition für Computerkonfigurationen. Das Cmdlet New-GuestConfigurationPolicy verwendet ein benutzerdefiniertes Richtlinienpaket und erstellt eine Richtliniendefinition.

Für den Parameter PolicyId von New-GuestConfigurationPolicy ist eine eindeutige Zeichenfolge erforderlich: Ein global eindeutiger Bezeichner (GUID, Globally Unique Identifier) ist erforderlich. Generieren Sie für neue Definitionen mithilfe des Cmdlets New-GUID eine neue GUID. Verwenden Sie beim Aktualisieren der Definition dieselbe eindeutige Zeichenfolge für PolicyId, um sicherzustellen, dass die richtige Definition aktualisiert wird.

Parameter des Cmdlets New-GuestConfigurationPolicy:

• PolicyId: Eine GUID.
• ContentUri: Öffentlicher HTTP-/HTTPS-URI des Pakets mit dem Inhalt der Computerkonfiguration.
• DisplayName: Anzeigename der Richtlinie.
• Beschreibung: Beschreibung der Richtlinie.
• Parameter: Richtlinienparameter, die in einer Hashtabelle bereitgestellt werden.
• PolicyVersion: Richtlinienversion.
• Pfad: Zielpfad, unter dem Richtliniendefinitionen erstellt werden. Geben Sie diesen Parameter nicht als Pfad zu einer lokalen Kopie des Pakets an.
• Plattform: Zielplattform (Windows/Linux) für das Paket mit den Richtlinien und dem Inhalt der Computerkonfiguration.
• Modus: (Groß-/Kleinschreibung wird berücksichtigt: ApplyAndMonitor, ApplyAndAutoCorrect, Audit) wählen Sie aus, ob die Richtlinie die Konfiguration überwachen oder bereitstellen soll. Der Standardwert ist Audit.
• Mit Tag werden der Richtliniendefinition ein oder mehrere Tags hinzugefügt.
• Mit Category wird das Feld mit den Kategoriemetadaten in der Richtliniendefinition festgelegt.
• LocalContentPath ist der Pfad zur lokalen Kopie der Computerkonfigurationspaketdatei .zip. Dieser Parameter ist erforderlich, wenn Sie eine benutzerseitig zugewiesene verwaltete Identität verwenden, um Zugriff auf ein Azure Storge-Blob bereitzustellen.
• ManagedIdentityResourceId ist die resourceId der benutzerseitig zugewiesenen verwalteten Identität, die Lesezugriff auf das Azure Storage-Blob mit der Computerkonfigurationspaketdatei .zip hat. Dieser Parameter ist erforderlich, wenn Sie eine benutzerseitig zugewiesene verwaltete Identität verwenden, um Zugriff auf ein Azure Storge-Blob bereitzustellen.
• ExcludeArcMachines gibt an, dass die Richtliniendefinition Arc-Computer ausschließen soll. Dieser Parameter ist erforderlich, wenn Sie eine benutzerseitig zugewiesene verwaltete Identität verwenden, um Zugriff auf ein Azure Storge-Blob bereitzustellen.

Weitere Informationen zum Parameter Mode finden Sie auf der Seite Konfigurieren von Korrekturoptionen für „Computerkonfiguration“.

Erstellen Sie eine Richtliniendefinition, die mithilfe eines benutzerdefinierten Konfigurationspakets in einem angegebenen Pfad überwacht:

$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

Erstellen Sie eine Richtliniendefinition, die ein benutzerdefiniertes Konfigurationspaket in einem angegebenen Pfad erzwingt:

$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

Erstellen Sie eine Richtliniendefinition, die ein benutzerdefiniertes Konfigurationspaket mit einer benutzerseitig zugewiesenen verwalteten Identität erzwingt:

$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

In der Ausgabe des Cmdlets wird ein Objekt zurückgegeben, das den Anzeigenamen der Definition und den Pfad der Richtliniendateien enthält. JSON-Definitionsdateien, die Überwachungsrichtliniendefinitionen erstellen, weisen den Namen auditIfNotExists.json und Dateien, die Richtliniendefinitionen zum Anwenden von Konfigurationen erstellen, weisen den Namen deployIfNotExists.json auf.

Filtern von Richtlinien der Computerkonfiguration mit Tags

Die mit Cmdlets im Modul GuestConfiguration erstellten Richtliniendefinitionen können optional einen Filter für Tags enthalten. Der Parameter Tag von New-GuestConfigurationPolicy unterstützt ein Array mit Hashtabellen, die die einzelnen Tageinträge enthalten. Die Tags werden dem Abschnitt if der Richtliniendefinition hinzugefügt und können nicht per Richtlinienzuweisung geändert werden.

Es folgt ein Beispielcodeschnipsel einer Richtliniendefinition zum Filtern nach Tags.

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

Verwenden von Parametern in benutzerdefinierten Richtliniendefinitionen für Computerkonfigurationen

„Computerkonfiguration“ unterstützt das Überschreiben von Eigenschaften einer DSC-Konfiguration zur Laufzeit. Dieses Feature bewirkt, dass die Werte in der MOF-Datei im Paket nicht als statisch angesehen werden müssen. Die Überschreibungswerte werden über Azure Policy bereitgestellt und ändern nicht, wie die DSC-Konfigurationen erstellt oder kompiliert werden.

Die Computerkonfiguration unterstützt die folgenden Werttypen für Parameter:

• String
• Boolean
• Double
• Float

Die Cmdlets New-GuestConfigurationPolicy und Get-GuestConfigurationPackageComplianceStatus enthalten einen Parameter mit dem Namen Parameter. Dieser Parameter verwendet eine Hashtabellendefinition mit allen Details zu den einzelnen Parametern und erstellt die erforderlichen Abschnitte jeder für die Azure Policy-Definition verwendeten Datei.

Im folgenden Beispiel wird eine Richtliniendefinition zum Überwachen eines Diensts erstellt, bei der der Benutzer bei der Zuweisung der Richtlinie eine Auswahl aus einer Liste trifft.

# 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

Veröffentlichen der Azure Policy Definition

Abschließend können Sie die Richtliniendefinitionen mit dem Cmdlet New-AzPolicyDefinition veröffentlichen. Mit den folgenden Befehle wird Ihre Computerkonfigurationsrichtlinie im Richtliniencenter veröffentlicht.

Um den Befehl New-AzPolicyDefinition auszuführen, benötigen Sie Zugriffsrechte zum Erstellen von Richtliniendefinitionen in Azure. Die entsprechenden Autorisierungsanforderungen sind auf der Seite mit der Übersicht über Azure Policy dokumentiert. Die empfohlene integrierte Rolle ist Resource Policy Contributor.

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

Oder, wenn die Richtlinie den Typ DINE (DeployIfNotExists) hat, verwenden Sie diesen Befehl:

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

Bei der in Azure erstellten Definition ist der letzte Schritt das Zuweisen der Definition. Informieren Sie sich darüber, wie Sie die Definition über das Portal, die Azure CLI oder über Azure PowerShell zuweisen können.

Lebenszyklus von Richtlinien

Wenn Sie ein Update für die Definition freigeben möchten, ändern Sie die Details für das Gastkonfigurationspaket und die Azure Policy-Definition.

Geben Sie zunächst beim Ausführen von New-GuestConfigurationPackage einen Namen für das Paket an, der es gegenüber früheren Versionen eindeutig kennzeichnet. Sie können z. B. eine Versionsnummer in den Namen einschließen wie in PackageName_1.0.0. Die Zahl in diesem Beispiel dient nur dazu, das Paket eindeutig zu machen, und nicht dazu, das Paket als neuer oder älter als andere Pakete zu kennzeichnen.

Aktualisieren Sie als anschließend die Parameter für das Cmdlet New-GuestConfigurationPolicy gemäß den folgenden Erläuterungen.

• Version: Beim Ausführen des Cmdlets New-GuestConfigurationPolicy müssen Sie eine höhere Versionsnummer als die derzeit veröffentlichte angeben.
• contentUri: Wenn Sie das Cmdlet New-GuestConfigurationPolicy ausführen, müssen Sie einen URI zum Speicherort des Pakets angeben. Durch Einschließen einer Paketversion in den Dateinamen wird sichergestellt, dass sich der Wert dieser Eigenschaft in jedem Release ändert.
• contentHash: Das Cmdlet New-GuestConfigurationPolicy aktualisiert diese Eigenschaft automatisch. Es handelt sich um einen Hashwert des Pakets, das mit New-GuestConfigurationPackage erstellt wurde. Diese Eigenschaft muss für die von Ihnen veröffentlichte Datei vom Typ .zip stimmen. Wenn nur die Eigenschaft contentUri aktualisiert wird, akzeptiert die Erweiterung das Inhaltspaket nicht.

Die einfachste Möglichkeit zum Veröffentlichen eines aktualisierten Pakets besteht darin, den in diesem Artikel beschriebenen Vorgang zu wiederholen und eine aktualisierte Versionsnummer anzugeben. Mit dieser Vorgehensweise wird sichergestellt, dass alle Eigenschaften richtig aktualisiert wurden.

Nächste Schritte

• Weisen Sie Ihre Richtliniendefinition mithilfe des Azure-Portals zu.
• Erfahren Sie, wie Sie die Richtlinienzuweisungen Konformitätsdetails für die Maschinenkonfiguration anzeigen.