Rozszerzenie Desired State Configuration z szablonami usługi Azure Resource Manager

Uwaga

Przed włączeniem rozszerzenia DSC chcielibyśmy wiedzieć, że nowsza wersja rozszerzenia DSC jest teraz ogólnie dostępna, zarządzana przez funkcję konfiguracji maszyny o nazwie Azure Automange. Funkcja konfiguracji maszyny łączy funkcje programu obsługi rozszerzenia Desired State Configuration (DSC), usługi Azure Automation State Configuration i najczęściej żądanych funkcji z opinii klientów. Konfiguracja maszyny obejmuje również obsługę maszyn hybrydowych za pośrednictwem serwerów z obsługą usługi Arc.

W tym artykule opisano szablon usługi Azure Resource Manager dla procedury obsługi rozszerzenia Desired State Configuration (DSC). Wiele przykładów używa metody RegistrationURL (podanej jako ciąg) i RegistrationKey (dostarczonej jako psCredential do dołączenia za pomocą usługi Azure Automation). Aby uzyskać szczegółowe informacje na temat uzyskiwania tych wartości, zobacz Używanie metakonfiguracji DSC do rejestrowania maszyn hybrydowych.

Uwaga

Przed włączeniem rozszerzenia DSC chcielibyśmy wiedzieć, że nowsza wersja rozszerzenia DSC jest teraz ogólnie dostępna, zarządzana przez funkcję konfiguracji maszyny o nazwie Azure Automange. Funkcja konfiguracji maszyny łączy funkcje programu obsługi rozszerzenia Desired State Configuration (DSC), usługi Azure Automation State Configuration i najczęściej żądanych funkcji z opinii klientów. Konfiguracja maszyny obejmuje również obsługę maszyn hybrydowych za pośrednictwem serwerów z obsługą usługi Arc.

Uwaga

Możesz napotkać nieco inne przykłady schematów. Zmiana schematu miała miejsce w wydaniu z października 2016 r. Aby uzyskać szczegółowe informacje, zobacz Aktualizowanie z poprzedniego formatu.

Przykład szablonu dla maszyny wirtualnej z systemem Windows

Poniższy fragment kodu jest kierowany do sekcji Zasób szablonu. Rozszerzenie DSC dziedziczy domyślne właściwości rozszerzenia. Aby uzyskać więcej informacji, zobacz VirtualMachineExtension, klasa.

{
  "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"
        }
      ]
    }
  }
}

Przykład szablonu dla zestawów skalowania maszyn wirtualnych z systemem Windows

Węzeł zestawu skalowania maszyn wirtualnych zawiera sekcję właściwości , która ma atrybut VirtualMachineProfile, extensionProfile . W obszarze rozszerzenia dodaj szczegóły rozszerzenia DSC.

Rozszerzenie DSC dziedziczy domyślne właściwości rozszerzenia. Aby uzyskać więcej informacji, zobacz VirtualMachineScaleSetExtension, klasa.

"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"
              }
            ]
          }
        }
      }
    ]
  }

Szczegółowe informacje o ustawieniach

Użyj następującego schematu w sekcji ustawień rozszerzenia DSC platformy Azure w szablonie usługi Resource Manager.

Aby uzyskać listę argumentów dostępnych dla domyślnego skryptu konfiguracji, zobacz Domyślny skrypt konfiguracji.

"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"
}

Szczegóły

