search

pulumi / pulumi-azure-native

Azure Native Provider
Apache License 2.0
126 stars 33 forks source link

Choose modules to structure according to Azure SDK not ARM Templates #690

Open mikhailshilkov opened 3 years ago

mikhailshilkov commented 3 years ago

At the moment, Azure-Native puts resources into modules that are named after ARM URL resource providers. Some of those names are outdated or confusing, and some resources clash because they end up in the same large module (like Network, e.g. #583).

In many aspects, Azure-Native follows Azure SDKs more closely than ARM Templates: naming resources after operations, flattening properties, renaming properties to SDK names. It would be logical to name modules similar to Azure SDKs too.

For example (old -> new):

etc.

Even, ARM template docs use some of those names in the menu structure: Cosmos DB, DNS, FrontDoor etc.

Every SDK has its own set of mappings, done mostly with readme.<language>.md files. So, mappings for different SDKs differ.

One possibility is to use top-level folder names in the azure-rest-api-spec repository folder structure, which gives unambiguous mapping. They are all lowercase so we'd have to map to PascalCase manually.

Obviously, any module naming change is largely breaking.

I'm curious to learn other opinions about this potential change.

mikhailshilkov commented 3 years ago

Here is a potential list of changes:

Insights->ApplicationInsights
Portal->CloudShell
DocumentDB->CosmosDB
Devices->DeviceProvisioningServices
DevTestLab->DevTestLabs
HybridData->HybridDataManager
Kubernetes->HybridKubernetes
VirtualMachineImages->ImageBuilder
Devices->IotHub
Management->ManagementGroups
DBforMariaDB->MariaDB
Media->MediaServices
OffAzure->Migrate
Migrate->MigrateProjects
Insights->Monitor
ManagedIdentity->Msi
DBforMySQL->MySql
DBforPostgreSQL->PostgreSql
DBforPostgreSQL->PostgreSqlHsc
PowerBI->PowerBIEmbedded
RecoveryServices->RecoveryServicesBackup
RecoveryServices->RecoveryServicesSiteRecovery
Cache->Redis
Cache->RedisEnterprise
Capacity->Reservations
Migrate->ResourceMover
SignalRService->SignalR
StorSimple->StorSimple1200Series
StorSimple->Storsimple8000Series
ImportExport->StorageImportExport
AVS->VMWare

Also, some resources move from one module to another (not all resources from the left go to the right, just a part of them):

Network->TrafficManager
Network->Frontdoor
Network->Dns
Network->PrivateDns
Aad->DomainServices
AadIam->AzureActiveDirectory
AzureActiveDirectory->CPIM
Authorization->Resources
Features->Resources
Solutions->Resources
OperationalInsights->ServiceMap
ContainerService->Compute
CertificateRegistration->Web
DomainRegistration->Web
headconnect commented 3 years ago

Sounds good to me - though my test is that it really does have to simplify mental mapping of navigation between various azure resources. I'm wondering if it wouldn't be pertinent to, along with these proposed changes, introduce a simpler top-level structure to differentiate between core offerings. Since you're pushing ContainerService into compute, perhaps the same should be done with ContainerInstance, HybridKubernetes (see? I'm using new names already ;)), possibly a few others. (windowsesu, windowsiot, vmwarecloudsimple, "ImageBuilder"..)

For me - maybe identity-related things under identity, like all IAM, AzureAD, managedidentity, etc. resources isn't really an optimal name for what it contains - though it's obvious when you're looking for resourcegroups and suchlike.

Basically, what I'm saying is.. this is hard ;)

I welcome such changes as they make sense as presented, and are not massive in impact. I'm definitely not experienced enough to know what's reasonable, only what "feels right" - so as I'm that subjective, I'm not going to try to impart any wisdom here, only a very lengthy thumbs-up

mikhailshilkov commented 3 years ago

@headconnect Thank you for the feedback! Naming is indeed hard.

you're pushing ContainerService into compute,

I think it's just one legacy-ish resource that goes from ContainerService to Compute, the rest remains the same.

The proposal above is still ~automatically produced from the Open API specs repository, it's just that we pick a different, more nuanced way to determine the name. We still want to do as little naming manually as possible.

imod commented 3 years ago

I'm not 100% sure whether I like it or not... On one side, I do think the names are very strange and I had issues to find the correct types too. But on the other side, after a while I found a way which really made it a lot simpler to find the correct type: by looking at the URLs of the azure portal... e.g. take this one, while looking at a "Log Analytics Workspace": https://portal.azure.com/#@mycomp.com/resource/subscriptions/XXXX-XXXXXX-XXXXX/resourceGroups/mygroup/providers/Microsoft.OperationalInsights/workspaces/mylogs/Overview it clearly points my to Microsoft.OperationalInsights The same is true when looking at the resources at https://resources.azure.com -> the names are what I use in my code too.

That sad I would rely hate to have to migrate my existing stacks again - if the old names are preconfigured as alias and https://github.com/pulumi/pulumi/issues/6570 is solved, then I guess this is ok.

yarinm commented 3 years ago

Will this affect existing stacks' state? This change has to be backwards compatible..

On another note, I think it's better to be aligned with the azure API and if an object is called there DocumentDB we should use that as well. It makes things much easier when trying to understand valid parameter values and if you are already using the azure SDK you will be familiar with the same terminology. I think the current naming is much better.

mikhailshilkov commented 3 years ago

Will this affect existing stacks' state? This change has to be backwards compatible..

We will provide aliases, so it will work in most cases. (https://github.com/pulumi/pulumi/issues/6570 being a counter-example)

if you are already using the azure SDK you will be familiar with the same terminology

The problem is that literally every SDK is different:

And the combination for every service is different.

ie-zero commented 3 years ago

Following the comment from @imod I constantly have the same issue i.e. to find which Pulumi resource maps to which REST call / ARM template.

As the top level resources have, or at least I assume they have, a 1-to-1 relation with the REST endpoints would it be possible to automatically generate the documentation linking the two together?

mikhailshilkov commented 2 years ago

@ie-zero Yes, that's a good suggestion. We can definitely link from our resources to ARM types - I'm not sure how to deal with the other way around, which seems more useful.

Can you give an example of a comment as you would like to see on a resource that wasn't trivial to you?

cleverguy25 commented 1 month ago

Added to epic https://github.com/pulumi/home/issues/3552

danielrbradley commented 1 month ago

Modules where we're not able to select a single default version beause of the overlap from multiple folders: