In the previous post we added the DSC For Linux VM extension to Azure Stack and used it during deployments based from PowerShell and a JSON template. The VM extension however did not surface in the Portal which is something we will fix in this and the next blog post.
In this series:
Adding and using….
- CentOS 7.2 (or any other image) to Azure Stack TP2
- OS Gallery Items to Azure Stack TP2
- The DSC For Linux extension v2 to Azure Stack TP2
- DSC For Linux Gallery Item to Azure Stack TP2 (this post)
- DSC For Linux Azure Automation DSC Gallery Item to Azure Stack TP2
VM Extension Gallery Item
As with the OS disk, we need to create a Gallery item to make the VM extension surface in the Portal. TP2 shipped with only 2 Gallery Items for Linux VM Extension:
In Public Azure there is no exposure of the DSC For Linux VM Extension in the Portal so we have cart blanche for this and the next blog post.
We identified basically 2 generic use cases for the DSC For Linux VM extension we want to see in the Portal:
- Push (mof) / Pull (meta.mof) / Install (custom resources)
- Register
The other functionalities don’t make much sense for this blog series so I’m ignoring those a bit (sorry).
In this blog post, we’ll create a Gallery item to expose the DSC For Linux VM extension in regard to the first use case (Push/Pull/Install).
Don’t start from scratch
As with the OS Gallery Item, I did not start from scratch but instead first looked at the DSC For Windows VM Extension. You can find it here: C:\ClusterStorage\Volume1\Shares\SU1_TenantLibrary_1\GalleryImages\Microsoft.Compute\local\Microsoft.DSC-arm.2.0.7.azpkg
I won’t do a side by side comparison like last time but instead will discuss the end result.
Artifact structure
The artifact has the following structure and files:
We have a root folder and 3 sub folders (DeploymentTemplates, icons and strings).
Root level documents folder
At the root level we have 2 json files:
- Manifest.json
- UIDefinition.json
Manifest.json
Just as with the OS Gallery item manifest file, the Manifest.json in this case contains a description of the gallery item (e.g. the name, publisher, version, etc). Which artifacts are contained within the package and of what type they are, which icon files are located, etc.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 |
{ "$schema": "https://gallery.azure.com/schemas/2015-10-01/manifest.json#", "name": "DSCForLinux-arm", "publisher": "Microsoft", "version": "1.0.0", "displayName": "ms-resource:displayName", "publisherDisplayName": "ms-resource:publisherDisplayName", "publisherLegalName": "ms-resource:publisherLegalName", "summary": "ms-resource:summary", "longSummary": "ms-resource:longSummary", "description": "ms-resource:description", "uiDefinition": { "path": "UIDefinition.json" }, "metadata": [], "artifacts": [ { "name": "MainTemplate", "type": "Template", "path": "DeploymentTemplates\\MainTemplate.json", "isDefault": true }, { "name": "CreateUiDefinition", "type": "Custom", "path": "DeploymentTemplates\\CreateUiDefinition.json", "isDefault": false } ], "properties": [], "categories": [ "compute-vmextension-linux" ], "links": [ { "displayName": "ms-resource:linkDisplayName0", "uri": "https://github.com/Azure/azure-linux-extensions/tree/master/DSC" } ], "filters": [], "products": [], "images": [ { "context": "ibiza", "items": [ { "id": "small", "path": "icons\\Small.png", "type": "icon" }, { "id": "medium", "path": "icons\\Medium.png", "type": "icon" }, { "id": "large", "path": "icons\\Large.png", "type": "icon" }, { "id": "wide", "path": "icons\\Wide.png", "type": "icon" }, { "id": "screenshot1", "path": "icons\\screenshot1.png", "type": "screenshot" } ] } ] } |
I’ve added a link to the GitHub repository for more information which will be displayed at the overview page for the VM Extension.
The publisher name is actually taken from the strings\resources.resjon (described later).
UIDefinition.json
The UIDefinition.json controls which blade type is used in the portal. In this case, the AddVmExtension is used which corresponds to the blade type we need.
|
1 2 3 4 5 6 7 8 9 |
{ "$schema": "https://gallery.azure.com/schemas/2015-02-12/uiDefinition.json#", "createDefinition": { "createBlade": { "name": "AddVmExtension", "extension": "Microsoft_Azure_Compute" } } } |
DeploymentTemplates folder
The DeploymentTemplates folder contains two json files:
- CreateUiDefinition.json
- MainTemplate.json
CreateUiDefinition.json
CreateUiDefinition describes the way the Portal generates the user input fields as elements.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
{ "handler": "Microsoft.Compute.VmExtension", "version": "0.0.1-preview", "parameters": { "elements": [ { "name": "FileUri", "type": "Microsoft.Common.FileUpload", "label": "Configuration Modules or Compiled configurations", "toolTip": "URL for the DSC compiled configurations (MOF), meta configuration (meta.MOF) or Resources (ZIP)", "constraints": { "required": true, "accept": [".zip", ".mof"] }, "options": { "multiple": false, "uploadMode": "url", "openMode": "binary", "encoding": "UTF-8" } }, { "name": "Mode", "type": "Microsoft.Common.DropDown", "label": "LCM Mode", "toolTip": "Mode of Local Configuration Manager", "defaultValue": "Push", "constraints": { "allowedValues": [ { "label": "Push", "value": "Push" }, { "label": "Pull", "value": "Pull" }, { "label": "Install", "value": "Install" } ] } } ], "outputs": { "vmName": "[vmName()]", "location": "[location()]", "FileUri": "[elements('FileUri')]", "Mode": "[elements('Mode')]" } } } |
In this case I have defined 2elements:
- FileUri
- Mode
FileUri
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
"name": "FileUri", "type": "Microsoft.Common.FileUpload", "label": "Configuration Modules or Compiled configurations", "toolTip": "URL for the DSC compiled configurations (MOF), meta configuration (meta.MOF) or Resources (ZIP)", "constraints": { "required": true, "accept": [".zip", ".mof"] }, "options": { "multiple": false, "uploadMode": "url", "openMode": "binary", "encoding": "UTF-8" } |
FileUri is the most interesting part of this document as it tells you something on how Azure works when users are allowed to upload content as part of a deployment.
First look at the type “Microsoft.Common.FileUpload”, it instructs the portal to generate a “select a file” control box where the user can click on a folder icon, browse to a supported artifact and upload it (we’ll see where it is uploaded when we use the Extension Gallery Item).
You can also see the label being generated in the Ui.
The tooltip is displayed when the user clicks/hovers over the I icon.
The constrains will be passed to the user’s explorer Ui:
We define this control as being required as we need either a mof, meta.mof or zip file to continue with one of the supported modes (push, pull, install).
In the options some additional options like allowing only a single file upload and upload mode is specified as Url (this will create and send the blob Uri as output).
Mode
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
"name": "Mode", "type": "Microsoft.Common.DropDown", "label": "LCM Mode", "toolTip": "Mode of Local Configuration Manager", "defaultValue": "Push", "constraints": { "allowedValues": [ { "label": "Push", "value": "Push" }, { "label": "Pull", "value": "Pull" }, { "label": "Install", "value": "Install" } ] } |
The type of the “Mode” element is “Microsoft.Common.DropDown”. It instructs the portal to generate a dropdown list.
The label and tooltip are generated the same as the previous control. The default value is set to “Push”. The allowed values are specified as a constraint. Push, Pull and Install are allowed values.
Outputs
At the end of the CreateUiDefinition.json, outputs are specified. These outputs are used to send as values for the parameters of MainTemplate.json which is used by the Portal to add the VM Extension to an already deployed VM or merge into the overall JSON generated for a VM from scratch deployment.
|
1 2 3 4 5 6 |
"outputs": { "vmName": "[vmName()]", "location": "[location()]", "FileUri": "[elements('FileUri')]", "Mode": "[elements('Mode')]" } |
MainTemplate.json
MainTemplate is basically a JSON template you would create yourself to add the DSC For Linux VM Extension to an already deployed VM.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 |
{ "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json", "contentVersion": "1.0.0.0", "parameters": { "vmName": { "type": "string" }, "location": { "type": "string" }, "FileUri": { "type": "string" }, "Mode": { "type": "string", "defaultValue": "Push", "allowedValues": [ "Push", "Pull", "Install" ] } }, "resources": [ { "name": "[concat(parameters('vmName'),'/Microsoft.OSTCExtensions.DSCForLinux')]", "type": "Microsoft.Compute/virtualMachines/extensions", "location": "[parameters('location')]", "apiVersion": "2015-06-15", "properties": { "publisher": "Microsoft.OSTCExtensions", "type": "DSCForLinux", "typeHandlerVersion": "2.0", "autoUpgradeMinorVersion": false, "settings": { "FileUri": "[parameters('FileUri')]", "Mode": "[parameters('Mode')]" }, "protectedSettings": { } } } ] } |
I created parameters which correspond with the outputs from the CreateUiDefinition.json and mapped those to the resource properties where applicable. As you can see this template only has the public settings FileUri and Mode specified, no other operational tasks will be supported by this Ui.
Icons
I took the liberty of creating some nice looking graphics for this extension :-). The screenshot image is required for VM Extensions, if you don’t add one, the Gallery Packager will bark at you.
| Large.png | 115 x 115 px |  |
| Medium.png | 90 x 90 px |  |
| Small.png | 40 x 40 px |  |
| Wide.png | 255 x 115 px |  |
| Screenshot1.png | 533 x 324 px |  |
Strings
The strings from strings\resources.resjson are used by the manifest file.
|
1 2 3 4 5 6 7 8 9 |
{ "displayName": "Desired State Configuration for Linux", "publisherDisplayName": "Ben Gelens.", "publisherLegalName": "Ben Gelens.", "summary": "Desired State Configuration for Linux", "longSummary": "Desired State Configuration for Linux", "description": "<p>DSC is a management platform that enables deploying and managing configuration data for software services and managing the environment in which these services run.</p>", "linkDisplayName0": "Learn more about DSC for Linux" } |
Packaging Gallery Item
If you haven’t done so in the previous blog posts, Download the Azure Gallery Packager and extract it somewhere you can find it. Let’s move the folder containing the files to the root of C. Now open a command prompt or PowerShell console and navigate to the packager and run: .\AzureGalleryPackageGenerator\AzureGalleryPackager.exe -m C:\Microsoft.OSTCExtensions.DSCForLinux-arm.1.0.0\Manifest.json -o C:\MyMarketPlaceItems
You should now have a marketplace item in azpkg format. If the packager did not work out, you probably have made some sort of typo somewhere or it just doesn’t like the paths you provide. In any case, you can download the azpkg I created here.
Adding the Gallery Item to Azure Stack
We are going to use the same storage account again from the first blog post, if you did not create it, please go back to that one and create it.
Run the following script to add the azpkg to Azure Stack (I assume you already setup the Azure Stack connection in PowerShell).
|
1 2 3 4 5 |
$subscriptionid = (Get-AzureRmSubscription -SubscriptionName 'Default Provider Subscription').SubscriptionId $StorageAccount = Get-AzureRmStorageAccount -ResourceGroupName tenantartifacts -Name tenantartifacts $GalleryContainer = Get-AzureStorageContainer -Name gallery -Context $StorageAccount.Context $DSCazpkg = $GalleryContainer | Set-AzureStorageBlobContent -File C:\MyMarketPlaceItems\Microsoft.DSCForLinux-arm.1.0.0.azpkg Add-AzureRMGalleryItem -SubscriptionId $subscriptionid -GalleryItemUri $DSCazpkg.ICloudBlob.StorageUri.PrimaryUri.AbsoluteUri -Apiversion "2015-04-01" |
You should see a message with StatusCode Ok.
Now we login to the portal, wait a bit, refresh a couple of times and eventually we get:
If it does not show here, see if it is listed under More.
Note, if you made an error somewhere (wrong text or something) and want to re-add the Gallery item. You should remove it first.
|
1 |
Remove-AzureRMGalleryItem -Name 'Microsoft.DSCForLinux-arm.1.0.0' -ApiVersion 2015-04-01 |
Using the Gallery Item
Now we made the Gallery Item available, let’s put it to work. We use the same mof file as in the previous blog (if you don’t have it, please compile it according the instructions there).
Let’s start to create a new VM based on our CentOS 7.2 Gallery Item.
At step 3 select the Extensions blade and then Add Extension.
Now we should see the DSC For Linux VM Extension Gallery Item.
Select it and hit create.
We can now see the fields we made available. Let’s provide it with the mof file.
The localhost.mof file has been uploaded to a generic storage account used by the Portal called “tenantextaccount”. You can find the blob using this code:
|
1 2 3 |
Get-AzureRmStorageAccount |?{$_.StorageAccountName -eq 'tenantextaccount'} | Get-AzureStorageContainer | Sort-Object -Property LastModified -Descending | Select-Object -First 1 | Get-AzureStorageBlob |
The blob is stored in a non-public container. Once uploaded a Uri including a SAS token appended to it will be returned and passed to the maintemplate by the output element described earlier in this blog. In effect, only the user which uploaded the file would have access to it because, he or she is the only one with a valid Uri including a sas token.
Now we have the extension configured, proceed as normal and deploy the VM. Once finished we should see the following in the VM Extension blade:
In the next blog we will repeat the steps from this post but target the register mode instead.