ADR: Azure provider registry aliasing

[asilverman]

ADR-1210: Azure provider registry aliasing

• Date: 2023-10-09
• Status: Accepted (10/11/2023 Bicep Discussion)

Protocol: Comments / Approval

• Please add an emoji as a means to provide your approval/objection to this proposed change.
  👍 (Approves)
  👎 (Objects)

• If you start a thread in a comment below, please use the ✅ (:white_check_mark:) emoji to signal you accept the resolution/answer and mark the thread resolved.

Context

With the introduction of dynamic type loading PR_#11458, a provider specification (for example import 'azure@1.0.0' as az has a corresponding oci artifact address mcr.microsoft.com/bicep/providers/az:1.0.0, the address for the az provider is hardcoded and the fqdn for the registry can ony be changed using a experimental environment variable __EXPERIMENTAL_BICEP_REGISTRY_FQDN PR_#11547.

Proposed Changes

We propose to add support for aliasing in a similar way aliasing is handled for Bicep modules for the az provider declaration syntax as following:

Case 1: Explicit declaration of the registry path

Example 1

import 'br:contosoregistry.azurecr.io/bicep/providers:az@1.0.0' as az

//bicepconfig.json
{
    "experimentalFeaturesEnabled": {
        "extensibility": true,
        "dynamicTypeLoading": true
    },
    "cacheRootDirectory": "~"
    // ...
}

In this case the user is using an explicit address from which to fetch the provider artifact, the compiler will use the current security context to authenticate the ACR client to fetch the types artifact.

The artifact will be stored under the path:

~/br/contosoregistry.azurecr.io/bicep$providers$az/1.0.0$/

Case 2: Default bicep registry

In the current implementation the syntax for declaring a provider is import 'az@1.0.0' as az, we propose changing the statement syntax to align with Example 1 (above).

Example 2:

import 'br/public:az@1.0.0' as az // where br:public is the alias

// bicepconfig.json
{
    "experimentalFeaturesEnabled": {
        "extensibility": true,
        "dynamicTypeLoading": true
    },
    "cacheRootDirectory": "~"
//...
}

When a registry prefix is unspecified and experimentalFeaturesEnabled.dynamicTypeLoading == true, the compiler will resolve the specification to the MCR registry address, that is, mcr.microsoft.com/bicep/providers/ and append to that prefix the value (azure:1.0.0) resulting in a fully qualified address for the type artifact https://mcr.microsoft.com/bicep/providers/az:1.0.0.

The artifact will be stored under the path:
~/br/mcr.microsoft.com/bicep$providers$az/1.0.0$/

The resolution happens by deduction from the default bicepconfig.json. There are various options to accomplish this discussed below.

Recommended Option

Uses the pattern established for modules. In the below bicepconfig.json adds a new section providerAliases that defines bicep registry alias called public and a providersPath with the prefix for provider artifacts in the registry.

//default bicepconfig.json
{
    "experimentalFeaturesEnabled": {
        "extensibility": true,
        "dynamicTypeLoading": true
    },
    "moduleAliases": {
        "ts": {},
        "br": {
            "public": {
                "registry": "mcr.microsoft.com",
                "modulePath": "bicep"
            }
        }
    },
    "providerAliases": {
        "br": {
            "public": {
                "registry": "mcr.microsoft.com",
                "providersPath": "bicep/providers"
            }
        }
    }
}

See Apendix for other options considered and a discussion on their drawbacks/benefits

Case 3: Using an alias

Example 3:

import 'br/contoso:az@1.0.0' as az

// bicepconfig.json
{
    "experimentalFeaturesEnabled": {
        "extensibility": true,
        "dynamicTypeLoading": true
    },
    "cacheRootDirectory": "~",
     "moduleAliases": {
        "ts": {},
        "br": {
            "public": {
                "registry": "mcr.microsoft.com",
                "modulePath": "bicep"
            }
        }
    },
    "providerAliases": {
        "br": {
           "public": {
                "registry": "mcr.microsoft.com",
                "providersPath": "bicep/providers"
            },
            "contoso": {
                "registry": "contoso.azurecr.io",
                "providersPath": "bicep/providers"
            }
        }
    }
}

In this case the user is gesturing the intent that they want to fetch the package from a private registry contosoregistry.azurecr.io whose alias is myPrivateRegistry. The compiler will resolve the alias by inspection of the bicepconfig.json and store the artifact under the path:

~/br/contoso.azurecr.io/bicep$providers$az/1.0.0$/

Out of Scope:

• Support local development work for type providers through loading of type artifacts from local paths (will be addressed separately)
• Support direct digest references like we do with modules in the import declaration syntax. This is a limitation of the current state (because SpecificationString is enforcing SemVer format)

