Azure-cli: Need better documentation on how Reimage works for VMss

[akramwaseem]

Hi,
Need a better documentation on the reimage works.
In a VMss lets say I have 10 VMs and I want to do reimage of all the VMs. How does it work. does it do on by one with zero downtime or does it do all at once?

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 0408c294-207a-2b72-7b93-e09121602b75
• Version Independent ID: 852cb67b-70c6-b811-3b0a-5d5b84b8a911
• Content: az vmss
• Content Source: src/command_modules/azure-cli-vm/azure/cli/command_modules/vm/_help.py
• Service: virtual-machine-scale-sets
• Product: unspecified
• GitHub Login: @rloutlaw
• Microsoft Alias: routlaw

[yugangw-msft]

//CC: @gatneil

[gatneil]

It does the reimage on all VMs specified in the command; if none are specified, it does all

[colemickens]

Hi @gatneil. I am really trying understand how to build some basic scenarios around VMSS and am having a hard time coming up with some fundamentals, or Google is failing me on finding documentation.

1. Does it reimage them all at once? Is it possible to roll it, or do I need to orchestrate that by hand by slicing instance ids and calling repeatedly?

2. What does reimage actually mean? There seems to be an entire "Reimaging Overview" document entirely missing. Things that I need to know about:

   • pitfalls, general guidance
   • what happens to data disks
   • rate of which rollout occurs (is the reimage done on my 300 VMs all at once?)
   • what happens to the VM ID exposed to the VM
   • does 'reimage' revert just the OS disk? does it reimage to the VMSS model at the last time of upgrade, or does it "reimage" to the current VMSS model?

3. What is the exact difference between 'upgrade', 'rolling-update' and 'reimage'? This forum post implies that "upgrade" can go one-by-one, but I thought that was exclusive to "rolling-update" and the 4 supported platform images? https://social.msdn.microsoft.com/Forums/en-US/2e9b155b-a11a-461b-ad8b-73f74814a064/vmss-upgrade-and-reimage?forum=WAVirtualMachinesforWindows (OTOH, I think the answer might have conflated Guy's tool with the API functionality inaccurately?)

A table of the three operations, along with rows like "update hw", "reset root disk", "reset disk attachments" etc, would go a long way to helping people build on top of these VMSS features.

[gatneil]

Hey @colemickens! Long time no see. I actually don't work in Azure anymore, but I agree that the information should get out there. For questions 1 and 2, I threw together a couple blog posts that cover the topics:

Updating a scale set (including details around how POST APIs like reimage operate at the control plane): https://negatblog.wordpress.com/2018/06/05/updating-a-scale-set/
Reimaging VMs in a scale set (mostly focused on the data plane - what does reimage actually do?): https://negatblog.wordpress.com/2018/06/05/reimaging-vms-in-a-scale-set/

As for question 3: It depends on exact context, but I suspect "upgrade" refers to "manual upgrade" (a.k.a. "update instances"...sigh, there are too many ways to describe the same thing). When doing PUT/PATCH updates in manual upgrade mode, only the scale set model is modified; existing VMs are not. Doing a "manual upgrade" call then brings up each VM specified in the request up to date with the latest model (note: the "manual upgrade" call itself is a POST API, so it behaves as discussed in the first blog post; in particular, this means that the operation happens on all VMs specified at the same time; the upgrade policy is bypassed).

"rolling-update" likely refers to the "rolling" upgrade mode. In this mode, PUT/PATCH updates are rolled out to VMs in the scale set automatically in batches. In this mode, "manual upgrade" calls are not necessary.

Finally, "reimage" replaces the old, crusty OS disks of a specified set of VMs with new, shiny OS disks. (note: this is also a POST API, so it has the same behavior described above).

Hope this helps! Let me know if you have follow-up questions :)

[colemickens]

@gatneil :wave: This is really great, I can't thank you enough. The PUT/PATCH/POST is a great resource too, especially including knowing how to know the request type from the docs. Thank you very much.

I think I only have one more question that you might know, and if not, I can experiment.

1. Deploy VMSS with user image foo.vhd.
2. Update the VMSS mode with user image bar.vhd.
3. (Do not do any upgrade commands to bring any of the VM to the new model, or anything)
4. Issue reimage to a VM.

Does the new OS disk come back as foo.vhd or bar.vhd?

[gatneil]

@colemickens, glad the blog posts were helpful. Let me know if you have other questions that come up. For this particular question, the new OS disk will come back as bar.vhd :)

[yugangw-msft]

@rloutlaw, I don't think the information provided should get to the CLI's help file, rather we need a document which can bring in good information from the following sources:

https://negatblog.wordpress.com/2018/06/05/updating-a-scale-set/
https://negatblog.wordpress.com/2018/06/05/reimaging-vms-in-a-scale-set/

I am closing this, as it is not actionable for CLI team

[sgerace]

I'm sorry to comment on this closed ticket, however, @colemickens I happened to stumble across this issue while investigating a similar question I had, and was wondering if you were ever able to arrive at a definitive answer as to whether, in your example, you would end up with foo.vhd or bar.vhd. From my testing, it appears that I am ending up with foo.vhd — in other words, I need to explicitly run update-instances on each instance in order to have it start pulling the updated image defined in the scale set model. A simple call to reimage is not sufficient in my testing.

@gatneil, in your blog post, you mention:

Note that with both types of reimaging, the VM is reimaged to the latest model of the scale set, not the model the VM was previously running with (since, in some cases, the VM might model might have lagged behind the overall scale set model). For instance, if you were to create a scale set in manual upgrade mode with admin username “neil”, then update the scale set model to have admin username “notneil”, then reimage VM 27, when VM 27 comes back up, the admin username will be “notneil”.

This logic does not seem to apply to the referenced image itself. Is this consistent with what you would expect? Does anyone know why there might be a discrepancy?