Расширение Desired State Configuration (DSC) с использованием шаблонов Azure Resource Manager

Статья
08/25/2024

Примечание.

Прежде чем включить расширение DSC, мы хотели бы знать, что более новая версия DSC теперь общедоступна, управляемая функцией конфигурации именованных компьютеров Azure Automange. Функция конфигурации компьютера объединяет функции обработчика расширений требуемой конфигурации состояния (DSC), служба автоматизации Azure конфигурации состояния и наиболее часто запрашиваемые функции из отзывов клиентов. Конфигурация компьютера также включает поддержку гибридных компьютеров с помощью серверов с поддержкой Arc.

В этой статье описывается шаблон Azure Resource Manager для обработчика расширения Desired State Configuration (DSC). Во многих примерах используется RegistrationURL (предоставляется в виде строки) и RegistrationKey (предоставляется в виде PSCredential) для подключения к службе автоматизации Azure. Дополнительные сведения о получении этих значений см. в статье об использовании метаконфигурации DSC для регистрации гибридных компьютеров.

Примечание.

Вы можете встретить немного отличающиеся примеры схемы. Изменение в схеме произошло в выпуске за октябрь 2016 года. Дополнительные сведения см. в разделе об обновлении предыдущего формата.

Пример шаблона для виртуальной машины Windows

В приведенном ниже фрагменте кода показан раздел Resource шаблона. Расширение DSC наследует свойства расширения по умолчанию. Дополнительные сведения см. в статье о классе VirtualMachineExtension.

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

Пример шаблона для масштабируемого набора виртуальных машин Windows

Узел масштабируемого набора виртуальных машин содержит раздел properties с атрибутами VirtualMachineProfile и extensionProfile. В разделе extensions добавьте данные о расширении DSC.

Расширение DSC наследует свойства расширения по умолчанию. Дополнительные сведения см. в статье о классе VirtualMachineScaleSetExtension.

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

Подробные сведения о разделе settings

Используйте указанную ниже схему в разделе settings расширения Azure DSC в шаблоне Resource Manager.

Список доступных аргументов для скрипта конфигурации по умолчанию см. в этом разделе.

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

Сведения

Имя свойства	Type	Описание
settings.wmfVersion	строка	Указывает версию Windows Management Framework (WMF), которую необходимо установить на виртуальной машине. Если задать для этого свойства значение latest, будет установлена последняя версия Windows Management Framework. В настоящее время для этого свойства доступны только такие значения: 4.0, 5.0, 5.1 и latest. Возможные значения зависят от обновлений. По умолчанию используется значение latest.
settings.configuration.url	строка	Указывает URL-адрес расположения, из которого можно скачать ZIP-файл конфигурации DSC. Если для доступа к предоставленному URL-адресу требуется маркер SAS, задайте для свойства protectedSettings.configurationUrlSasToken значение маркера SAS. Это свойство обязательное, если заданы свойства settings.configuration.script или settings.configuration.function. Если для этих свойств значение не задано, необходимо предоставить расширение, которое вызывает скрипт конфигурации по умолчанию для установки метаданных диспетчера конфигурации расположения (LCM) и аргументов.
settings.configuration.script	строка	Указывает имя файла скрипта, содержащего определение вашей конфигурации DSC. Этот скрипт должен находиться в корневом каталоге ZIP-файла, скачанного по URL-адресу, указанному в свойстве settings.configuration.url. Это свойство обязательное, если заданы свойства settings.configuration.url или settings.configuration.script. Если для этих свойств значение не задано, необходимо предоставить расширение, которое вызывает скрипт конфигурации по умолчанию для установки метаданных LCM и аргументов.
settings.configuration.function	строка	Указывает имя вашей конфигурации DSC. Указанную конфигурацию необходимо добавить в скрипт, который определяет свойство settings.configuration.script. Это свойство обязательное, если заданы свойства settings.configuration.url или settings.configuration.function. Если для этих свойств значение не задано, необходимо предоставить расширение, которое вызывает скрипт конфигурации по умолчанию для установки метаданных LCM и аргументов.
settings.configurationArguments	Коллекция	Определяет параметры, которые необходимо передать в конфигурацию DSC. Это свойство не зашифровано.
settings.configurationData.url	строка	Указывает URL-адрес расположения, из которого можно скачать файл данных конфигурации (в формате PDS1), используемый в качестве входных данных для вашей конфигурации DSC. Если для доступа к предоставленному URL-адресу требуется маркер SAS, задайте для свойства protectedSettings.configurationDataUrlSasToken значение маркера SAS.
settings.privacy.dataCollection	строка	Включает или отключает сбор данных телеметрии. Для этого свойства доступны только такие значения: Enable, Disable, '' или $null. Если для этого свойства не задано значение или задано значение null, сбор данных телеметрии будет выполняться. Значение по умолчанию — ''. Дополнительные сведения см. в записи блога Azure DSC Extension Data Collection (Коллекция данных расширения DSC Azure).
settings.advancedOptions.downloadMappings	Коллекция	Определяет альтернативные расположения для скачивания Windows Management Framework. Дополнительные сведения см. в записи блога Azure DSC Extension 2.8 & How to map downloads of the extension dependencies to your own location (Расширение DSC Azure версии 2.8. Сведения о сопоставлении загрузок зависимостей расширения с вашим расположением).
protectedSettings.configurationArguments	Коллекция	Определяет параметры, которые необходимо передать в конфигурацию DSC. Это свойство зашифровано.
protectedSettings.configurationUrlSasToken	строка	Указывает маркер SAS для доступа к URL-адресу, который определяет свойство settings.configuration.url. Это свойство зашифровано.
protectedSettings.configurationDataUrlSasToken	строка	Указывает маркер SAS для доступа к URL-адресу, который определяется свойством settings.configurationData.url. Это свойство зашифровано.

