rozszerzenie Desired State Configuration za pomocą szablonów usługi Azure Resource Manager

  • Artykuł

Uwaga

Przed włączeniem rozszerzenia DSC chcielibyśmy wiedzieć, że nowsza wersja dsC jest teraz ogólnie dostępna, zarządzana przez funkcję usługi Azure Automange o nazwie konfiguracja maszyny. Funkcja konfiguracji maszyny łączy funkcje obsługi rozszerzeń Desired State Configuration (DSC), Azure Automation State Configuration i najczęściej żądanych funkcji z opinii klientów. Konfiguracja maszyny obejmuje również obsługę maszyny hybrydowej 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 rozszerzeń Desired State Configuration (DSC). Wiele przykładów używa metody RegistrationURL (podanej jako ciąg) i RegistrationKey (podanej jako psCredential do dołączenia za pomocą Azure Automation. Aby uzyskać szczegółowe informacje na temat uzyskiwania tych wartości, zobacz Use DSC metaconfiguration to register hybrid machines (Używanie metakonfiguracji DSC do rejestrowania maszyn hybrydowych).

Uwaga

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

Uwaga

Mogą wystąpić nieco inne przykłady schematów. Zmiana schematu nastąpiła w wersji 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 zawiera sekcję 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 ma 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 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 ciąg Określa wersję 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 ciąg Określa lokalizację adresu URL, z której należy pobrać plik konfiguracji DSC .zip. Jeśli podany adres URL wymaga tokenu SYGNATURy dostępu współdzielonego, 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 zostanie podana żadna wartość, rozszerzenie wywołuje domyślny skrypt konfiguracji, aby ustawić metadane lokalizacji Configuration Manager (LCM), a argumenty powinny zostać podane.
settings.configuration.script ciąg 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 parametr 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, aby ustawić metadane LCM i należy podać argumenty.
settings.configuration.function ciąg Określa nazwę konfiguracji DSC. Konfiguracja o nazwie musi zostać uwzględniona w skrycie, który definiuje plik settings.configuration.script . Ta właściwość jest wymagana, jeśli zdefiniowano wartość 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, aby ustawić metadane 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 ciąg 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 SYGNATURy dostępu współdzielonego, ustaw właściwość protectedSettings.configurationDataUrlSasToken na wartość tokenu SAS.
settings.privacy.dataCollection ciąg Włącza lub wyłącza zbieranie danych telemetrycznych. Jedyne możliwe wartości tej właściwości to Enable, Disable, "" 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 lokalizacje alternatywne, 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 rozszerzenia 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 ciąg Określa token sygnatury dostępu współdzielonego używany do uzyskiwania dostępu do adresu URL zdefiniowanego przez parametr settings.configuration.url . Ta właściwość jest szyfrowana.
protectedSettings.configurationDataUrlSasToken ciąg 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 lokalne Configuration Manager podstawowe. Aby skonfigurować tylko właściwości LCM wymienione w poniższej tabeli, możesz użyć domyślnego skryptu konfiguracji rozszerzenia DSC.

Nazwa właściwości Typ Opis
protectedSettings.configurationArguments.RegistrationKey PSCredential Wymagana właściwość. Określa klucz używany dla węzła do zarejestrowania się 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 ciąg 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 ciąg Wymagana właściwość. Określa konfigurację węzła na koncie usługi Automation do przypisania do węzła.
settings.configurationArguments.ConfigurationMode ciąg Określa tryb LCM. Prawidłowe opcje obejmują ApplyOnly, ApplyandMonitor i ApplyandAutoCorrect. Wartość domyślna to ApplyandMonitor.
settings.configurationArguments.RefreshFrequencyMins uint32 Określa, jak często program 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 program 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 uruchomić ponownie, jeśli operacja DSC żąda go. Wartość domyślna to false.
settings.configurationArguments.ActionAfterReboot ciąg Określa, co się dzieje 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 program LCM zastępuje istniejące moduły w węźle. Wartość domyślna to false.

ustawienia a ustawienia 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 za pomocą 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 procedury obsługi rozszerzeń DSC. W tym przykładzie użyto szablonów 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żna pobrać pliki .zip z dowolnej lokalizacji.

W szablonie Resource Manager następujący kod nakazuje maszynie wirtualnej pobranie poprawnego pliku, a następnie uruchomienie odpowiedniej funkcji 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 Azure Automation

Poniższy przykład pobiera wartość RegistrationUrl i RegistrationKey, odwołując się do właściwości konta 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]"
        }
    }
}

Aktualizacja z poprzedniego formatu

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

Poniższy schemat przedstawia wygląd poprzedniego schematu 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"
}

Poniżej przedstawiono, 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. ModulesUrl
settings.configuration.script Pierwsza część ustawień. ConfigurationFunction (przed \\)
settings.configuration.function Druga część ustawień. ConfigurationFunction (po \\)
settings.configuration.module.name Ustawienia. ModuleSource
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}'. Jedyne możliwe wartości to "", "Włącz" i "Wyłącz". "WmfVersion jest '{0}'. Tylko możliwe wartości to ... i "latest".

Problem: Podana wartość jest niedozwolona.

Rozwiązanie: zmień nieprawidłową wartość na prawidłową. 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 są rozpoznawane jako prawidłowe lokalizacje, do których rozszerzenie może uzyskać dostęp na maszynie zdalnej.

Nieprawidłowy typ klucza rejestracji

"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ótów .

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 konfiguracjeArgumenty

"Znaleziono zduplikowane argumenty "{0}" w konfiguracji publicznej 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 parametru settings.configuration.script"

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

"ustawienia. Configuration.url wymaga określenia parametru 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