Apendix

Options for how to specify the bicepconfig.json

Option 2: Converging both "moduleAliases" and "providerAliases" into "aliases"

{
    "aliases": {
        "ts": {},
        "br": {
            "public": {
                "registry": "mcr.microsoft.com",
                "modulePath": "bicep",
                "providerPath": "bicep/providers",
            }
// ...
}

Drawbacks:

• Seems to be conflating the concepts since "ts" is not a valid scheme for providers, costumers can be mislead to believe that it is
  Advantages:
• Easier to implement, requiring less custom code.

Option 3: Aliasing the full path of the provider (including) the provider name

import br:az@1.0.0

{
    "moduleAliases": {
        "ts": {},
        "br": {
            "public": {
                "registry": "mcr.microsoft.com",
                "modulePath": "bicep"
            }
        }
    },
    "providerAliases": {
        "br": {
           "az": {
                "registry": "mcr.microsoft.com",
                "providersPath": "bicep/providers/az"
            }
        }
    }
}

Disatvantages:

• Breaks consistency with pre-existing module syntax adding to cognitive burden of costumers

Advantages:

• Less stuff to type for costumers consuming providers

[majastrz]

I have some questions and comments:

1. The gestures to reference a provider in general should feel familar to users. Do we have a need to deviate from the module reference syntax for providers for non-MCR providers? For example, we could allow the full module reference syntax for type providers and treat az@x.y.z as a syntactic sugar that resolves to something like br/public:providers/az:x.y.z
2. In addition to aliased, non-aliased references, we should also support direct digest references like we do with modules.
3. How will local development work for type providers? Do we expect dev providers to be published to a private registry or can we allow them to be loaded on the local machine?

[asilverman]

1. The gestures to reference a provider in general should feel familar to users. Do we have a need to deviate from the module reference syntax for providers for non-MCR providers? For example, we could allow the full module reference syntax for type providers and treat az@x.y.z as a syntactic sugar that resolves to something like br/public:providers/az:x.y.z

I think this likely was an unintended omision on my part, I agree we should not deviate from the module reference syntax. I edited the proposal to use the syntax in the comment.

2. In addition to aliased, non-aliased references, we should also support direct digest references like we do with modules.

Adding support for digest references cannot be done with the current state since the provider SpecificationString is enforcing the SemVer format. We can relax this in the future to support digests if we want to but for now this is out of scope.

3. How will local development work for type providers? Do we expect dev providers to be published to a private registry or can we allow them to be loaded on the local machine?

Developers will be able to specify a local path in the bicepconfig.json in the following way:

// bicepconfig.json
{
    "experimentalFeaturesEnabled": {
        "extensibility": true,
        "dynamicTypeLoading": true
    },
    "cacheRootDirectory": "~",
    "providerAliases" : {
        "myPrivateRegistry" : {
            "registry": "<your-local-path-here>"
        }
    }
}

The compiler would resolve myPrivateRegistry to a local path. Support for local paths is however out of scope for this ADR and will be addressed in a separate ADR and subsequent PR

[dciborow]

I don't think that the version number should be part of the declaration. At least by default, the version number should be configured in the bicepconfig.json. When building a large template out of bicep modules, I think this version would have to be the same across all the nested dependencies.

import 'br/public:providers/az@1.0.0' as az == import 'az@1.0.0' as az == import az

// bicepconfig.json
{
    "experimentalFeaturesEnabled": {
        "extensibility": true,
        "dynamicTypeLoading": true
    },
    "version": {
      "az": "1.0.0"
    } 
    "cacheRootDirectory": "~",
    "providerAliases" : {
        "myPrivateRegistry" : {
            "registry": "<your-local-path-here>"
        }
    }
}

[asilverman]

@dciborow I think perhaps we can decouple two concerns/considerations you are bringing up in your comment. Please correct me if I misunderstood, as I read this I am thinking of the following concerns:

1. The provider import declaration syntax is too long. So import 'br/public:providers/az@1.0.0' as az can be reduced to something like import az which is more convenient to type.
2. There is an imperative to have the versions for a given types provider package to be the same across all imported modules.

• With regards to (1) I think while possible, I would like to better understand how to accomplish an experience that requires less typing in greater detail to prevent unintended side-effects. For now I'd like to call it out of scope for this proposal and discuss in greater detail what would such a feature look like. I am not sure this concern is blocking, and we can always refine the current proposal to align with a future change. With that said, I am happy to debate if you think it should be in scope.

• Regarding (2) this is in my opinion the topic of a separate conversation and should be addressed separately since it feels overtly restrictive.

[StephenWeatherford]

Agree with that comment. People have already been asking for a way to not have to specify a version in every resource (and ARM templates have api profiles). Are there scenarios where you need different versions in different files? Maybe aliases could be used for this, if the alias can specify the version. Or maybe not specifying a version uses the version specified in the bicepconfig (but that limits it to only a single version across all files or requiring all others to be explicit about the version).

[anthony-c-martin]

Case 1: Implicit resolution

This feels similar in goals to aliases. A shorter syntax definitely feels beneficial, but can we achieve this by extending aliases rather than introducing a new concept for path resolution?

[asilverman]

yes, I meant to extend aliases here. I fixed the proposal to align with the pre-existing features of module aliases

[anthony-c-martin]

Case 3: Using an alias

Example 3:

import 'br/myPrivateRegistry:providers/az@1.0.0' as az

IIRC, with modules you have 'br:<full_path>' and 'br/public:<short_path>', whereas here you are proposing '<full_path>' and 'br/public:<short_path>'. Was this an intentional difference?

[asilverman]

it was not intentional. The syntax for modules is confusing for me so I made a mistake. Fixed the proposal to be aligned with the syntax we are familiar with (from modules)

[shenglol]

I recalled the reason why alias must be before :. If an alias is after : then we cannot distinguish between the case where a module path starts with an alias, and the case where the user wants to use the alias:

br:example.com/my-module@1.0.0  // example.com is a registry endpoint
br:example.com/my-moudle@1.0.0  // Oops, example.com is an alias

[asilverman]

Ahh!, thanks for clarifying. I worry that I will likely forget again in the future just because the difference is very nuanced

[StephenWeatherford]

It's the ":" vs "/" that's hard to remember. Specifically what "br/..." is supposed to mean, it looks so much like "br:" for new users.

If we were starting from scratch, I'd suggest something like:

module bs_noalias "br:mcr.microsoft.com/path/module"
module ts_withalias "public:path/module"
module ts_withalias "custom:path/module"

I.e., not sure what requiring "br/" and "ts/" in front of an alias buys us. The alias itself ought to be enough to match with bicepconfig.json.

[StephenWeatherford]

We had talked about versioning the registry cache. I believe we had decided to use this or something similar?

br/modules.v2
br/providers.v2
br/templatespec.v2

@shenglol @majastrz Does that sound right?

[shenglol]

For template specs the scheme is ts instead of br. Also, we don't need v2 in the path since modules and providers in the path can be v2 manifest indicators.

[StephenWeatherford]

Not if we might add a v3 later (hopefully not but entirely possible).

[shenglol]

That's fair. In that case I'd prefer adding v2 as a subdirectory.

[StephenWeatherford]

So:

cacheroot/br/v2
cacheroot/ts/v2
cacheroot/pr/v1

or would it be:

cacheroot/br/v2/modules
cacheroot/br/v2/providers
cacheroot/ts/v2

or:

cacheroot/br/modules/v2
cacheroot/br/providers/v2
cacheroot/ts/v2

or?

I'm tracking possible cache changes including this here: #11900

[shenglol]

Personally I prefer

cacheroot/br/modules/v2
cacheroot/br/providers/v2
cacheroot/ts

[anthony-c-martin]

For modules, we consider filesystem to be the "default", with br & ts requiring specific opt-in.

For providers, is there any benefit to considering filesystem default, or could we consider br the default?

[asilverman]

I think that br should be the default. ts is not supported and local can be added later. Also, I am not sure if by default you mean that there is no need to specify the br: prefix. If that is the case, I think that it is a possibility, but I worry it makes this too implicit.

[anthony-c-martin]

Also, I am not sure if by default you mean that there is no need to specify the br: prefix. If that is the case, I think that it is a possibility, but I worry it makes this too implicit.

Yeah, that's what I was wondering. For modules, because local is the default, it's implied unless the user fully qualifies with br: or ts:. Agree it might be too confusing to change the default for providers.

[StephenWeatherford]

...Especially if we had to add "local:" to use local paths.

[StephenWeatherford]

Can we perhaps consider simplifying this as I mentioned above, to get rid of the "br/" and "ts/"? That can be figured from the bicepconfig (yes, we have to make some breaking changes, or allow both, and aliases would have to be all in the same namespace, not separated by br/ts/pr):

module bs_noalias "br:mcr.microsoft.com/path/module"
module ts_withalias "public:path/module"
module ts_withalias "custom:path/module"

I.e., not sure what requiring "br/" and "ts/" in front of an alias buys us. The alias itself ought to be enough to match with bicepconfig.json. Seems a lot cleaner and less confusing. Doesn't conflict with "c:\path" because only relative local paths are allowed.