Ambiguous Permissions on Properties Complicate 75+ Create-OR-Update Operations

[selvasingh]

Ambiguous Permissions on Properties Complicate 75+ Create-OR-Update Operations

There are 75+ Create-OR-Update operations (across Azure Swagger specs) with ambiguous, undocumented permissions on properties (or parameters). If permissions on properties were unambiguously represented in Swagger specs then a generated client library could offer simpler programming experiences and improved predictability.

Let us look at one example.

VirtualMachines.createOrUpdate() - one of the parameters is VirtualMachine. Here is a breakdown of permissions of a subset of properties of VirtualMachine:

Property	Permission
id	read (4)
storageProfile::imageReference	read | initialize (6)
storageProfile::osDisk::createOption	read | initialize (6)
storageProfile::osDisk::vhd::uri	read | initialize (6)
availabilitySet	read | initialize (6)
hardwareProfile	read | initialize | update (7)
storageProfile::dataDisks	read | initialize | update (7)
storageProfile::osDisk::caching	read | initialize | update (7)
networkProfile	read | initialize | update (7)
tags	read | initialize | update (7)

Today, because of this ambiguous situation, when a developer calls the VirtualMachines.createOrUpdate() operation, the only available option is trial and error to find out what combinations of parameters work.

The good news is that it is possible to capture these permissions.

Swagger 2.0 says, "Declares the property as "read only". This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as readOnly being true SHOULD NOT be in the required list of the defined schema. Default value is false " Some of Azure Swagger specs use this property.

readOnly can only represent read permissions but CANNOT represent read | initialize (6) OR read | initialize | update (7). A new Swagger extension will solve the problem -

Field Name	Type	Description
mutability	integer	Represents the permission of the property: -read (4) -initialize (1) -read | initialize (6) -read | initialize | update (7) Default is read | initialize | update (7)

Capturing permissions on properties will simplify programming experiences and improve predictability across languages - C#, Java, Node, Python, Ruby, PHP, Go - and tools - PowerShell and cross-platform CLI.

Today, regardless of the ambiguous situation, hand-written PowerShell commandlets and cross-platform CLI commands absorb the complexity and simplify it for developers - there are two distinct paths for Create and Update:

PowerShell: Create a virtual machine that uses VirtualMachines.createOrUpdate()

PS C:\> New-AzureRmVM -ResourceGroupName $ResourceGroupName -Location $Location -VM $VirtualMachine

PowerShell: Update a virtual machine that uses VirtualMachines.createOrUpdate()

PS C:\> Update-AzureRmVM -ResourceGroupName "ResourceGroup11" -Name "VirtualMachine07" -VM $VirtualMachine

If permissions on properties were unambiguously represented in Swagger specs then a generated client library could offer simpler programming experiences and improved predictability.

Reference - today, there are 75+ such Create-OR-Update operations with such ambiguous permissions on properties

Authorization

• RoleDefinitions.createOrUpdate()

Compute

• AvailabilitySets.createOrUpdate()
• VirtualMachineExtensions.createOrUpdate()
• VirtualMachines.createOrUpdate()
• VirtualMachineScaleSets.createOrUpdate()

Data Lake Store Account

• Account.createOrUpdateFirewallRule()

DNS

• RecordSets.createOrUpdate()
• Zones.createOrUpdate()

Intune

• Ios.createOrUpdateMAMPolicy()
• Android.createOrUpdateMAMPolicy()

Logic

• Workflows.createOrUpdate()
• WorkflowAccessKeys.createOrUpdate()

Network

• ApplicationGateways.createOrUpdate()
• ExpressRouteCircuitAuthorizations.createOrUpdate()
• ExpressRouteCircuitPeerings.createOrUpdate()
• ExpressRouteCircuits.createOrUpdate()
• LoadBalancers.createOrUpdate()
• LocalNetworkGateways.createOrUpdate()
• NetworkInterfaces.createOrUpdate()
• NetworkSecurityGroups.createOrUpdate()
• PublicIPAddresses.createOrUpdate()
• RouteTables.createOrUpdate()
• Routes.createOrUpdate()
• SecurityRules.createOrUpdate()
• Subnets.createOrUpdate()
• VirtualNetworkGatewayConnections.createOrUpdate()
• VirtualNetworkGateways.createOrUpdate()
• VirtualNetworks.createOrUpdate()

Notification Hubs

• Namespaces.createOrUpdate()
• Namespaces.createOrUpdateAuthorizationRule()
• NotificationHubs.createOrUpdate()
• NotificationHubs.createOrUpdateAuthorizationRule()

Redis

• Redis.createOrUpdate()

Remote App

• Collection.createOrUpdate()

ARM Resources - Locks

• ManagementLocks.createOrUpdateAtResourceGroupLevel()
• ManagementLocks.createOrUpdateAtResourceLevel()
• ManagementLocks.createOrUpdateAtSubscriptionLevel()

ARM Resources - Account

• Deployments.createOrUpdate()
• ResourceGroups.createOrUpdate()
• Resources.createOrUpdate()
• Tags.createOrUpdateValue()
• Tags.createOrUpdate()
• PolicyDefinitions.createOrUpdate()

Scheduler

• JobCollections.createOrUpdate()
• Jobs.createOrUpdate()
• JobCollections.createOrUpdate()
• Jobs.createOrUpdate()

Search

• Services.createOrUpdate()

SQL

• SecurityAlertPolicy.createOrUpdate()

App Service - Web App

• Certificates.createOrUpdateCertificate()
• Certificates.createOrUpdateCsr()
• Domains.createOrUpdateDomain()
• HostingEnvironments.createOrUpdateHostingEnvironment()
• HostingEnvironments.createOrUpdateMultiRolePool()
• HostingEnvironments.createOrUpdateWorkerPool()
• ManagedHostingEnvironments.createOrUpdateManagedHostingEnvironment()
• ServerFarms.createOrUpdateServerFarm()
• ServerFarms.createOrUpdateVnetRoute()
• Sites.createOrUpdateSiteVNETConnectionSlot()
• Sites.createOrUpdateSiteVNETConnection()
• Sites.createOrUpdateSite()
• Sites.createOrUpdateSiteSlot()
• Sites.createOrUpdateSiteHostNameBinding()
• Sites.createOrUpdateSiteHostNameBindingSlot()
• Sites.createOrUpdateSiteConfig()
• Sites.createOrUpdateSiteConfigSlot()
• Sites.createOrUpdateSiteSourceControlSlot()
• Sites.createOrUpdateSiteSourceControl()
• Sites.createOrUpdateSiteRelayServiceConnection()
• Sites.createOrUpdateSiteRelayServiceConnectionSlot()
• Sites.createOrUpdateSiteVNETConnectionGateway()
• Sites.createOrUpdateSiteVNETConnectionGatewaySlot()
• DataSources.createOrUpdate()
• Indexers.createOrUpdate()
• Indexes.createOrUpdate()

[devigned]

Why do we need read | initialize? Shouldn't that just be a readonly property? If they can't be updated in the API, why should we provide any way to initialize?

@Azure/adx-autorest-contributors thoughts?

[selvasingh]

Please see a partial breakdown of permissions of a subset of properties of virtual machine where some of the parameters are part of a create operation, then it is read only

[devigned]

@selvasingh the way I interpret that is that the constructor should require the readonly | initialize properties and not provide a setter for those properties. Anything that is readonly | initialize | update should be optional and provide a setter. Is that an incorrect interpretation?

[devigned]

OAI/OpenAPI-Specification#425 <-- perhaps, we should use composition as described here.

[selvasingh]

Azure/azure-sdk-for-java#698

[devigned]

I'm going to close this issue and track it via #307.