Desired State Configuration-extensie met Azure Resource Manager-sjablonen

In dit artikel wordt de Azure Resource Manager-sjabloon voor de extensie-handler Desired State Configuration (DSC) beschreven. Veel van de voorbeelden gebruiken RegistrationURL (geleverd als een tekenreeks) en RegistrationKey (geleverd als een PSCredential voor onboarding met Azure Automation. Zie DSC-metaconfiguratie gebruiken om hybride machines te registreren voor meer informatie over het verkrijgen van deze waarden.

Voorbeeld van een sjabloon voor een Windows-VM

Het volgende codefragment wordt weergegeven in de sectie Resource van de sjabloon. De DSC-extensie neemt standaarduitbreidingseigenschappen over. Zie De klasse VirtualMachineExtension voor meer informatie.

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "[concat(parameters('VMName'), '/Microsoft.Powershell.DSC')]",
  "apiVersion": "2018-06-01",
  "location": "[parameters('location')]",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', parameters('VMName'))]"
  ],
  "properties": {
    "publisher": "Microsoft.Powershell",
    "type": "DSC",
    "typeHandlerVersion": "2.77",
    "autoUpgradeMinorVersion": true,
    "protectedSettings": {
      "Items": {
        "registrationKeyPrivate": "[listKeys(resourceId('Microsoft.Automation/automationAccounts/', parameters('automationAccountName')), '2018-06-30').Keys[0].value]"
      }
    },
    "settings": {
      "Properties": [
        {
          "Name": "RegistrationKey",
          "Value": {
            "UserName": "PLACEHOLDER_DONOTUSE",
            "Password": "PrivateSettingsRef:registrationKeyPrivate"
          },
          "TypeName": "System.Management.Automation.PSCredential"
        },
        {
          "Name": "RegistrationUrl",
          "Value": "[reference(concat('Microsoft.Automation/automationAccounts/', parameters('automationAccountName'))).registrationUrl]",
          "TypeName": "System.String"
        },
        {
          "Name": "NodeConfigurationName",
          "Value": "[parameters('nodeConfigurationName')]",
          "TypeName": "System.String"
        }
      ]
    }
  }
}

Sjabloonvoorbeeld voor virtuele-machineschaalsets van Windows

Een knooppunt van een virtuele-machineschaalset heeft een eigenschappensectie met het kenmerk VirtualMachineProfile extensionProfile . Voeg onder extensies de details voor DSC-extensie toe.

De DSC-extensie neemt standaarduitbreidingseigenschappen over. Zie de klasse VirtualMachineScaleSetExtension voor meer informatie.

"extensionProfile": {
    "extensions": [
      {
        "name": "Microsoft.Powershell.DSC",
        "properties": {
          "publisher": "Microsoft.Powershell",
          "type": "DSC",
          "typeHandlerVersion": "2.77",
          "autoUpgradeMinorVersion": true,
          "protectedSettings": {
            "Items": {
              "registrationKeyPrivate": "[listKeys(resourceId('Microsoft.Automation/automationAccounts/', parameters('automationAccountName')), '2018-06-30').Keys[0].value]"
            }
          },
          "settings": {
            "Properties": [
              {
                "Name": "RegistrationKey",
                "Value": {
                  "UserName": "PLACEHOLDER_DONOTUSE",
                  "Password": "PrivateSettingsRef:registrationKeyPrivate"
                },
                "TypeName": "System.Management.Automation.PSCredential"
              },
              {
                "Name": "RegistrationUrl",
                "Value": "[reference(concat('Microsoft.Automation/automationAccounts/', parameters('automationAccountName'))).registrationUrl]",
                "TypeName": "System.String"
              },
              {
                "Name": "NodeConfigurationName",
                "Value": "[parameters('nodeConfigurationName')]",
                "TypeName": "System.String"
              }
            ]
          }
        }
      }
    ]
  }

Gedetailleerde informatie over instellingen

Gebruik het volgende schema in de sectie instellingen van de Azure DSC-extensie in een Resource Manager-sjabloon.

Zie Standaardconfiguratiescript voor een lijst met argumenten die beschikbaar zijn voor het standaardconfiguratiescript.

"settings": {
    "wmfVersion": "latest",
    "configuration": {
        "url": "http://validURLToConfigLocation",
        "script": "ConfigurationScript.ps1",
        "function": "ConfigurationFunction"
    },
    "configurationArguments": {
        "argument1": "Value1",
        "argument2": "Value2"
    },
    "configurationData": {
        "url": "https://foo.psd1"
    },
    "privacy": {
        "dataCollection": "enable"
    },
    "advancedOptions": {
        "downloadMappings": {
            "customWmfLocation": "http://myWMFlocation"
        }
    }
},
"protectedSettings": {
    "configurationArguments": {
        "parameterOfTypePSCredential1": {
            "userName": "UsernameValue1",
            "password": "PasswordValue1"
        },
        "parameterOfTypePSCredential2": {
            "userName": "UsernameValue2",
            "password": "PasswordValue2"
        }
    },
    "configurationUrlSasToken": "?g!bber1sht0k3n",
    "configurationDataUrlSasToken": "?dataAcC355T0k3N"
}

