[Story] Bicep Registry

[majastrz]

Bicep Registry

We need a mechanism in Bicep that allows users to publish and acquire Bicep content to/from an external registry.

Bicep content includes:

• modules
• linter rules
• types for ARM and non-ARM resources
• future extensibility

Requirements

Official/public registry

• Canonical and easy to find public registry for Bicep modules
• Can be scoped only to Bicep content
• Public-facing website
• Easy to browse
• High search relevance
• Ability to view dependencies, descriptions, reviews/ratings, publisher, etc.
• Metadata-aware search capability (can we search for modules referencing some obscure resource type?)

Support for private registries

• Users can setup private registries and authenticate to them in all relevant registry scenarios
• Private registry setup is not required to get started with Bicep.

Deployment-time reliability

The Bicep integration with Azure PowerShell and CLI introduces a deployment-time dependency on Bicep and therefore on the Bicep regitry. While users are generally more tolerant of reduced reliability at build time, they are less so at deployment time. As such, we should make every attempt to avoid regressing that as much as is feasible.

Versioning

• Content published to the registry must be versioned.
• Semantic versioning should be possible.

Simple end-user experience

References to modules in a registry should live in the bicep file and be similar to local module references as much as possible. In other words, the syntax should look like this:

module foo '...' = {
  name: 'fooName'
}

A separate proposal will be created to specify what '...' will look like in the registry case. Configuration of custom linters is TBD.

Tooling should be capable of:

• offering completions for modules in the registry
• restoring/downloading modules on-demand so the authoring experience is consistent with local modules (completions for modules parameters, for example)

The following scenarios should be possible out of the box without any additional configuration:

• Referencing a public module by version
• Linting with default set of linters and their default settings

Publishing to the registry

• Creating a registry package and publishing should not require in-depth understanding of the underlying packaging technology. Such operations should be exposed as simple/single CLI commands.
• It should be possible to script publishing to a private or public registry.

Local testing

• It should be possible to easily set up a local registry for local development and testing.
• Semantics of local registry should be similar to remote registries.

Consistent experience within Bicep ecosystem

• We should be using the same mechanism for pulling in content from the Bicep registry in all scenarios.
• Cross-cutting aspects such as configurating registries, auth, etc. should have an identical experience. The experience of consumption or referencing of content from the registry may vary depending on the scenario if the semantics are different. For example, module references live within a Bicep files but linter rules configuration should not.

Repeatable/trustworthy builds

• Bicep builds depending on public modules of specific versions should be repeatable.
  • Content that is published with a specific version should never change. (Content updates should be published with a new version number.)
  • Content should never be deleted from the public registry.
• It should be possible to sign registry content to authenticate its origin.
• Exceptions to the above may be made due to legal or security reasons.
• Private registries should follow the same rules as public registry to achieve reliable builds, but it is the responsibility of the registry admin.

Min version

• We should block content requiring a higher version of Bicep with user-friendly/obvious error messages.

Candidates

• OCI
• NuGet
• NPM
• Version Control based (Git/Sub Version/etc.)

Cost

The goal of the evaluation is not to choose the cheapest possible option but rather the one that provides the best experience with balanced against the cost of the implementation.

Open Questions

Here is a list of open questions and tentative answers:

1. Do we try to support multiple package managers/registry types? (No?)
2. How do we resolve conflicts between multiple feeds? (Can possibly defer to the package manager best practices?)
3. How do we resolve conflicts between custom linter dependencies? (Ideally we should have isolation of custom linter dependencies.)
4. Do we need to provide versioning for types to achieve repeatable builds? (Yes?)
5. Related to deploy-time reliability:

• Should we encourage "bicep restore" at deploy-time (via Az PS or CLI) or recommend patterns where this is done at build time.
• How to reconcile this with user expectations of just deploying via Az PS/CLI?
• Do we see two different audience types with different levels of concern about deployment reliability?

Appendix

Related issues:

• bicep module registry (BMR) #62
• Ability to reference "external" modules #660
• Modules need versions #1242

Misc. links:

• https://github.com/features/packages
• https://www.nuget.org/
• https://www.npmjs.com/
• https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs

[MarcusFelling]

Another candidate to add to the list is GitHub Packages: https://github.com/features/packages

[majastrz]

GitHub packages is an implementation of several package manager feeds (covers NuGet, NPM, several others and likely also OCI via Docker). It isn't a separate package manager on its own, but it's definitely something to consider while we figure out if we want to be package manager agnostic.

[MarcusFelling]

Understood. It was more so a consideration for where we host "official" modules, as opposed to NuGet.org or a public Azure Artifacts feed.

[majastrz]

And even if we don't use it for public feeds, it could also be a solution for private.

[majastrz]

Updated issue with notes from our discussion yesterday.

[johnymachine]

Possibly show bicep packege definition and import option on azure portal marketplace.

When i want to create storage account I can see in portal
import */StorageAccount and params i can supply

[sajayantony]

If these are Azure templates then having an Azure availability with possible regional availability in both public and airgap and other sovereign clouds needs to be considered.
MCR already supports OCI bundles and helm3 charts. The network egress rules for customers also stay consistent without requiring opening up your VNET to a full package manager endpoint.

[majastrz]

If these are Azure templates then having an Azure availability with possible regional availability in both public and airgap and other sovereign clouds needs to be considered.
MCR already supports OCI bundles and helm3 charts. The network egress rules for customers also stay consistent without requiring opening up your VNET to a full package manager endpoint.

Yes, that's one of the reasons why OCI is tempting and why we are considering it for this.