Reconsider how Azure API versions are exposed in the programming model #169
Comments
|
Overall, my hypothesis is that this is much more natural for folks familiar with ARM. Our raw exposal of ARM API sort-of requires good understanding of ARM overall, there's no shortcut, unfortunately.
As mentioned in #167, the plan is actually to discourage using
You would get ~50-100 versions to choose from - how would you find the one you need? It's easier to start your selection with the resource provider and get a limited set of versions.
We discussed this and can still do this, but that doesn't really match the advice not to use it for production stacks.
Indeed. All our manually-created examples and templates don't use blank imports for this reason. Instead, they import targeted separate modules. Our docs generation can't do that yet. Curious what others think @lukehoban @leezen @infin8x |
|
All makes sense, and I suspect you're 100% right here. Just take this as feedback from a relative Azure newbie who just wanted to get up and running, and spelunk a bit through the Azure services, and wished it was simpler to navigate and understand how to do the right thing. The versioning of the package and the APIs within that package is definitely a strange, non-standard pattern, and yet I understand from your reply why it ended up that way. |
|
JFWIW - I personally expected we would get a fair bit of similar feedback during the preview, and would find ourselves wanting to promote the I do believe the "right" thing for heavy users will be to learn about API Versions and pin to them, as there are real versioning pains they will feel otherwise. But luckily, that pinning is something they can do at the time they might be impacted by a breaking change, which means it is less critical they buy into this complexity right away. That is, if they start with just the simple default, then if/when they encounter a breaking change, they have the option to pin the API Version. There are a few things we could do to make this a better overall user experience if we did want to go this direction:
Does the Azure SDK have this same problem? I still am not exactly sure how our |
I guess they don't. As far as I can tell, they don't have a fully automated process to release a new SDK version as soon as API definitions change and they do have some hand-holding to avoid these situations. One part of that are Often, an API version would change with a comment "SDKs don't use it yet". |
As someone who has worked on ARM for some years, I can tell you that, for me, I take zero thought of the API version until I have to. Usually, I just use whatever version was there when I copied the template from elsewhere. I would like to take zero thought of the API version in Pulumi as well.
I disagree with this plan. It might work better based on Pulumi's current versioning scheme, but it is contrary to the way developers work with packages in real languages. This would also make shared libraries untenable because now library developers either have to recode every thing for each version of each resource or they just pick which version has the most users (probably latest).
Here is how I would fix these issues and make it easier for those who want to work with "latest" or just newbs:
Yes, because of the way Pulumi is doing this. Currently, the package version can change from X.3 to X.4 and, even though it may seem like a harmless update, it can actually introduce breaking changes where most developers wouldn't expect one.
This is easily solved by updating the major version number every time a new Azure API version is released.
Again, this issue becomes much less critical when the major version number changes. This is because developers understand that a new major version implies potential breaking changes. The next section also helps.
For this (and many other good reasons), we need to break up the areas and versions into separate packages. Currently, we have one package that includes everything:
I propose the following package dependency structure:
"So, mostly, everything is the same, just multiple packages" But sooo much more flexible and useable.
That's fine. ARM2Pulumi can still use the versioned resources. Results
@joeduffy I was in the same boat as you. At first, I was like WTH!?! Then @mikhailshilkov explained it to me and it all seemed to make sense. But, now, as someone who has spent a lot of time with this provider, it just doesn't work well. As @lukehoban explained, "latest" should be the default and the versioned packages are just for fallback. My original Slack thread |
|
Here is our thinking for API versioning that we intend to have at 1.0 of this provider. We have two major goals here:
We will solve these two goals separately:
How the top-level resources work:
We will explore the potential evolution of our SDKs that may allow us to make the top-level resources "multi-versioned". Any results will come after the 1.0 release. I encourage everyone to 👍 this comment if it makes sense to you, or leave a comment below with any concerns. |
|
I'd like to see the top-level modules as a separate NuGet package since a) It's opinionated Thoughts? |
|
@lukehoban I think you had a strong opinion against splitting the packages. Could you respond to @MisinformedDNA? |
|
And this:
VS only recommends three possible classes, but since there are so many classes named the same, it, more often than not, recommends all the ones you don't want. If there were fewer classes (slimmer packages), this issue would come up far less often. |
I am finding working with the Azure NextGen provider to be a bit clumsy in comparison to our usual patterns, due to the way we expose API versions. This is simply my own feedback, and I'm curious whether others agree/disagree.
The way API versions are front and center feels very "web API", and specific to the way Azure versions their APIs, and not something I'd expect so prominently in a library's surface area. Also, I can't imagine most end users would want to peg to a specific version, versus just using
latest, so forcing users to think about and choose a "version" so early in developing code against these libraries just feels odd -- indeed, for me, it was jarring. I mean, why wouldn't I just picklatest?It also seems odd to me that versions are per-service rather than just being global to the entire package.
An alternative way to structure this would be:
Expose
latestresources automatically from the various modules -- so, for instance,new azure.resources.ResourceGroup(..)would pick up the latest API by default.Provide a way to import the API definitions for alternative versions if you want, at a package-wide level -- so, for example,
import * as azure20190501 from "@pulumi/azure-nextgen/v20190501".This feels more intuitive to me. As an added bonus, it should perform better because we wouldn't parse all the different API version variants when you imported the default version alone. This could have language-specific implications, however.
The text was updated successfully, but these errors were encountered: