ADR: Process for publishing the AZ provider types (alpha)

[asilverman]

Process for publishing the az provider types (alpha)

Date: 2023-09-07

Status

Draft

Context

The goal of this ADR is to formally describe the recommended process for publishing the az resource types provider
as an OCI artifact for the purpose of dynamic loading as described in proposal #10662 (previously accepted by the Bicep maintainers) for an alpha milestone.

This means some concrete process so we can publish experimental az types packages so we can inform our decisions moving forward.

Current State

In the current state we have two workflows that are executing in the repository.

1. build.yml - Triggered by PRs and push to main . Builds the generator and its dependencies and publishes a NuGet
   package with the Azure resource type definitions.
2. update-types.yml - Triggered by a cron schedule (once a week) or manually. Checks out a snapshot of the main
   branch from the azure/azure-rest-api-specs repo, runs the generation script on the snapshot and commits the result to the
   /generated folder in the autogenerate or
   azure/bicep-types-az/tree/autogenerate-<git-commit-ish> branches depending on the trigger (a '<git-commit-ish>' is a truncated commit sha256 digest)

When a new version of the Bicep is released, the person cutting the release performs the following steps:

1. Chose to either manually merge the autogenerate branch into main or manually trigger the update-types.yml
   workflow to update the /generated folder. This will update the definitions stored in /generated in the main branch and trigger
   the build.yml workflow which in turn will publish a NuGet package with a bumped version.
2. Verify (manually) that a new NuGet package was published
3. Update the NuGet package reference in the Bicep.Core.csproj file in the azure/bicep repo to the new package
   version
4. Proceed with the release process for azure/bicep

The current process allow us to catch the odd regression before impacting any customers (e.g. the time where we accidentally deleted all of the types for Microsoft.Compute)

Desired State (For Alpha)

• We want to automatically publish a new az-types-provider-package OCI artifact each time theres a change in the
  azure/bicep-types-az/tree/main/generated folder.
• We will tag the Azure/bicep-types-az and the OCI registry artifact with a version 0.0.X-alpha where X is corresponding to
  the topological distance, measured as count of commits made on the folder since the first publication (0.0.1-alpha).

Out of Scope

• Determining what the version should be for GA of these packages

Proposed Changes

We propose to add a new workflow publish-az-provider-to-registry.yml that triggers on push to main that will publish an OCI artifact to the bicep public registry (syndicated with MCR).

The workflow will:

1. Check if a new version of the package must be published by comparing the state of the /generated folder with the state of the previous version.
2. Increment the the X-alpha version by one if a change is detected.
3. Tag the azure/bicep-types-az commit with the new version.
4. gzip and tar all .json files in the /generated folder into a .tgz file
5. Use ORAS to publish the az-types-provider-package artifact to the Bicep public registry under the following prefix: bicep/providers (e.g. mcr.microsoft.com/bicep/providers/az:1.0.0). The tag for the OCI artifact will match the semantic version.

The OCI types provider artifact structure

A resource types provider artifact MUST conform to the following requirements:

1. The OCI Image manifest for a types provider OCI manifest MUST set the following fields as shown below:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json", // CONSTANT
  "artifactType": "application/vnd.ms.bicep.provider.artifact", // CONSTANT
  "config": {
    // v1 is used to represent the current serialization version, this gives us flexibility
    // to bump the version in the future if we want some configuration in the future.
    "mediaType": "application/vnd.ms.bicep.provider.config.v1+json", 
    "digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "size": 0 // MUST BE EMPTY FOR V1+JSON
  },
  "layers": [
    {
      // For any artifact with `config.mediaType == vnd.ms.bicep.provider.config.v1+json` 
      // there MUST be one and only one layer with a mediaType below
      // The config mediaType may be incremented allowing for other layers with different mediaTypes
      "mediaType": "application/vnd.ms.bicep.provider.types.layer.v1.tar+gzip",
      // The contents MUST be a single tar+gzip file whose decompressed structure
      // MUST match the `/generated` folder structure, that is, a top-level index.json 
      //with a relative path to a file structure that leads to a types.json file for the specify type 
      "digest": "sha256:5eef22336a881e27bb27125670d963e749bddc030227c556fa4fe1ee802e54ef",
      "size": 10387998,
      "annotations": {
         // This OPTIONAL annotation gives you the file name (automatically set by ORAS)
        "org.opencontainers.image.title": "types.tgz"
      }
    }
  ],
  "annotations": {
    // This OPTIONAL annotation gives you the date timestamp when the artifact was generated (automatially set by ORAS)
    "org.opencontainers.image.created": "2023-09-06T19:43:08Z"
  }
}

