Support version pinning in a configuration document

[michaeltlombardi]

Summary of the new feature / enhancement

As an infrastructure engineer, I want to be able to define version pins for the resoures in my configuration documents to ensure my configuration management is as deterministic as possible.

Proposed technical implementation details (optional)

A few options come to mind.

The easiest-for-users would be to allow them to append a version pin to the end of the resource type name for a resource, like Microsoft.DSC/[email protected]. This would require introduce complexity to the engine for handling and impact the way configuration functions work, which makes it a harder sell to me.

The more explicit option is to support a version field on the resource instance declaration:

- type:    Microsoft.DSC/PowerShell
  version: v1.0.0

Another option would be to define it under resource metadata:

- type: Microsoft.DSC/PowerShell
  metadata:
    Microsoft.DSC:
      version: v1.0.0

Of the available options, I lean more towards the metadata implementation, even though it requires defining per-resource metadata. However, we've discussed other uses for this property bag, and defining a structure for this would pave the way for those use cases. It would also enable users to declare version pins in the top-level metadata with per-resource overrides (if we choose to support that).

I don't think this would require any further work for adapters, since they already report available resources and versions to DSC.

[anmenaga]

Currently discovery in the engine and resource invocation (i.e. find and invoke this resource with this specific version scenario) does not consider resource versions at all;
so either way this will need some work in the engine.
And, most likely, an internal resource identifier will be changed to look like Microsoft.DSC/[email protected],
so probably we should use the same for user-facing resource identifier.

[michaeltlombardi]

Arguably, it might be better to have a pin or require (or similar) field in the resource instance declaration or metadata to support pinning by version/sha/signature/etc as that metadata about resources works its way into the engine so we don't have to overload the type name further. I'm also not sure if <namespace>/<name>@<version> is valid ARM syntax or not.

metadata:
  Microsoft.DSC:
    requireResources:
      - type: MyOrg/Database
        version: 1.2
        sha: <sha>
      - type: MyOrg.Web/*
        version: "[2.0,3.0)"
        signed_by: <trusted-persona>
resources:
  # Using `require` field on instance
  - type: MyOrg.Web/Server
    name: Setup web server
    require:
      version: 2.4.2
    properties: {}
  # Using `require` field in metadata
  - type: MyOrg.Web/Static
    name: Define static site
    metadata:
      Microsoft.DSC: { require: { version: 2.3.0, sha: <sha> } }
    properties: {}
    dependsOn:
      - "[resourceId('MyOrg.Web/Server', 'Setup web server')]"

Note

In this example I'm showing using both top-of-document and per-instance pins, but I wouldn't expect people to mix and match like this, or at least not to override document-level pins.

If we didn't have to maintain ARM compatibility, I think I would prefer specifying type as a string or an object with the requirements, e.g.

resources:
  - name: Setup web server
    type: MyOrg.Web/[email protected]
    properties {}
  - name: Define static site
    type:
      name: MyOrg.Web/Static
      version: 2.3.0
      sha: <sha>
    properties: {}
    dependsOn:
      - "[resourceId('MyOrg.Web/Server', 'Setup web server')]"

If we implement the dsc config resolve command in #414 and the more general-purpose "I want the fully resolved document based on this machine and the document I'm specifying" resolve command, I think it would be really valuable to be able to pull the version, sha, etc for the resources into the document. That would also make auditing, testing, and investigation more straightforward, assuming that only fully-resolved configuration documents are used in production.