Provide resource name aliases

[sebader]

First of all: I do understand your goal of not abstracting away the details of the platform.

However, in order to provide an easier entrance/learning curve I would propose to offer aliases (for the lack of a better term) for common resource names.
For example:

resource vnet 'Microsoft.Network/virtualNetworks@2019-06-01'
=>
resource vnet 'virtualnetwork@2019-06-01'

resource tde 'Microsoft.Sql/servers/databases/transparentDataEncryption@2014-04-01-preview'
=>
resource tde 'sqldb_tde@2014-04-01-preview'

I'm sure there are many more considerations required around this but I thought it's worth having a discussion on this.

(Along the same lines I could also see that it could be helpful to provide defaults for the API versions but that should be - if at all - a separate issue)

[alex-frankel]

I do think we can get rid of Microsoft. pretty easily tbh, but we can put that aside for now.

I don't have a problem with aliases like this as long as we have a good system for keeping track of them and showing them in docs, etc. Curious what others think. One potential concern is by using an alias for a child resource, it does hide some of the complexity away from the user. In other words, it's important for authors to know that a child resource is a child resource and not a top level resource.

For abstracting apiVersions and "imports" (which could potentially allow you to create your own aliases), we have #16 tracking

[sebader]

Agreed, good documentation around this would be crucial. But IMHO that is anyway a big issue today with ARM vs Terraform - and tbh this puzzles me every time again:
If you go to the Azure TF provider docs, you get an immediate overview of which resources you can provision - and I mean all of which are available through TF. And when you go into a resource, you see all the properties and attributes.
There is nothing that comes even close to this in our official docs! :(

(sorry, this is a bit off topic but I believe apart from the syntax of ARM JSON this is one of the bigger reasons why people choose TF over ARM templates)

[alex-frankel]

Agreed. Have you seen the template reference before? This is technically our equivalent, but it's nowhere near as robust.

@DCtheGeek and @tfitzmac are in the middle of overhauling this page so it would be a great time to provide feedback

[sebader]

I actually haven't really used it. I'll take a look!

[sebader]

@alex-frankel looking at the template reference again, I remember why I never really used it... in it's current state the coverage and updates differs so greatly between different RPs, that I really lacked confidence that this gives me the current view of what's really available. Some RPs have a single API version listed - from 3 or 4 years ago.
And preview versions seem not to be listed at all. One might say that this is intentional but I know of RPs (e.g. Stream Analytics) where it is basically mandated to use a -preview version, just because the official ones haven't been updated in years and don't contain GA'ed features.

So to summarize: I think we absolutely need a 1st party place that lists all the available RPs and their offered APIs! Also in order for bicep to be really useful for people and be able to offer IntelliSense based on the API version you set in your template. If we get there I think bicep can be a huge value-add!

[tfitzmac]

We generate template reference from the REST API specs that RPs publish. The schemas used for Intellisense are generated from the same source. For some reason, Stream Analytics has only published one API version. The only way to generate schemas and docs is for the RPs to make sure their REST API specs are up-to-date.

It's important to not confuse the age of the API version with the its freshness. Many RPs continue to update an older API version because they have not introduced any breaking changes that require a new version.

We publish lots of preview versions but generally add them or remove them based on the RPs preference. Some RPs want preview versions published because it's the only way to use new features. Other RPs do not want users to continue using preview versions when a stable version has been released.

[sebader]

thanks @tfitzmac for the explanations! I didn't want to imply that the lack of coverage is because of ARM - the RPs are very much responsible to update their APIs.

However, when seen from an (external, non-MSFT) user perspective, this is somewhat hard to understand. If we want to make onboarding of new people to Azure easier, we somehow need to provide solutions on this.

[alex-frankel]

A couple of questions:

• to what degree is this problem mitigated by intellisense for resourceTypes (and apiVersions)?
• is the list of aliases maintained by microsoft? should it follow a specific naming convention? how many aliases would you expect (e.g. 10% of resource types?)

[sebader]

• To a) intellisense would certainly go a long way. However, consider that not everybody authoring the templates will always have the required tools installed. Also, aliases would help a lot with readability of a template - especially when we are talking about really long names like the TDE example above.

• b) I would assume the list would live together with the rest of bicep here on Github. So while we as Microsoft would of course govern PRs to that list, anybody could contribute/suggest new aliases. If we can come up with some good naming convention, that would of course help. Not sure, though, how easy it will be to find a common scheme that applies to many RPs.

As in how many RPs would be covered? I would say we should probably start by offering aliases to the most commonly used ones. From there on it can be up to the community (see PRs above) to suggest more

[slavizh]

may be this can be solved by Intellisense and improvements in search for RPs. For example let's say I am new user and I want to deploy Log Analytics. If I start to type loganalytics... it will show me Microsoft.OperationalInsights/workspaces RP and give me clear description that is RP for Log Analytics workspace. Same with Azure Monitor, you type monitor and you get all RPs for Azure Monitor including the workspaces one.

[MarcusFelling]

Closing this issue as we will be tracking this work in #622