适用于 Linux 的 DSC 扩展 (Microsoft.OSTCExtensions.DSCForLinux)DSC extension for Linux (Microsoft.OSTCExtensions.DSCForLinux)

Desired State Configuration (DSC) 是一个管理平台,可让你使用“配置即代码”来管理 IT 和开发基础结构。Desired State Configuration (DSC) is a management platform that you can use to manage your IT and development infrastructure with configuration as code.

备注

适用于 Linux 的 DSC 扩展和适用于 Linux 的 Azure Monitor 虚拟机扩展当前存在冲突,并在并列配置中不受支持。The DSC extension for Linux and the Azure Monitor virtual machine extension for Linux currently present a conflict and aren't supported in a side-by-side configuration. 不要在同一 VM 上同时使用这两个解决方案。Don't use the two solutions together on the same VM.

DSCForLinux 扩展由 Azure 发布并提供支持。The DSCForLinux extension is published and supported by Azure. 该扩展在 Azure 虚拟机上安装 OMI 和 DSC 代理。The extension installs the OMI and DSC agent on Azure virtual machines. DSC 扩展还能执行以下操作:The DSC extension can also do the following actions:

  • 将 Linux VM 注册到 Azure 自动化帐户,以便从 Azure 自动化服务提取配置 (Register ExtensionAction)Register the Linux VM to an Azure Automation account to pull configurations from the Azure Automation service (Register ExtensionAction).
  • 将 MOF 配置推送到 Linux VM (Push ExtensionAction)。Push MOF configurations to the Linux VM (Push ExtensionAction).
  • 将元 MOF 配置应用到 Linux VM,以配置提取服务器来提取节点配置 (Pull ExtensionAction)。Apply meta MOF configuration to the Linux VM to configure a pull server in order to pull node configuration (Pull ExtensionAction).
  • 将自定义的 DSC 模块安装到 Linux VM (Install ExtensionAction)。Install custom DSC modules to the Linux VM (Install ExtensionAction).
  • 从 Linux VM 中删除自定义的 DSC 模块 (Remove ExtensionAction)。Remove custom DSC modules from the Linux VM (Remove ExtensionAction).

先决条件Prerequisites

操作系统Operating system

对于运行 Linux 的节点,DSC Linux 扩展支持 PowerShell DSC 文档中列出的所有 Linux 发行版。For nodes running Linux, the DSC Linux extension supports all the Linux distributions listed in the PowerShell DSC documentation.

Internet 连接Internet connectivity

DSCForLinux 扩展要求目标虚拟机已连接到 Internet。The DSCForLinux extension requires the target virtual machine to be connected to the internet. 例如,Register 扩展要求连接到自动化服务。For example, the Register extension requires connectivity to the Automation service. 对于其他操作(例如 Pull),Install 扩展要求连接到 Azure 存储和 GitHub。For other actions such as Pull, Install requires connectivity to Azure Storage and GitHub. 它依赖于客户提供的设置。It depends on settings provided by the customer.

扩展架构Extension schema

公共配置Public configuration

下面是所有支持的公共配置参数:Here are all the supported public configuration parameters:

  • FileUri:(可选,字符串)MOF 文件、元 MOF 文件或自定义资源 zip 文件的 URI。FileUri: (optional, string) The uri of the MOF file, meta MOF file, or custom resource zip file.
  • ResourceName:(可选,字符串)自定义资源模块的名称。ResourceName: (optional, string) The name of the custom resource module.
  • ExtensionAction:(可选,字符串)指定扩展的功能。ExtensionAction: (optional, string) Specifies what an extension does. 有效值为 Register、Push、Pull、Install 和 Remove。Valid values are Register, Push, Pull, Install, and Remove. 如果未指定,则默认将值视为推送操作。If not specified, it's considered a Push Action by default.
  • NodeConfigurationName:(可选,字符串)要应用的节点配置的名称。NodeConfigurationName: (optional, string) The name of a node configuration to apply.
  • RefreshFrequencyMins:(可选,整数)指定 DSC 尝试从提取服务器获取配置的频率(以分钟为单位)。RefreshFrequencyMins: (optional, int) Specifies how often (in minutes) that DSC attempts to obtain the configuration from the pull server. 如果提取服务器上的配置不同于目标节点上的当前配置,则会将前者复制到挂起的存储并应用。If configuration on the pull server differs from the current one on the target node, it's copied to the pending store and applied.
  • ConfigurationMode:(可选,字符串)指定 DSC 如何应用配置。ConfigurationMode: (optional, string) Specifies how DSC should apply the configuration. 有效值为 ApplyOnly、ApplyAndMonitor 和 ApplyAndAutoCorrect。Valid values are ApplyOnly, ApplyAndMonitor, and ApplyAndAutoCorrect.
  • ConfigurationModeFrequencyMins:(可选,整数)指定 DSC 确保配置处于所需状态的频率(以分钟为单位)。ConfigurationModeFrequencyMins: (optional, int) Specifies how often (in minutes) DSC ensures that the configuration is in the desired state.

备注

如果使用的版本低于 2.3,则 mode 参数与 ExtensionAction 相同。If you use a version earlier than 2.3, the mode parameter is the same as ExtensionAction. Mode(模式)看上去像是一个重载的术语。Mode seems to be an overloaded term. 为了避免混淆,从版本 2.3 开始使用了 ExtensionAction。To avoid confusion, ExtensionAction is used from version 2.3 onward. 为了向后兼容,扩展支持 mode 和 ExtensionAction。For backward compatibility, the extension supports both mode and ExtensionAction.

受保护的配置Protected configuration

下面是所有支持的受保护配置参数:Here are all the supported protected configuration parameters:

  • StorageAccountName:(可选,字符串)包含文件的存储帐户的名称StorageAccountName: (optional, string) The name of the storage account that contains the file
  • StorageAccountKey:(可选,字符串)包含文件的存储帐户的密钥StorageAccountKey: (optional, string) The key of the storage account that contains the file
  • RegistrationUrl:(可选,字符串)Azure 自动化帐户的 URLRegistrationUrl: (optional, string) The URL of the Azure Automation account
  • RegistrationKey:(可选,字符串)Azure 自动化帐户的访问密钥RegistrationKey: (optional, string) The access key of the Azure Automation account

方案Scenarios

注册 Azure 自动化帐户Register an Azure Automation account

protected.jsonprotected.json

{
  "RegistrationUrl": "<azure-automation-account-url>",
  "RegistrationKey": "<azure-automation-account-key>"
}

public.jsonpublic.json

{
  "ExtensionAction" : "Register",
  "NodeConfigurationName" : "<node-configuration-name>",
  "RefreshFrequencyMins" : "<value>",
  "ConfigurationMode" : "<ApplyAndMonitor | ApplyAndAutoCorrect | ApplyOnly>",
  "ConfigurationModeFrequencyMins" : "<value>"
}

PowerShell 格式PowerShell format

$privateConfig = '{
  "RegistrationUrl": "<azure-automation-account-url>",
  "RegistrationKey": "<azure-automation-account-key>"
}'

$publicConfig = '{
  "ExtensionAction" : "Register",
  "NodeConfigurationName": "<node-configuration-name>",
  "RefreshFrequencyMins": "<value>",
  "ConfigurationMode": "<ApplyAndMonitor | ApplyAndAutoCorrect | ApplyOnly>",
  "ConfigurationModeFrequencyMins": "<value>"
}'

将 MOF 配置文件(在 Azure 存储帐户中)应用到 VMApply an MOF configuration file (in an Azure storage account) to the VM

protected.jsonprotected.json

{
  "storageAccountEndPoint": "https://core.chinacloudapi.cn/",
  "StorageAccountName": "<storage-account-name>",
  "StorageAccountKey": "<storage-account-key>"
}

public.jsonpublic.json

{
  "FileUri": "<mof-file-uri>",
  "ExtensionAction": "Push"
}

PowerShell 格式PowerShell format

$privateConfig = '{
  "storageAccountEndPoint": "https://core.chinacloudapi.cn/",
  "StorageAccountName": "<storage-account-name>",
  "StorageAccountKey": "<storage-account-key>"
}'

$publicConfig = '{
  "FileUri": "<mof-file-uri>",
  "ExtensionAction": "Push"
}'

将 MOF 配置文件(在公共存储中)应用到 VMApply an MOF configuration file (in public storage) to the VM

public.jsonpublic.json

{
  "FileUri": "<mof-file-uri>"
}

PowerShell 格式PowerShell format

$publicConfig = '{
  "FileUri": "<mof-file-uri>"
}'

将元 MOF 配置文件(在 Azure 存储帐户中)应用到 VMApply a meta MOF configuration file (in an Azure storage account) to the VM

protected.jsonprotected.json

{
  "storageAccountEndPoint": "https://core.chinacloudapi.cn/",
  "StorageAccountName": "<storage-account-name>",
  "StorageAccountKey": "<storage-account-key>"
}

public.jsonpublic.json

{
  "ExtensionAction": "Pull",
  "FileUri": "<meta-mof-file-uri>"
}

PowerShell 格式PowerShell format

$privateConfig = '{
  "storageAccountEndPoint": "https://core.chinacloudapi.cn/",
  "StorageAccountName": "<storage-account-name>",
  "StorageAccountKey": "<storage-account-key>"
}'

$publicConfig = '{
  "ExtensionAction": "Pull",
  "FileUri": "<meta-mof-file-uri>"
}'

将元 MOF 配置文件(在公共存储中)应用到 VMApply a meta MOF configuration file (in public storage) to the VM

public.jsonpublic.json

{
  "FileUri": "<meta-mof-file-uri>",
  "ExtensionAction": "Pull"
}

PowerShell 格式PowerShell format

$publicConfig = '{
  "FileUri": "<meta-mof-file-uri>",
  "ExtensionAction": "Pull"
}'

将自定义资源模块(Azure 存储帐户中的 zip 文件)安装到 VMInstall a custom resource module (a zip file in an Azure storage account) to the VM

protected.jsonprotected.json

{
  "storageAccountEndPoint": "https://core.chinacloudapi.cn/",
  "StorageAccountName": "<storage-account-name>",
  "StorageAccountKey": "<storage-account-key>"
}

public.jsonpublic.json

{
  "ExtensionAction": "Install",
  "FileUri": "<resource-zip-file-uri>"
}

PowerShell 格式PowerShell format

$privateConfig = '{
  "storageAccountEndPoint": "https://core.chinacloudapi.cn/",
  "StorageAccountName": "<storage-account-name>",
  "StorageAccountKey": "<storage-account-key>"
}'

$publicConfig = '{
  "ExtensionAction": "Install",
  "FileUri": "<resource-zip-file-uri>"
}'

将自定义资源模块(公共存储中的 zip 文件)安装到 VMInstall a custom resource module (a zip file in public storage) to the VM

public.jsonpublic.json

{
  "ExtensionAction": "Install",
  "FileUri": "<resource-zip-file-uri>"
}

PowerShell 格式PowerShell format

$publicConfig = '{
  "ExtensionAction": "Install",
  "FileUri": "<resource-zip-file-uri>"
}'

从 VM 中删除自定义资源模块Remove a custom resource module from the VM

public.jsonpublic.json

{
  "ResourceName": "<resource-name>",
  "ExtensionAction": "Remove"
}

PowerShell 格式PowerShell format

$publicConfig = '{
  "ResourceName": "<resource-name>",
  "ExtensionAction": "Remove"
}'

模板部署Template deployment

可使用 Azure Resource Manager 模板部署 Azure VM 扩展。Azure VM extensions can be deployed with Azure Resource Manager templates. 部署需要部署后配置(例如,载入 Azure 自动化)的一个或多个虚拟机时,模板是理想选择。Templates are ideal when you deploy one or more virtual machines that require post-deployment configuration, such as onboarding to Azure Automation.

201-dsc-linux-azure-storage-on-ubuntu201-dsc-linux-public-storage-on-ubuntu 是示例资源管理器模板。The sample Resource Manager template is 201-dsc-linux-azure-storage-on-ubuntu and 201-dsc-linux-public-storage-on-ubuntu.

有关 Azure 资源管理器模板的详细信息,请参阅创作 Azure 资源管理器模板For more information about the Azure Resource Manager template, see Authoring Azure Resource Manager templates.

Azure CLI 部署Azure CLI deployment

使用 [Azure CLI][azure-cli]Use [Azure CLI][azure-cli]

在部署 DSCForLinux 扩展之前,请根据第 3 部分中所述的不同方案配置 public.jsonprotected.jsonBefore you deploy the DSCForLinux extension, configure your public.json and protected.json according to the different scenarios in section 3.

经典Classic

重要

经典 VM 将于 2023 年 3 月 1 日停用。Classic VMs will be retired on March 1, 2023.

如果从 ASM 使用 IaaS 资源,请在 2023 年 3 月 1 日之前完成迁移。If you use IaaS resources from ASM, please complete your migration by March 1, 2023. 我们建议你尽快进行切换,以利用 Azure 资源管理器中的许多增强功能。We encourage you to make the switch sooner to take advantage of the many feature enhancements in Azure Resource Manager.

有关详细信息,请参阅在 2023 年 3 月 1 日之前将 IaaS 资源迁移到 Azure 资源管理器For more information, see Migrate your IaaS resources to Azure Resource Manager by March 1, 2023.

经典部署模式也称为 Azure 服务管理模式。The classic deployment mode is also called Azure Service Management mode. 可运行以下命令切换到该模式:You can switch to it by running:

$ azure config mode asm

可运行以下命令部署 DSCForLinux 扩展:You can deploy the DSCForLinux extension by running:

$ azure vm extension set <vm-name> DSCForLinux Microsoft.OSTCExtensions <version> \
--private-config-path protected.json --public-config-path public.json

若要了解最新可用的扩展版本,请运行:To learn the latest extension version available, run:

$ azure vm extension list

Resource ManagerResource Manager

可运行以下命令切换到 Azure 资源管理器模式:You can switch to Azure Resource Manager mode by running:

$ azure config mode arm

可运行以下命令部署 DSCForLinux 扩展:You can deploy the DSCForLinux extension by running:

$ azure vm extension set <resource-group> <vm-name> \
DSCForLinux Microsoft.OSTCExtensions <version> \
--private-config-path protected.json --public-config-path public.json

备注

在 Azure 资源管理器模式下,azure vm extension list 目前不可用。In Azure Resource Manager mode, azure vm extension list isn't available for now.

使用 [Azure PowerShell][azure-powershell]Use [Azure PowerShell][azure-powershell]

经典Classic

可运行以下命令在 Azure 服务管理模式下登录到 Azure 帐户:You can sign in to your Azure account in Azure Service Management mode by running:

Add-AzureAccount -Environment AzureChinaCloud

运行以下命令部署 DSCForLinux 扩展:And deploy the DSCForLinux extension by running:

$vmname = '<vm-name>'
$vm = Get-AzureVM -ServiceName $vmname -Name $vmname
$extensionName = 'DSCForLinux'
$publisher = 'Microsoft.OSTCExtensions'
$version = '< version>'

根据上面部分所述的不同方案更改 $privateConfig 和 $publicConfig 的内容。Change the content of $privateConfig and $publicConfig according to different scenarios in the previous section.