Details

Standaardconfiguratiescript

Zie Basisinstellingen voor lokale Configuration Manager voor meer informatie over de volgende waarden. U kunt het standaardconfiguratiescript voor de DSC-extensie gebruiken om alleen de LCM-eigenschappen te configureren die in de volgende tabel worden vermeld.

settings versus protectedSettings

Alle instellingen worden opgeslagen in een tekstbestand voor instellingen op de VM. Eigenschappen die worden vermeld onder instellingen zijn openbare eigenschappen. Openbare eigenschappen worden niet versleuteld in het tekstbestand instellingen. Eigenschappen die worden vermeld onder protectedSettings worden versleuteld met een certificaat en worden niet weergegeven als tekst zonder opmaak in het instellingenbestand op de VM.

Als de configuratie referenties nodig heeft, kunt u de referenties opnemen in protectedSettings:

"protectedSettings": {
    "configurationArguments": {
        "parameterOfTypePSCredential1": {
               "userName": "UsernameValue1",
               "password": "PasswordValue1"
        }
    }
}

Voorbeeld van configuratiescript

In het volgende voorbeeld ziet u het standaardgedrag voor de DSC-extensie. Dit is het verstrekken van metagegevensinstellingen aan LCM en het registreren bij de Automation DSC-service. Configuratieargumenten zijn vereist. Configuratieargumenten worden doorgegeven aan het standaardconfiguratiescript om LCM-metagegevens in te stellen.

"settings": {
    "configurationArguments": {
        "RegistrationUrl" : "[parameters('registrationUrl1')]",
        "NodeConfigurationName" : "nodeConfigurationNameValue1"
    }
},
"protectedSettings": {
    "configurationArguments": {
        "RegistrationKey": {
            "userName": "NOT_USED",
            "Password": "registrationKey"
        }
    }
}

Voorbeeld met behulp van het configuratiescript in Azure Storage

Het volgende voorbeeld is afkomstig uit het overzicht van de DSC-extensiehandler. In dit voorbeeld worden Resource Manager sjablonen gebruikt in plaats van cmdlets om de extensie te implementeren. Sla de IisInstall.ps1 configuratie op, plaats deze in een .zip-bestand (bijvoorbeeld) iisinstall.zipen upload het bestand vervolgens in een toegankelijke URL. In dit voorbeeld wordt Azure Blob Storage gebruikt, maar u kunt .zip bestanden downloaden vanaf elke willekeurige locatie.

In de sjabloon Resource Manager wordt de vm met de volgende code geïnstrueerd om het juiste bestand te downloaden en vervolgens de juiste PowerShell-functie uit te voeren:

"settings": {
    "configuration": {
        "url": "https://demo.blob.core.windows.net/iisinstall.zip",
        "script": "IisInstall.ps1",
        "function": "IISInstall"
    }
},
"protectedSettings": {
    "configurationUrlSasToken": "odLPL/U1p9lvcnp..."
}

Voorbeeld met registratiewaarden waarnaar wordt verwezen Azure Automation

In het volgende voorbeeld worden de RegistrationUrl en RegistrationKey opgehaald door te verwijzen naar de Azure Automation accounteigenschappen en de methode listkeys te gebruiken om de primaire sleutel (0) op te halen. In dit voorbeeld zijn de parameters automationAccountName en NodeConfigName opgegeven voor de sjabloon.

"settings": {
    "RegistrationUrl" : "[reference(concat('Microsoft.Automation/automationAccounts/', parameters('automationAccountName'))).registrationUrl]",
    "NodeConfigurationName" : "[parameters('NodeConfigName')]"
},
"protectedSettings": {
    "configurationArguments": {
        "RegistrationKey": {
            "userName": "NOT_USED",
            "Password": "[listKeys(resourceId('Microsoft.Automation/automationAccounts/', parameters('automationAccountName')), '2018-01-15').Keys[0].value]"
        }
    }
}

Bijwerken vanuit een eerdere indeling

Alle instellingen in een eerdere indeling van de extensie (en die de openbare eigenschappen ModulesUrl, ModuleSource, ModuleVersion, ConfigurationFunction, SasToken of Properties hebben) worden automatisch aangepast aan de huidige indeling van de extensie. Ze rennen net zoals ze eerder deden.

