vSphere Content Library versioning 

A question came up the other day on how versioning is handled when using the vSphere Content Library feature and specifically when you update an existing VM template that already exists in the Content Library (CL, which I will be using throughout the article). Having used CL since vSphere 6.0 which I have also written about it extensively here, I knew that it had a built-in versioning mechanism which would automatically increment as new updates were applied to the VM Templates stored in CL.

One thing that I do not think many folks are aware of is that you can actually retrieve the CL Item Version within the vSphere Web Client. You can do by just adding the "Content Version" column by right clicking on column headers and select show/hide columns to add or remove specific fields.

I figured, this was pretty straight forward and shared my findings with the individual and thought that was it. While working on my Content Library PowerCLI community module, I came to learn there was more than one version that was being returned by the CL API.

Here is an example screenshot showing the three different versions using the Get-ContentLibraryItems (not to be confused with the OOTB Get-ContentLibraryItem cmdlet):

Taking a look at the API documentation, it was still not 100% clear on what all these versions provided and also when would they increment? I reached out to one of the CL Engineers, Eric who then provided me more information on how each of these versions are being used. Lets go through each one of them and I will include an example which also helped me understand how these different "versions" actually work.

Content Version - This particular version will increment as changes are made to the actual file content itself. This is also the same version that is available in the vSphere Web Client UI as shown earlier.

Lets now go through an example workflow to show when this version will get incremented:

1. Create a new VM called Foo (ContentVersion=N/A)
2. Clone VM Foo into CL called Foo VM Template (ContentVersion=1)
3. Clone completes for Foo VM Template (ContentVersion=2) <--The reason this is 2 and not 1 is that when the initial CL Item is created (think of it as a placeholder), the Content Version is incremented
4. Deploy Foo VM Template to new VM called Bar (ContentVersion=2, no changes on deploy)
5. Update VM Bar with some changes and clone Bar back to Foo VM Template (ContentVersion=3) <--Changes were made and we now increment the Content Version

Metadata Version - This particular version will only increment for changes made to either the name or description of the CL template.

Version - This particular version is used for concurrency control and this will always increment along with the Metadata Version for local libraries.

Lets now go through an example workflow for a local library to show how these two versions get incremented:

1. Create a new VM called Foo (MetadataVersion=N/A)
2. Clone VM Foo into CL called Foo VM Template (MetadataVersion=1, Version=1)
3. Update the description of Foo VM Template (MetadataVersion=2, Version=2)
4. Deploy Foo VM Template to new VM called Bar (MetadataVersion=2, Version=2, no changes on deploy)
5. Update VM Bar with some changes and clone Bar back to Foo VM Template (MetadataVersion=3, Version=3)

Lets now go through an example workflow for a subscribed library to show how these two versions get incremented:

• Create a new VM called Foo on a local library named CL1 (MetadataVersion=N/A)
• Clone VM Foo into CL called Foo VM Template (MetadataVersion=1, Version=1)
• Update the description of Foo VM Template (MetadataVersion=2, Version=2)
• Create a new subscribed library to CL1 which will download Foo VM Template (MetadataVersion=2, Version=1) <--MetadataVersion must match the publisher, but version does not have to match

After going through a few of these exercises with a few dummy VMs and using my Get-ContentLibaryItems function, I was able to get a better grasp on CL versioning. Hopefully this helpful for anyone who might want to use the CL APIs to track changes between their VM templates and/or files or just being able to see this within the vSphere Web Client UI.