$privateConfig = '{
  "storageAccountEndPoint": "https://core.chinacloudapi.cn/",
  "StorageAccountName": "<storage-account-name>",
  "StorageAccountKey": "<storage-account-key>"
}'
$publicConfig = '{
  "ExtensionAction": "Push",
  "FileUri": "<mof-file-uri>"
}'
Set-AzureVMExtension -ExtensionName $extensionName -VM $vm -Publisher $publisher `
  -Version $version -PrivateConfiguration $privateConfig `
  -PublicConfiguration $publicConfig | Update-AzureVM

Resource ManagerResource Manager

可运行以下命令在 Azure 资源管理器模式下登录到 Azure 帐户:You can sign in to your Azure account in Azure Resource Manager mode by running:

Connect-AzAccount -Environment AzureChinaCloud

若要详细了解如何将 Azure PowerShell 与 Azure 资源管理器配合使用,请参阅使用 Azure PowerShell 管理 Azure 资源To learn more about how to use Azure PowerShell with Azure Resource Manager, see Manage Azure resources by using Azure PowerShell.

可运行以下命令部署 DSCForLinux 扩展:You can deploy the DSCForLinux extension by running:

$rgName = '<resource-group-name>'
$vmName = '<vm-name>'
$location = '< location>'
$extensionName = 'DSCForLinux'
$publisher = 'Microsoft.OSTCExtensions'
$version = '< version>'

根据上面部分所述的不同方案更改 $privateConfig 和 $publicConfig 的内容。Change the content of $privateConfig and $publicConfig according to different scenarios in the previous section.

$privateConfig = '{
  "storageAccountEndPoint": "https://core.chinacloudapi.cn/",
  "StorageAccountName": "<storage-account-name>",
  "StorageAccountKey": "<storage-account-key>"
}'
$publicConfig = '{
  "ExtensionAction": "Push",
  "FileUri": "<mof-file-uri>"
}'
Set-AzVMExtension -ResourceGroupName $rgName -VMName $vmName -Location $location `
  -Name $extensionName -Publisher $publisher -ExtensionType $extensionName `
  -TypeHandlerVersion $version -SettingString $publicConfig -ProtectedSettingString $privateConfig

故障排除和支持Troubleshoot and support

疑难解答Troubleshoot

有关扩展部署状态的数据可以从 Azure 门户和使用 Azure CLI 进行检索。Data about the state of extension deployments can be retrieved from the Azure portal and by using the Azure CLI. 若要查看给定 VM 的扩展部署状态,请使用 Azure CLI 运行以下命令。To see the deployment state of extensions for a given VM, run the following command by using the Azure CLI.

az vm extension list --resource-group myResourceGroup --vm-name myVM -o table

扩展执行输出将记录到以下文件:Extension execution output is logged to the following file:

/var/log/azure/<extension-name>/<version>/extension.log file.

错误代码:51 表示分发或扩展操作不受支持。Error code: 51 represents either unsupported distribution or unsupported extension action. 在某些情况下,如果计算机中存在较高版本的 OMI,则 DSC Linux 扩展无法安装 OMI。In some cases, DSC Linux extension fails to install OMI when a higher version of OMI already exists in the machine. [错误响应: (000003)不允许降级][error response: (000003)Downgrade not allowed]

支持Support

如果对本文中的任何观点存在疑问,请通过 Azure 支持联系 Azure 专家。If you need more help at any point in this article, contact the Azure experts on the Azure support. 或者,也可以提出 Azure 支持事件。Alternatively, you can file an Azure support incident. 请转到 Azure 支持站点提交请求。Go to the Azure support site and submit your request. 有关使用 Azure 支持的信息,请阅读 Azure 支持常见问题For information about using Azure Support, read the Azure support FAQ.

后续步骤Next steps

有关扩展的详细信息,请参阅适用于 Linux 的虚拟机扩展和功能For more information about extensions, see Virtual machine extensions and features for Linux.