Decision

Consequences

[anthony-c-martin]

• We want to automatically publish a new az-types-provider-package OCI artifact each time theres a change in the
  azure/azure-rest-api-specs/tree/main/specification folder.

This folder changes very frequently - I'd possibly consider having a lower bound for how frequently we push updates to avoid having an overwhelming number of versions published.

[majastrz]

I think we can publish the {} config blobs based on @StephenWeatherford's findings during his modules investigations.

[jeskew]

We want to automatically publish a new az-types-provider-package OCI artifact each time theres a change in the
azure/azure-rest-api-specs/tree/main/specification
folder.

Would this preclude using GitHub actions or policies? I don't believe any of our existing automation can watch an external repo for changes, so we might need to write a custom bot to achieve this.

[majastrz]

What is the usecase for the org.opencontainers.image.title annotation?

[anthony-c-martin]

• Automatically determining what the new semantic version should be. For now, a human must make the versioning determination for MAJOR and MINOR versions based on inspection of the /generated folder. The PATCH version will be incremented and the git 'height' from the initial commit on the /generated folder.

Isn't this in contradiction with the final "desired state" point? Or is "desired state" larger than the scope of this ADR. Might be worth clarifying that.

[jeskew]

We want the semantic version to increment MAJOR, MINOR and PATCH version automatically based on some heuristic that inspects the state of the /specification folder in the snapshot as compared to the previous published state.

I'm skeptical that such a heuristic exists. Why not use something that can always be reliably calculated (e.g., date-based versioning)?

[majastrz]

I think org.opencontainers.image.created is a good idea to include in this. We should check if we do the same for modules (out of scope of this proposal).

[majastrz]

Use ORAS to publish the az-types-provider-package artifact to the Bicep public registry under the following prefix: bicep/providers (e.g. mcr.microsoft.com/bicep/providers/az:1.0.0). The tag for the OCI artifact will match the semantic version.

I think it makes sense to use ORAS to start with, but I think eventually we will need to generalize the ability to publish providers. At which point, I think we will need to add a new verb to Bicep CLI that accomplishes the same thing but is also capable of performing additional validation on the type provider content that is specific to our scenario. (For example, validating the types JSON.)

[anthony-c-martin]

We propose to add a new workflow publish-az-provider-to-registry.yml that triggers on push to main that will publish an OCI artifact to the bicep public registry (syndicated with MCR).

I would also clarify that this workflow needs to be testable, to validate we're pushing out the correct format.

[StephenWeatherford]

I think org.opencontainers.image.created is a good idea to include in this. We should check if we do the same for modules (out of scope of this proposal).

Agreed. I already have a PR to add to modules.

[anthony-c-martin]

Desired State

As discussed, it would be helpful to clarify that this isn't the desired state of this proposal - rather the eventual desired state. It would be helpful to explain the desired state for this proposal as part of the doc.

[StephenWeatherford]

We want the semantic version to increment MAJOR, MINOR and PATCH version automatically based on some heuristic that inspects the state of the /specification folder in the snapshot as compared to the previous published state.

I'm skeptical that such a heuristic exists. Why not use something that can always be reliably calculated (e.g., date-based versioning)?

Really don't want to see us with another apiVersion type of non-semantic versioning where you can't tell at all whether there are supposed to be breaking changes or not.