Allow the owner of the Azure Virtual Machines to configure the VM using Desired State Configuration (DSC) for Linux.
Latest version is 2.71
About how to create MOF document, please refer to below documents.
- Get started with Desired State Configuration (DSC) for Linux
- Built-In Desired State Configuration Resources for Linux
- [DSC for Linux releases] (https://github.com/Microsoft/PowerShell-DSC-for-Linux/releases)
DSCForLinux Extension can:
- Register the Linux VM to Azure Automation account in order to pull configurations from Azure Automation service (Register ExtensionAction)
- Push MOF configurations to the Linux VM (Push ExtensionAction)
- Applies Meta MOF configuration to the Linux VM to configure Pull Server in order to pull Node Configuration (Pull ExtensionAction)
- Install custom DSC modules to the Linux VM (Install ExtensionAction)
- Remove custom DSC modules to the Linux VM (Remove ExtensionAction)
Here're all the supported public configuration parameters:
FileUri
: (optional, string) the uri of the MOF file/Meta MOF file/custom resource ZIP file.ResourceName
: (optional, string) the name of the custom resource moduleExtensionAction
: (optional, string) Specifies what an extension does. valid values: Register, Push, Pull, Install, Remove. If not specified, it's considered as Push Action by default.NodeConfigurationName
: (optional, string) the name of a node configuration to apply.RefreshFrequencyMins
: (optional, int) Specifies how often (in minutes) 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 is copied to the pending store and applied.ConfigurationMode
: (optional, string) Specifies how DSC should apply the configuration. Valid values are: ApplyOnly, ApplyAndMonitor, ApplyAndAutoCorrect.ConfigurationModeFrequencyMins
: (optional, int) Specifies how often (in minutes) DSC ensures that the configuration is in the desired state.
NOTE: If you are using a version < 2.3, mode parameter is same as ExtensionAction. Mode seems to be a overloaded term. Therefore to avoid the confusion, ExtensionAction is being used from 2.3 version onwards. For backward compatibility, the extension supports both mode and ExtensionAction.
Here're all the supported protected configuration parameters:
StorageAccountName
: (optional, string) the name of the storage account that contains the fileStorageAccountKey
: (optional, string) the key of the storage account that contains the fileRegistrationUrl
: (optional, string) the URL of the Azure Automation accountRegistrationKey
: (optional, string) the access key of the Azure Automation account
You can deploy it using Azure CLI, Azure PowerShell and ARM template.
2.1. Using Azure CLI
Before deploying DSCForLinux Extension, you should configure your public.json
and protected.json
, according to the different scenarios in section 3.
The Classic mode is also called Azure Service Management mode. You can switch to it by running:
$ azure config mode asm
You can deploy 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
You can switch to Azure Resource Manager mode by running:
$ azure config mode arm
You can deploy 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
NOTE: In ARM mode,
azure vm extension list
is not available for now.
2.2. Using Azure PowerShell
You can login to your Azure account (Azure Service Management mode) by running:
Add-AzureAccount
And deploy DSCForLinux Extension by running:
$vmname = '<vm-name>'
$vm = Get-AzureVM -ServiceName $vmname -Name $vmname
$extensionName = 'DSCForLinux'
$publisher = 'Microsoft.OSTCExtensions'
$version = '<version>'
# You need to change the content of the $privateConfig and $publicConfig
# according to different scenarios in section 3
$privateConfig = '{
"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
You can login to your Azure account (Azure Resource Manager mode) by running:
Login-AzureRmAccount
Click HERE to learn more about how to use Azure PowerShell with Azure Resource Manager.
You can deploy DSCForLinux Extension by running:
$rgName = '<resource-group-name>'
$vmName = '<vm-name>'
$location = '<location>'
$extensionName = 'DSCForLinux'
$publisher = 'Microsoft.OSTCExtensions'
$version = '<version>'
# You need to change the content of the $privateConfig and $publicConfig
# according to different scenarios in section 3
$privateConfig = '{
"StorageAccountName": "<storage-account-name>",
"StorageAccountKey": "<storage-account-key>"
}'
$publicConfig = '{
"ExtensionAction": "Push",
"FileUri": "<mof-file-uri>"
}'
Set-AzureRmVMExtension -ResourceGroupName $rgName -VMName $vmName -Location $location `
-Name $extensionName -Publisher $publisher -ExtensionType $extensionName `
-TypeHandlerVersion $version -SettingString $publicConfig -ProtectedSettingString $privateConfig
2.3. Using ARM Template
The sample ARM template is 201-dsc-linux-azure-storage-on-ubuntu and 201-dsc-linux-public-storage-on-ubuntu.
For more details about ARM template, please visit Authoring Azure Resource Manager templates.
protected.json
{
"RegistrationUrl": "<azure-automation-account-url>",
"RegistrationKey": "<azure-automation-account-key>"
}
public.json
{
"ExtensionAction" : "Register",
"NodeConfigurationName" : "<node-configuration-name>",
"RefreshFrequencyMins" : "<value>",
"ConfigurationMode" : "<ApplyAndMonitor | ApplyAndAutoCorrect | ApplyOnly>",
"ConfigurationModeFrequencyMins" : "<value>"
}
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>"
}'
protected.json
{
"StorageAccountName": "<storage-account-name>",
"StorageAccountKey": "<storage-account-key>"
}
public.json
{
"FileUri": "<mof-file-uri>",
"ExtensionAction": "Push"
}
powershell format
$privateConfig = '{
"StorageAccountName": "<storage-account-name>",
"StorageAccountKey": "<storage-account-key>"
}'
$publicConfig = '{
"FileUri": "<mof-file-uri>",
"ExtensionAction": "Push"
}'
public.json
{
"FileUri": "<mof-file-uri>"
}
powershell format
$publicConfig = '{
"FileUri": "<mof-file-uri>"
}'
protected.json
{
"StorageAccountName": "<storage-account-name>",
"StorageAccountKey": "<storage-account-key>"
}
public.json
{
"ExtensionAction": "Pull",
"FileUri": "<meta-mof-file-uri>"
}
powershell format
$privateConfig = '{
"StorageAccountName": "<storage-account-name>",
"StorageAccountKey": "<storage-account-key>"
}'
$publicConfig = '{
"ExtensionAction": "Pull",
"FileUri": "<meta-mof-file-uri>"
}'
public.json
{
"FileUri": "<meta-mof-file-uri>",
"ExtensionAction": "Pull"
}
powershell format
$publicConfig = '{
"FileUri": "<meta-mof-file-uri>",
"ExtensionAction": "Pull"
}'
protected.json
{
"StorageAccountName": "<storage-account-name>",
"StorageAccountKey": "<storage-account-key>"
}
public.json
{
"ExtensionAction": "Install",
"FileUri": "<resource-zip-file-uri>"
}
powershell format
$privateConfig = '{
"StorageAccountName": "<storage-account-name>",
"StorageAccountKey": "<storage-account-key>"
}'
$publicConfig = '{
"ExtensionAction": "Install",
"FileUri": "<resource-zip-file-uri>"
}'
public.json
{
"ExtensionAction": "Install",
"FileUri": "<resource-zip-file-uri>"
}
powershell format
$publicConfig = '{
"ExtensionAction": "Install",
"FileUri": "<resource-zip-file-uri>"
}'
public.json
{
"ResourceName": "<resource-name>",
"ExtensionAction": "Remove"
}
powershell format
$publicConfig = '{
"ResourceName": "<resource-name>",
"ExtensionAction": "Remove"
}'
- Ubuntu 14.04 LTS, 16.04 LTS, 18.04 LTS and 20.04 LTS
- Debian 8, 9 and 10
- Oracle Linux 6 and 7
- CentOS 6, 7 and 8
- RHEL 6, 7 and 8
- SUSE Linux Enterprise Server 12 and 15
- The status of the extension is reported back to Azure so that user can see the status on Azure Portal
- The operation log of the extension is
/var/log/azure/<extension-name>/<version>/extension.log
file.
- To distribute MOF configurations to the Linux VM with Pull Servers, you need to make sure the cron service is running in the VM.
# 2.5 (2017-05-25)
- Added support Oracle Distros
# 2.4 (2017-05-14)
- Added more logging
# 2.3 (2017-05-08)
- Update to OMI v1.1.0-8 and Linux DSC v1.1.1-294
- Added optional public.json parmeters: 'NodeConfigurationName', 'RefreshFrequencyMins', 'ConfigurationMode' and 'ConfigurationModeFrequencyMins'.
- Added a new parameter 'ExtensionAction' to replace 'mode' to avoid confusion with DSC terminology: push/pull mode.
- Supports mode parameter for backward compatibility.
# 2.0 (2016-03-10)
- Pick up Linux DSC v1.1.1
- Add function to register Azure Automation
- Refine extension configurations
# 1.0 (2015-09-24)
- Initial version