Скрипт конфигурации по умолчанию

Дополнительные сведения об указанных ниже значениях см. в разделе Базовые параметры. С помощью скрипта конфигурации по умолчанию расширения DSC можно настроить только свойства LCM, указанные в следующей таблице.

Имя свойства	Type	Описание
protectedSettings.configurationArguments.RegistrationKey	PSCredential	Обязательное свойство. Определяет ключ, используемый узлом для регистрации в службе автоматизации Azure в качестве пароля для объекта учетных данных PowerShell. Это значение можно автоматически обнаружить с помощью метода listkeys в учетной записи службы автоматизации. См. пример.
settings.configurationArguments.RegistrationUrl	строка	Обязательное свойство. Указывает URL-адрес конечной точки службы автоматизации, в которой пытается зарегистрироваться узел. Это значение можно автоматически обнаружить с помощью метода reference в учетной записи службы автоматизации.
settings.configurationArguments.NodeConfigurationName	строка	Обязательное свойство. Указывает конфигурацию узла в учетной записи службы автоматизации, которая будет присвоена узлу.
settings.configurationArguments.ConfigurationMode	строка	Указывает режим для LCM. Допустимые значения: ApplyOnly, ApplyandMonitior и ApplyandAutoCorrect. Значение по умолчанию — ApplyAndMonitor.
settings.configurationArguments.RefreshFrequencyMins	uint32	Указывает, как часто LCM пытается проверить учетную запись службы автоматизации на наличие обновлений. Значение по умолчанию — 30. Минимальное значение — 15.
settings.configurationArguments.ConfigurationModeFrequencyMins	uint32	Указывает, как часто LCM проверяет текущую конфигурацию. Значение по умолчанию — 15. Минимальное значение — 15.
settings.configurationArguments.RebootNodeIfNeeded	boolean	Указывает, может ли узел автоматически перезагружаться по запросу операции DSC. По умолчанию используется значение false.
settings.configurationArguments.ActionAfterReboot	строка	Указывает, что происходит после перезагрузки при применении конфигурации. Допустимые значения: ContinueConfiguration и StopConfiguration. Значение по умолчанию: ContinueConfiguration.
settings.configurationArguments.AllowModuleOverwrite	boolean	Указывает, перезаписывает ли LCM имеющиеся модули на узле. По умолчанию используется значение false.

Сравнение разделов settings и protectedSettings

Все параметры сохраняются в текстовом файле параметров на виртуальной машине. Свойства, указанные в разделе settings, общедоступные. Общедоступные свойства не зашифрованы в текстовом файле параметров. Свойства, указанные в разделе protectedSettings, зашифрованы с помощью сертификата, а это значит, что они не отображаются как обычный текст в файле параметров на виртуальной машине.

Если для конфигурации нужны учетные данные, их можно добавить в раздел protectedSettings.

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

Пример скрипта конфигурации

В указанном ниже примере показано поведение по умолчанию расширения DSC, которое заключается в предоставлении параметров метаданных LCM и регистрации в службе автоматизации DSC. Аргументы конфигурации необходимы и будут переданы в скрипт конфигурации по умолчанию, чтобы задать метаданные LCM.

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

Пример с использованием скрипта конфигурации в службе хранилища Azure

Указанный ниже пример основан на примере конфигурации в статье Общие сведения об обработчике расширения Desired State Configuration в Azure. В этом примере для развертывания расширения используются шаблоны Resource Manager, а не командлеты. Сохраните конфигурацию IisInstall.ps1, добавьте ее в ZIP-файл (пример: iisinstall.zip) и передайте файл на доступный URL-адрес. В этом примере используется хранилище BLOB-объектов Azure, но ZIP-файл можно скачать из любого произвольного расположения.

В шаблоне Resource Manager следующий код указывает виртуальной машине скачать правильный файл и выполнить соответствующую функцию PowerShell.

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

Пример использования ссылок на значения регистрации в службе автоматизации Azure

Следующий пример получает RegistrationUrl и RegistrationKey, ссылаясь на свойства учетной записи службы автоматизации Azure, используя метод listkeys для извлечения первичного ключа (0). В этом примере параметры automationAccountName и NodeConfigName были предоставлены в шаблоне.

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

Обновление из предыдущего формата

Все параметры в предыдущем формате расширения (содержащие общедоступные свойства ModulesUrl, ModuleSource, ModuleVersion, ConfigurationFunction, SasToken или Properties) автоматически адаптируются к текущему формату расширения. и выполняются в обычном режиме.