Nazwa właściwości	Typ	Opis
settings.wmfVersion	string	Określa wersję programu Windows Management Framework (WMF), która powinna być zainstalowana na maszynie wirtualnej. Ustawienie tej właściwości na najnowszą wersję programu WMF. Obecnie jedynymi możliwymi wartościami tej właściwości są 4.0, 5.0, 5.1 i najnowsze. Te możliwe wartości podlegają aktualizacjom. Wartość domyślna to najnowsza.
settings.configuration.url	string	Określa lokalizację adresu URL, z której chcesz pobrać plik konfiguracji DSC .zip. Jeśli podany adres URL wymaga tokenu SAS na potrzeby dostępu, ustaw właściwość protectedSettings.configurationUrlSasToken na wartość tokenu SAS. Ta właściwość jest wymagana, jeśli zdefiniowano właściwość settings.configuration.script lub settings.configuration.function . Jeśli dla tych właściwości nie podano żadnej wartości, rozszerzenie wywołuje domyślny skrypt konfiguracji, aby ustawić metadane programu Location Configuration Manager (LCM) i należy podać argumenty.
settings.configuration.script	string	Określa nazwę pliku skryptu, który zawiera definicję konfiguracji DSC. Ten skrypt musi znajdować się w folderze głównym pliku .zip pobranego z adresu URL określonego przez właściwość settings.configuration.url . Ta właściwość jest wymagana, jeśli zdefiniowano wartość settings.configuration.url lub settings.configuration.script . Jeśli dla tych właściwości nie podano żadnej wartości, rozszerzenie wywołuje domyślny skrypt konfiguracji w celu ustawienia metadanych LCM i należy podać argumenty.
settings.configuration.function	string	Określa nazwę konfiguracji DSC. Konfiguracja o nazwie musi być uwzględniona w skry skrycie, który definiuje settings.configuration.script . Ta właściwość jest wymagana, jeśli zdefiniowano element settings.configuration.url lub settings.configuration.function . Jeśli dla tych właściwości nie podano żadnej wartości, rozszerzenie wywołuje domyślny skrypt konfiguracji w celu ustawienia metadanych LCM i należy podać argumenty.
settings.configurationArguments	Kolekcja	Definiuje wszystkie parametry, które mają zostać przekazane do konfiguracji DSC. Ta właściwość nie jest szyfrowana.
settings.configurationData.url	string	Określa adres URL, z którego ma być pobierany plik danych konfiguracji (psd1), który ma być używany jako dane wejściowe dla konfiguracji DSC. Jeśli podany adres URL wymaga tokenu SAS na potrzeby dostępu, ustaw właściwość protectedSettings.configurationDataUrlSasToken na wartość tokenu SAS.
settings.privacy.dataCollection	string	Włącza lub wyłącza zbieranie danych telemetrycznych. Jedynymi możliwymi wartościami tej właściwości są Włączone, Wyłącz, "" lub $null. Pozostawienie tej właściwości pustej lub null powoduje włączenie telemetrii. Wartość domyślna to "". Aby uzyskać więcej informacji, zobacz Zbieranie danych rozszerzenia DSC platformy Azure.
settings.advancedOptions.downloadMappings	Kolekcja	Definiuje alternatywne lokalizacje, z których mają być pobierane WMF. Aby uzyskać więcej informacji, zobacz Rozszerzenie DSC platformy Azure 2.8 i sposób mapowania pobierania zależności rozszerzeń na własną lokalizację.
protectedSettings.configurationArguments	Kolekcja	Definiuje wszystkie parametry, które mają zostać przekazane do konfiguracji DSC. Ta właściwość jest szyfrowana.
protectedSettings.configurationUrlSasToken	string	Określa token SAS używany do uzyskiwania dostępu do adresu URL, który definiuje settings.configuration.url . Ta właściwość jest szyfrowana.
protectedSettings.configurationDataUrlSasToken	string	Określa token SYGNATURy dostępu współdzielonego używany do uzyskiwania dostępu do adresu URL zdefiniowanego przez parametr settings.configurationData.url . Ta właściwość jest szyfrowana.

Domyślny skrypt konfiguracji

Aby uzyskać więcej informacji na temat następujących wartości, zobacz Ustawienia podstawowe programu Local Configuration Manager. Możesz użyć domyślnego skryptu konfiguracji rozszerzenia DSC, aby skonfigurować tylko właściwości LCM wymienione w poniższej tabeli.

