Adding and using DSC For Linux Gallery Item to Azure Stack TP2

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….

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:

bg_as_04crpaddon_01

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:

bg_as_04crpaddon_02

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.

I’ve added a link to the GitHub repository for more information which will be displayed at the overview page for the VM Extension.

bg_as_04crpaddon_03

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.

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.

In this case I have defined 2elements:

  • FileUri
  • Mode
FileUri

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).

bg_as_04crpaddon_04

You can also see the label being generated in the Ui.

The tooltip is displayed when the user clicks/hovers over the I icon.

bg_as_04crpaddon_05

The constrains will be passed to the user’s explorer Ui:

bg_as_04crpaddon_06

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

The type of the “Mode” element is “Microsoft.Common.DropDown”. It instructs the portal to generate a dropdown list.

bg_as_04crpaddon_07

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.

bg_as_04crpaddon_08

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.

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.

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  bg_as_04crpaddon_09
Medium.png 90 x 90 px  bg_as_04crpaddon_10
Small.png 40 x 40 px  bg_as_04crpaddon_11
Wide.png 255 x 115 px  bg_as_04crpaddon_12
Screenshot1.png 533 x 324 px  bg_as_04crpaddon_13

Strings

The strings from strings\resources.resjson are used by the manifest file.

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).

You should see a message with StatusCode Ok.

bg_as_04crpaddon_14

Now we login to the portal, wait a bit, refresh a couple of times and eventually we get:

bg_as_04crpaddon_15

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.

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.

bg_as_04crpaddon_16

Now we should see the DSC For Linux VM Extension Gallery Item.

bg_as_04crpaddon_17

Select it and hit create.

bg_as_04crpaddon_18

We can now see the fields we made available. Let’s provide it with the mof file.

bg_as_04crpaddon_19

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:

bg_as_04crpaddon_20

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:

bg_as_04crpaddon_21

In the next blog we will repeat the steps from this post but target the register mode instead.

Spread the word. Share this post!

Ben Gelens

About the author

Ben Gelens is a PowerShell MVP and technical consultant at Inovativ in the Netherlands where he works as a member of the CloudOS team. While building clouds for his customers, Ben’s primary focus is automation and orchestration. As such, Ben has a great deal of field experience on all kinds of PowerShell subjects (e.g. Remoting, Tool making, DSC, SMA, Workflow) in all kinds of areas (e.g. Windows Azure Pack, Active Directory, Office 365, Server Management, Azure). Ben is an active IT community participant and speaker. He is a member of the Hyper-V.nu community, a member of the Dutch PowerShell User Group and a contributing author for PowerShell magazine.

Contact:
Email: ben@bgelens.nl
Twitter: @bgelens
LinkedIn: https://nl.linkedin.com/in/ben-gelens-mvp-06407b22
GitHub: http://github.com/bgelens/