In het volgende schema ziet u hoe het vorige instellingenschema eruit zag:

"settings": {
    "WMFVersion": "latest",
    "ModulesUrl": "https://UrlToZipContainingConfigurationScript.ps1.zip",
    "SasToken": "SAS Token if ModulesUrl points to private Azure Blob Storage",
    "ConfigurationFunction": "ConfigurationScript.ps1\\ConfigurationFunction",
    "Properties": {
        "ParameterToConfigurationFunction1": "Value1",
        "ParameterToConfigurationFunction2": "Value2",
        "ParameterOfTypePSCredential1": {
            "UserName": "UsernameValue1",
            "Password": "PrivateSettingsRef:Key1"
        },
        "ParameterOfTypePSCredential2": {
            "UserName": "UsernameValue2",
            "Password": "PrivateSettingsRef:Key2"
        }
    }
},
"protectedSettings": {
    "Items": {
        "Key1": "PasswordValue1",
        "Key2": "PasswordValue2"
    },
    "DataBlobUri": "https://UrlToConfigurationDataWithOptionalSasToken.psd1"
}

De vorige indeling wordt als volgt aangepast aan de huidige indeling:

Problemen oplossen

Hier volgen enkele van de fouten die u kunt tegenkomen en hoe u deze kunt oplossen.

Ongeldige waarden

"Privacy.dataCollection is '{0}'. De enige mogelijke waarden zijn '', 'Enable' en 'Disable''. "WmfVersion is '{0}'. Alleen mogelijke waarden zijn ... en 'nieuwste'.

Probleem: een opgegeven waarde is niet toegestaan.

Oplossing: Wijzig de ongeldige waarde in een geldige waarde. Zie de tabel in Details voor meer informatie.

Ongeldige URL

"ConfigurationData.url is '{0}'. Dit is geen geldige URL: 'DataBlobUri is '{0}'. Dit is geen geldige URL' Configuration.url is '{0}'. Dit is geen geldige URL'

Probleem: een opgegeven URL is niet geldig.

Oplossing: Controleer al uw opgegeven URL's. Zorg ervoor dat alle URL's worden omgezet naar geldige locaties waartoe de extensie toegang heeft op de externe computer.

Ongeldig type RegistrationKey

"Ongeldig type voor parameter RegistrationKey van het type PSCredential."

Probleem: De waarde RegistrationKey in protectedSettings.configurationArguments kan niet worden opgegeven als een ander type dan een PSCredential.

Oplossing: Wijzig de vermelding protectedSettings.configurationArguments voor RegistrationKey in een PSCredential-type met de volgende indeling:

"configurationArguments": {
    "RegistrationKey": {
        "userName": "NOT_USED",
        "Password": "RegistrationKey"
    }
}

Ongeldig ConfigurationArgument-type

"Ongeldig configurationArguments type {0}"

Probleem: de eigenschap ConfigurationArguments kan niet worden omgezet in een hash-tabelobject .

Oplossing: Maak van de eigenschap ConfigurationArguments een Hash-tabel. Volg de indeling in de voorgaande voorbeelden. Let op aanhalingstekens, komma's en accolades.

Dubbele configuratieargumenten

"Dubbele argumenten gevonden in{0} zowel openbare als beveiligde configuratieArguments"

Probleem: De ConfigurationArguments in openbare instellingen en de ConfigurationArguments in beveiligde instellingen hebben eigenschappen met dezelfde naam.

Oplossing: Verwijder een van de dubbele eigenschappen.

Ontbrekende eigenschappen

"settings. Configuration.function vereist dat settings.configuration.url of settings.configuration.module is opgegeven'

"settings. Configuration.url vereist dat settings.configuration.script is opgegeven'

"settings. Configuration.script vereist dat settings.configuration.url is opgegeven'

"settings. Configuration.url vereist dat settings.configuration.function is opgegeven'

"protectedSettings.ConfigurationUrlSasToken vereist dat settings.configuration.url is opgegeven"

"protectedSettings.ConfigurationDataUrlSasToken vereist dat settings.configurationData.url is opgegeven"

Probleem: Een gedefinieerde eigenschap heeft een andere eigenschap nodig, die ontbreekt.

Oplossingen:

• Geef de ontbrekende eigenschap op.
• Verwijder de eigenschap die de ontbrekende eigenschap nodig heeft.

Volgende stappen

• Meer informatie over het gebruik van virtuele-machineschaalsets met de Azure DSC-extensie.
• Meer informatie over het beveiligd referentiebeheer van DSC.
• Krijg een inleiding tot de Azure DSC-extensiehandler.
• Ga naar het PowerShell-documentatiecentrum voor meer informatie over PowerShell DSC.