Nazwa właściwości	Typ	Opis
protectedSettings.configurationArguments.RegistrationKey	PsCredential	Wymagana właściwość. Określa klucz używany do zarejestrowania węzła w usłudze Azure Automation jako hasło obiektu poświadczeń programu PowerShell. Tę wartość można automatycznie odnaleźć przy użyciu metody listkeys względem konta usługi Automation. Zobacz przykład.
settings.configurationArguments.RegistrationUrl	string	Wymagana właściwość. Określa adres URL punktu końcowego usługi Automation, pod którym węzeł próbuje się zarejestrować. Tę wartość można automatycznie odnaleźć przy użyciu metody referencyjnej względem konta usługi Automation.
settings.configurationArguments.NodeConfigurationName	string	Wymagana właściwość. Określa konfigurację węzła na koncie usługi Automation, która ma zostać przypisana do węzła.
settings.configurationArguments.ConfigurationMode	string	Określa tryb LCM. Prawidłowe opcje to ApplyOnly, ApplyandMonitor i ApplyandAutoCorrect. Wartość domyślna to ApplyandMonitor.
settings.configurationArguments.RefreshFrequencyMins	uint32	Określa, jak często LCM próbuje sprawdzić konto usługi Automation pod kątem aktualizacji. Wartość domyślna to 30. Wartość minimalna to 15.
settings.configurationArguments.ConfigurationModeFrequencyMins	uint32	Określa, jak często narzędzie LCM weryfikuje bieżącą konfigurację. Wartość domyślna to 15. Wartość minimalna to 15.
settings.configurationArguments.RebootNodeIfNeeded	boolean	Określa, czy węzeł można automatycznie ponownie uruchomić, jeśli operacja DSC żąda go. Wartość domyślna to false.
settings.configurationArguments.ActionAfterReboot	string	Określa, co się stanie po ponownym uruchomieniu podczas stosowania konfiguracji. Prawidłowe opcje to ContinueConfiguration i StopConfiguration. Wartość domyślna to ContinueConfiguration.
settings.configurationArguments.AllowModuleOverwrite	boolean	Określa, czy menedżer LCM zastępuje istniejące moduły w węźle. Wartość domyślna to false.

ustawienia a chronioneUstawienia

Wszystkie ustawienia są zapisywane w pliku tekstowym ustawień na maszynie wirtualnej. Właściwości wymienione w obszarze ustawień są właściwościami publicznymi. Właściwości publiczne nie są szyfrowane w pliku tekstowym ustawień. Właściwości wymienione w obszarze protectedSettings są szyfrowane przy użyciu certyfikatu i nie są wyświetlane w postaci zwykłego tekstu w pliku ustawień na maszynie wirtualnej.

Jeśli konfiguracja wymaga poświadczeń, możesz uwzględnić poświadczenia w obszarze protectedSettings:

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

Przykładowy skrypt konfiguracji

W poniższym przykładzie pokazano domyślne zachowanie rozszerzenia DSC, które polega na udostępnieniu ustawień metadanych LCM i zarejestrowaniu się w usłudze Automation DSC. Argumenty konfiguracji są wymagane. Argumenty konfiguracji są przekazywane do domyślnego skryptu konfiguracji w celu ustawienia metadanych LCM.

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

Przykład użycia skryptu konfiguracji w usłudze Azure Storage

Poniższy przykład pochodzi z przeglądu programu obsługi rozszerzeń DSC. W tym przykładzie użyto szablonów usługi Resource Manager zamiast poleceń cmdlet do wdrożenia rozszerzenia. Zapisz konfigurację IisInstall.ps1, umieść ją w pliku .zip (na przykład: iisinstall.zip), a następnie przekaż plik w dostępnym adresie URL. W tym przykładzie użyto usługi Azure Blob Storage, ale możesz pobrać .zip pliki z dowolnej lokalizacji.

W szablonie usługi Resource Manager następujący kod instruuje maszynę wirtualną, aby pobrała prawidłowy plik, a następnie uruchom odpowiednią funkcję programu PowerShell:

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

Przykład użycia przywołynych wartości rejestracji usługi Azure Automation

Poniższy przykład pobiera wartości RegistrationUrl i RegistrationKey , odwołując się do właściwości konta usługi Azure Automation i używając metody listkeys w celu pobrania klucza podstawowego (0). W tym przykładzie parametry automationAccountName i NodeConfigName zostały dostarczone do szablonu.

"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]"
        }
    }
}

Aktualizuj z poprzedniego formatu

Wszystkie ustawienia w poprzednim formacie rozszerzenia (i które mają właściwości publiczne ModulesUrl, ModuleSource, ModuleVersion, ConfigurationFunction, SasToken lub Properties) automatycznie dostosowują się do bieżącego formatu rozszerzenia. Biegają tak jak wcześniej.

Poniższy schemat pokazuje, jak wyglądał poprzedni schemat ustawień:

"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"
}

Oto jak poprzedni format dostosowuje się do bieżącego formatu:

Bieżąca nazwa właściwości	Poprzedni odpowiednik schematu
settings.wmfVersion	Ustawienia. WMFVersion
settings.configuration.url	Ustawienia. ModułyUrl
settings.configuration.script	Pierwsza część ustawień. ConfigurationFunction (przed \\)
settings.configuration.function	Druga część ustawień. ConfigurationFunction (po \\)
settings.configuration.module.name	Ustawienia. Źródło modułu
settings.configuration.module.version	Ustawienia. ModuleVersion
settings.configurationArguments	Ustawienia. Właściwości
settings.configurationData.url	protectedSettings.DataBlobUri (bez tokenu SAS)
settings.privacy.dataCollection	Ustawienia. Privacy.dataCollection
settings.advancedOptions.downloadMappings	Ustawienia. AdvancedOptions.DownloadMappings
protectedSettings.configurationArguments	protectedSettings.Properties
protectedSettings.configurationUrlSasToken	Ustawienia. Sygnatura dostępu współdzielonego
protectedSettings.configurationDataUrlSasToken	Token SYGNATURY dostępu współdzielonego z identyfikatora protectedSettings.DataBlobUri

Rozwiązywanie problemów

Poniżej przedstawiono niektóre błędy, które mogą wystąpić i jak można je naprawić.

Nieprawidłowe wartości

"Privacy.dataCollection to '{0}'. Jedynymi możliwymi wartościami są "", "Włącz" i "Wyłącz". "WmfVersion to '{0}'. Tylko możliwe wartości to ... i "latest".

Problem: Podana wartość jest niedozwolona.

Rozwiązanie: zmień nieprawidłową wartość na prawidłową wartość. Aby uzyskać więcej informacji, zobacz tabelę w sekcji Szczegóły.

Nieprawidłowy adres URL

"ConfigurationData.url to '{0}'. To nie jest prawidłowy adres URL" "DataBlobUri to '{0}". To nie jest prawidłowy adres URL" "Configuration.url is '{0}". To nie jest prawidłowy adres URL"

Problem: Podany adres URL jest nieprawidłowy.

Rozwiązanie: Sprawdź wszystkie podane adresy URL. Upewnij się, że wszystkie adresy URL rozpoznają prawidłowe lokalizacje, do których rozszerzenie może uzyskać dostęp na maszynie zdalnej.

Nieprawidłowy typ registrationKey

"Nieprawidłowy typ parametru RegistrationKey typu PSCredential".

Problem: Wartość RegistrationKey w pliku protectedSettings.configurationArguments nie może być podana jako dowolny typ inny niż PSCredential.

Rozwiązanie: Zmień wpis protectedSettings.configurationArguments dla registrationKey na typ PSCredential przy użyciu następującego formatu:

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

Nieprawidłowy typ configurationArgument

"Nieprawidłowy typ {0}configurationArguments"

Problem: właściwość ConfigurationArguments nie może rozpoznać obiektu tabeli skrótu.

Rozwiązanie: Ustaw właściwość ConfigurationArguments na tabelę skrótów. Postępuj zgodnie z formatem podanym w poprzednich przykładach. Poszukaj cudzysłowów, przecinków i nawiasów klamrowych.

Zduplikowane konfiguracjeArguments

"Znaleziono zduplikowane argumenty "{0}" zarówno w konfiguracji publicznej, jak i chronionejArguments"

Problem: KonfiguracjeArguments w ustawieniach publicznych i ConfigurationArguments w ustawieniach chronionych mają właściwości o tej samej nazwie.

Rozwiązanie: Usuń jedną z zduplikowanych właściwości.

Brakujące właściwości

"ustawienia. Configuration.function wymaga określenia parametru settings.configuration.url lub settings.configuration.module"

"ustawienia. Configuration.url wymaga określenia ustawienia.configuration.script"

"ustawienia. Configuration.script wymaga określenia parametru settings.configuration.url"

"ustawienia. Configuration.url wymaga, aby określono parametr settings.configuration.function"

"protectedSettings.ConfigurationUrlSasToken wymaga określenia ustawienia.configuration.url"

"protectedSettings.ConfigurationDataUrlSasToken wymaga określenia ustawienia.configurationData.url"

Problem: Zdefiniowana właściwość wymaga innej właściwości, której brakuje.

Rozwiązania:

• Podaj brakującą właściwość.
• Usuń właściwość, która wymaga brakującej właściwości.

Następne kroki

• Dowiedz się więcej o używaniu zestawów skalowania maszyn wirtualnych z rozszerzeniem DSC platformy Azure.
• Dowiedz się więcej na temat bezpiecznego zarządzania poświadczeniami dsC.
• Zapoznaj się z wprowadzeniem do procedury obsługi rozszerzenia DSC platformy Azure.
• Aby uzyskać więcej informacji na temat rozszerzenia DSC programu PowerShell, przejdź do centrum dokumentacji programu PowerShell.