Раньше схема settings выглядела следующим образом:

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

Вот как меняется предыдущий формат:

Имя текущего свойства	Предыдущий эквивалент схемы
settings.wmfVersion	settings.wmfVersion
settings.configuration.url	settings.ModulesUrl
settings.configuration.script	Первая часть свойства settings.ConfigurationFunction (before \\)
settings.configuration.function	Вторая часть свойства settings.ConfigurationFunction (after \\)
settings.configuration.module.name	settings.ModuleSource
settings.configuration.module.version	settings.ModuleVersion
settings.configurationArguments	settings.Properties
settings.configurationData.url	protectedSettings.DataBlobUri (без маркера SAS)
settings.privacy.dataCollection	settings.Privacy.dataCollection
settings.advancedOptions.downloadMappings	settings.advancedOptions.downloadMappings
protectedSettings.configurationArguments	protectedSettings.Properties
protectedSettings.configurationUrlSasToken	settings.SasToken
protectedSettings.configurationDataUrlSasToken	Маркер SAS из свойства protectedSettings.DataBlobUri

Устранение неполадок

Ниже приведены некоторые общие ошибки и способы их устранения.

Недопустимые значения

"Privacy.dataCollection имеет значение "{0}". Единственные возможные значения это "Enable" и "Disable". "WmfVersion имеет значение "{0}". Возможные значения: … и "latest".

Проблема. Указано неразрешенное значение.

Решение. Замените недопустимое значение допустимым. Дополнительные сведения см. в таблице раздела Сведения.

Недопустимый URL-адрес.

"ConfigurationData.url имеет значение "{0}". Это недопустимый URL-адрес." "DataBlobUri имеет значение "{0}". Это недопустимый URL-адрес." "Configuration.url имеет значение "{0}". This is not a valid URL" (Значение свойства Configuration.url — "{0}". Это недопустимый URL-адрес).

Проблема. Указан недопустимый URL-адрес.

Решение. Проверьте все указанные URL-адреса. Убедитесь, что все URL-адреса разрешаются в допустимые расположения, к которым расширение может получить доступ на удаленном компьютере.

Недопустимый тип RegistrationKey

"Недопустимый тип параметра RegistrationKey типа PSCredential."

Проблема. Значение RegistrationKey в protectedSettings.configurationArguments не может быть предоставлено как любой тип, отличный от PSCredential.

Решение. Измените запись protectedSettings.configurationArguments для RegisterKey на тип PSCredential, используя следующий формат:

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

Недопустимый тип свойства ConfigurationArgument

"Недопустимый тип ConfigurationArgument: {0}"

Проблема. Невозможно разрешить свойство ConfigurationArguments в объект Hash table.

Решение. Задайте для свойства ConfigurationArguments тип Hash table. Следуйте формату из приведенного выше примеров. Обращайте внимание на кавычки, запятые и скобки.

Повторяющееся свойство ConfigurationArguments

"В общедоступном и защищенном свойстве configurationArguments найден повторяющийся аргумент "{0}"

Проблема. Свойства ConfigurationArguments из общедоступной схемы settings и ConfigurationArguments из защищенной схемы settings имеют свойства с одинаковыми именами.

Решение. Удалите одно из повторяющихся свойств.

Отсутствующие свойства

"settings.сonfiguration.function requires that configuration.url or settings.configuration.module is specified" (Для параметра settings.configuration.function требуется указать свойство settings.configuration.url или configuration.module)

"settings.сonfiguration.url requires that settings.сonfiguration.script is specified" (Для параметра settings.сonfiguration.url требуется указать свойство settings.сonfiguration.script)

"settings.сonfiguration.script requires that settings.сonfiguration.url is specified" (Для параметра settings.сonfiguration.script требуется указать свойство settings.сonfiguration.url)

"settings.сonfiguration.url requires that settings.сonfiguration.function is specified" (Для параметра settings.сonfiguration.function требуется указать свойство settings.сonfiguration.url)

"protectedSettings.ConfigurationUrlSasToken.url requires that settings.сonfiguration.function is specified" (Для параметра protectedSettings.ConfigurationUrlSasToken.url требуется указать свойство settings.сonfiguration.url)

"protectedSettings.ConfigurationDataUrlSasToken.url requires that settings.сonfiguration.function is specified" (Для параметра protectedSettings.ConfigurationDataUrlSasToken.url требуется указать свойство settings.сonfiguration.url)

Проблема. Для заданного свойства требуется другое свойство, которое отсутствует.

Решения:

Укажите отсутствующее свойство.
Удалите свойство, требующее отсутствующего свойства.

Следующие шаги

Узнайте больше об использовании наборов масштабирования виртуальных машин с помощью расширения Azure DSC.
Получите дополнительные сведения о безопасном управлении учетными данными посредством DSC.
Ознакомьтесь с общими сведениями об обработчике расширения Desired State Configuration в Azure.
Дополнительные сведения о PowerShell DSC см. в центре документации по PowerShell.

Поделиться через