Steps to migrate code that uses Azure Management Libraries for Java from 1.1 to 1.2 ...
If this note missed any breaking changes, please open a pull request.
V1.2 is backwards compatible with V1.1 in the APIs intended for public use that reached the general availability (stable) stage in V1.0.
Some breaking changes were introduced in APIs that were still in Beta in V1.1, as indicated by the @Beta annotation.
When you create a service principal, there's an option to export an authentication file:
return authenticated.servicePrincipals()
.define(SP_NAME)
.withNewApplication(APP_NAME)
// password credentials definition
.definePasswordCredential("password")
.withPasswordValue("P@ssw0rd")
// export the credentials to the file
.withAuthFileToExport(authFileStream)
.attach()
.withNewRoleInSubscription(role, subscriptionId)
.create();The output format has been changed from Java properties format to JSON. For more information about the auth file formats, please see the documentations here: https://github.com/Azure/azure-sdk-for-java/blob/master/AUTH.md#auth-file-formats.
The load balancer API, which has been in Beta, has undergone a major rework to further simplify the user model, to achieve greater consistency with the application gateway model, as well as to enable additional configuration scenarios that became possible as a result of more recent enhancements in the Azure Load Balancer service.
The rework includes naming changes, some API removals, some additions, as well as a reordering of the load balancer definition flow.
Other than the usual requirement for a region and a resource group at the beginning of a load balancer definition flow, the only other syntactically required element is the definition of at least one load balancing rule (.defineLoadBalancingRule()), OR an inbound NAT rule (.defineInboundNatRule()), OR an inbound NAT pool (.defineInboundNatPool()). Attaching at least one of these child elements results in a minimally functional and useful load balancer configuration. This change also enables the creation of load balancers which only have NAT rules or NAT pools and no LB rules, which was not possible in the earlier versions of the SDK.
Previously, at least one explicit frontend definition was required near the beginning of a load balancer definition flow, which could then be referred to from load balancing rules, NAT rules, and/or NAT pools. Although a frontend IP configuration is still a required child element of a load balancer under the hood, there are now methods within the LB rule, NAT rule and NAT pool definition flows which create automatically-named frontends implicitly, via a reference to a new or existing public IP address (.fromExistingPublicIPAddress(pip) | .fromNewPublicIPAddress(dnsLabel)) or to an existing virtual network subnet (.fromExistingSubnet(network, subnetName)). The former would result in the creation of a public (Internet-facing) frontend, whereas the latter would create a private internal frontend.
Note that if the same public IP reference is used by two or more rules/pools, they will all be automatically associated with the same frontend IP configuration under the hood, since multiple frontends pointing to the same public IP address are not allowed by the underlying service. Analogous logic applies to subnets.
Hence, frontend definitions are now in the optional ("creatable") section of the load balancer definition. Note however that if any of these *rules or *pools reference a frontend by name, rather than implicitly by a public IP address or subnet, then a frontend with that name MUST be defined explicitly later in that load balancer definition flow, despite of its "optional" status.
Probe definitions (.defineHttpProbe() | .defineTcpProbe()) have now been moved into the optional ("creatable") section of the load balancer definition flow as they are no longer required by the underlying service. Default probes are provided by Azure if no explicit probes are defined.
Backend definitions (.defineBackend()) have now been moved into the optional ("creatable") section of the load balancer definition flow. Backends can be implicitly created by the load balancing or NAT rule definitions by merely referencing their name (.toBackend(name)).
Previous releases of the load balancer API supported a notion of "default" child elements, such as default frontends, backends, etc. Those elements, when created implicitly, would assume the name "default" and would be the ones that other methods would refer to in implicit ways. In some sense, these "default" child elements were "global" across the load balancer definition.
This entire notion of a "default" child element of a load balancer has now been removed. The name "default" no longer has any special meaning and the methods operating on such default elements have been either removed or reworked. For example, .withExistingPublicIPAddress() which would have created a public frontend named "default" no longer appears in the load balancer definition flow. As mentioned earlier, certain child elements still can be created implicitly (e.g. frontends), but the names generated for them in such cases are unique and associated with the context they are created from (i.e., for example a specific load balancing rule).
The following naming associated with load balancers has been changed in ways that break backwards compatibility with the previous Beta releases of this API:
| From | To | Ref |
|---|---|---|
LoadBalancer.updateInternetFrontend() |
LoadBalancer.updatePublicFrontend() |
bf25b |
LoadBalancer.updateInternalFrontend() |
LoadBalancer.updatePrivateFrontend() |
bf25b |
LoadBalancingRule.withFrontend() |
LoadBalancingRule.fromFrontend() |
bd408 |
LoadBalancerInboundNatRule.withFrontend() |
LoadBalancerRuleInboundNatRule.fromFrontend() |
bd408 |
LoadBalancerInboundNatPool.withFrontend() |
LoadBalancerRuleInboundNatPool.fromFrontend() |
bd408 |
LoadBalancingRule.withBackend() |
LoadBalancingRule.toBackend() |
1e97e |
LoadBalancingRule.withBackendPort() |
LoadBalancingRule.toBackendPort() |
047e9 |
LoadBalancerInboundNatRule.withBackendPort() |
LoadBalancerInboundNatRule.toBackendPort() |
047e9 |
LoadBalancerInboundNatPool.withBackendPort() |
LoadBalancerInboundNatPool.toBackendPort() |
047e9 |
LoadBalancingRule.withFrontendPort() |
LoadBalancingRule.fromFrontendPort() |
951b2 |
LoadBalancerInboundNatRule.withFrontendPort() |
LoadBalancerInboundNatRule.fromFrontendPort() |
951b2 |
LoadBalancerInboundNatPool.withFrontendPortRange() |
LoadBalancerInboundNatPool.fromFrontendPortRange() |
52da0 |
LoadBalancingRule.withExistingPublicIPAddress() |
LoadBalancingRule.fromExistingPublicIPAddress() |
7ef84 |
LoadBalancerInboundNatRule.withExistingPublicIPAddress() |
LoadBalancerInboundNatRule.fromExistingPublicIPAddress() |
7ef84 |
LoadBalancerInboundNatPool.withExistingPublicIPAddress() |
LoadBalancerInboundNatPool.fromExistingPublicIPAddress() |
7ef84 |
| Removed | Alternate to switch to | PR |
|---|---|---|
LoadBalancer.withNewPublicIPAddress() |
LoadBalancerPublicFrontend.withNewPublicIPAddress() |
378d0 |
LoadBalancer.withExistingPublicIPAddress() |
LoadBalancerPublicFrontend.withExistingPublicIPAddress() |
378d0 |
LoadBalancer.withFrontendSubnet() |
LoadBalancerPrivateFrontend.withExistingSubnet() |
378d0 |
LoadBalancer.withLoadBalancingRule() |
LoadBalancer.defineLoadBalancingRule() |
dc191 |
LoadBalancer.withHttpProbe() |
LoadBalancer.defineHttpProbe() |
0b802 |
LoadBalancer.withTcpProbe() |
LoadBalancer.defineTcpProbe() |
0b802 |
LoadBalancer.withExistingVirtualMachines() |
LoadBalancerBackend.withExistingVirtualMachines() |
7a80c |
The document db API which was in the com.microsoft.azure.management.documentdb namespace has been moved to com.microsoft.azure.management.cosmosdb. The POM artifact id has been changed from azure-mgmt-documentdb to azure-mgmt-cosmosdb.
The following naming associated with document db has been changed in ways that break backwards compatibility with the previous releases of this API:
| From | To | Ref |
|---|---|---|
DocumentDBAccount |
CosmosDBAccount |
#1856 |
DocumentDBAccounts |
CosmosDBAccounts |
#1856 |
DocumentDBManager.databaseAccounts |
CosmosDBManager.databaseAccounts |
#1856 |