Azure management client library for Java

The Azure Management Libraries for Java is a higher-level, object-oriented API for managing Azure resources, that is optimized for ease of use, succinctness and consistency.

We'd love to hear your feedback

We're always working on improving our products and the way we communicate with our users. So we'd love to learn what's working and how we can do better.

If you haven't already, please take a few minutes to complete this short survey we have put together.

Thank you in advance for your collaboration. We really appreciate your time!

Documentation

Various documentation is available to help you get started

• API reference documentation
• Code snippets and samples

Migration from older version of Azure management library

If you are an existing user of the older version of Azure management library for Java (the namespace of old packages contains com.microsoft.azure.management.**) and you are looking for a migration guide to the new version of the SDK, please refer to this migration guide here

Getting started

Prerequisites

• Java Development Kit (JDK) with version 8 or above
• Azure Subscription

Include the package

For your convenience, we have provided a multi-service package that includes some of the most highly used Azure services. We recommend using this package when you are dealing with mutiple services.

<dependency>
  <groupId>com.azure.resourcemanager</groupId>
  <artifactId>azure-resourcemanager</artifactId>
  <version>2.1.0</version>
</dependency>

The services available via azure-resourcemanager are listed as below:

List of services

• App Services
• Authorization
• CDN
• Compute
• Container Instance
• Container Registry
• Container Services (AKS)
• Cosmos DB
• DNS
• Event Hubs
• Insight (Monitor)
• Key Vault
• Managed Identity
• Network
• Private DNS
• Redis
• Resources
• Service Bus
• Spring Cloud
• SQL
• Storage
• Traffic Manager
• Search (preview)

In the case where you are interested in certain service above or the service not included in the multi-service package, you can choose to use the single-service package for each service. Those packages follow the same naming patterns and design principals. For example, the package for Media Services has the following artifact information.

<dependency>
  <groupId>com.azure.resourcemanager</groupId>
  <artifactId>azure-resourcemanager-mediaservices</artifactId>
  <version>1.0.0-beta.1</version>
</dependency>

See Single-Service Packages for a complete list of single-services packages with the API versions they are consuming.

Include the recommended packages

Azure Management Libraries require a TokenCredential implementation for authentication and an HttpClient implementation for HTTP client.

azure-identity package and azure-core-http-netty package provide the default implementation.

Azure Identity provides Azure Active Directory token authentication support across the Azure SDK.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
  <version>1.2.0</version>
</dependency>

Azure Core Netty HTTP client is a plugin for Azure Core HTTP client API.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-http-netty</artifactId>
  <version>1.6.3</version>
</dependency>

Alternatively, Azure Core OkHttp HTTP client is another plugin for HTTP client API.

Authentication

By default, Azure Active Directory token authentication depends on correct configure of following environment variables.

• AZURE_CLIENT_ID for Azure client ID.
• AZURE_TENANT_ID for Azure tenant ID.
• AZURE_CLIENT_SECRET or AZURE_CLIENT_CERTIFICATE_PATH for client secret or client certificate.

In addition, Azure subscription ID can be configured via environment variable AZURE_SUBSCRIPTION_ID.

With above configuration, the manager class can be authenticated by following code:

AzureProfile profile = new AzureProfile(AzureEnvironment.AZURE);
TokenCredential credential = new DefaultAzureCredentialBuilder()
    .authorityHost(profile.getEnvironment().getActiveDirectoryEndpoint())
    .build();
AzureResourceManager azure = AzureResourceManager
    .authenticate(credential, profile)
    .withDefaultSubscription();

The sample code assumes global Azure. Please change AzureEnvironment.AZURE variable if otherwise.

See Authentication for more options.

Code snippets and samples

See Samples for code snippets and samples.

Key concepts

The key concepts of Azure Management Libraries includes:

• Fluent interface to manage Azure resources.
• Dependency across Azure resources.
• Batch Azure resource provisioning.
• Integration with Azure role-based access control.
• Asynchronous operations with Reactor. (Preview)
• Configurable client, e.g. configuring HTTP client, retries, logging, etc.
• API design
• API design (preview)

Examples

Fluent interface

You can create a virtual machine instance, together with required virtual network and ip address created automatically.

VirtualMachine linuxVM = azure.virtualMachines().define("myLinuxVM")
    .withRegion(Region.US_EAST)
    .withNewResourceGroup(rgName)
    .withNewPrimaryNetwork("10.0.0.0/28")
    .withPrimaryPrivateIPAddressDynamic()
    .withoutPrimaryPublicIPAddress()
    .withPopularLinuxImage(KnownLinuxVirtualMachineImage.UBUNTU_SERVER_18_04_LTS)
    .withRootUsername("<username>")
    .withSsh("<ssh-key>")
    .withSize(VirtualMachineSizeTypes.STANDARD_D3_V2)
    .create();

Update.

linuxVM.update()
    .withNewDataDisk(10, 0, CachingTypes.READ_WRITE)
    .apply();

Dependency across Azure resources

You can create a function app, together with required storage account and app service plan created on specification.

Creatable<StorageAccount> creatableStorageAccount = azure.storageAccounts()
    .define("<storage-account-name>")
    .withRegion(Region.US_EAST)
    .withExistingResourceGroup(rgName)
    .withGeneralPurposeAccountKindV2()
    .withSku(StorageAccountSkuType.STANDARD_LRS);
Creatable<AppServicePlan> creatableAppServicePlan = azure.appServicePlans()
    .define("<app-service-plan-name>")
    .withRegion(Region.US_EAST)
    .withExistingResourceGroup(rgName)
    .withPricingTier(PricingTier.STANDARD_S1)
    .withOperatingSystem(OperatingSystem.LINUX);
FunctionApp linuxFunctionApp = azure.functionApps().define("<function-app-name>")
    .withRegion(Region.US_EAST)
    .withExistingResourceGroup(rgName)
    .withNewLinuxAppServicePlan(creatableAppServicePlan)
    .withBuiltInImage(FunctionRuntimeStack.JAVA_8)
    .withNewStorageAccount(creatableStorageAccount)
    .withHttpsOnly(true)
    .withAppSetting("WEBSITE_RUN_FROM_PACKAGE", "<function-app-package-url>")
    .create();

Batch Azure resource provisioning

You can batch create and delete managed disk instances.

List<String> diskNames = Arrays.asList("datadisk1", "datadisk2");
List<Creatable<Disk>> creatableDisks = diskNames.stream()
    .map(diskName -> azure.disks()
        .define(diskName)
        .withRegion(Region.US_EAST)
        .withExistingResourceGroup(rgName)
        .withData()
        .withSizeInGB(10)
        .withSku(DiskSkuTypes.STANDARD_LRS))
    .collect(Collectors.toList());
Collection<Disk> disks = azure.disks().create(creatableDisks).values();
azure.disks().deleteByIds(disks.stream().map(Disk::id).collect(Collectors.toList()));

Integration with Azure role-based access control

You can assign Contributor for an Azure resource to a service principal.

String raName = UUID.randomUUID().toString();
RoleAssignment roleAssignment = azure.accessManagement().roleAssignments()
    .define(raName)
    .forServicePrincipal(servicePrincipal)
    .withBuiltInRole(BuiltInRole.CONTRIBUTOR)
    .withScope(resource.id())
    .create();

Asynchronous operations (Preview)

You can create storage account, then blob container, in reactive programming.

azure.storageAccounts().define("<storage-account-name>")
    .withRegion(Region.US_EAST)
    .withNewResourceGroup(rgName)
    .withSku(StorageAccountSkuType.STANDARD_LRS)
    .withGeneralPurposeAccountKindV2()
    .withOnlyHttpsTraffic()
    .createAsync()
    .flatMap(storageAccount -> azure.storageBlobContainers()
        .defineContainer("container")
        .withExistingBlobService(rgName, storageAccount.name())
        .withPublicAccess(PublicAccess.BLOB)
        .createAsync()
    )
    //...

You can operate on virtual machines in parallel.

azure.virtualMachines().listByResourceGroupAsync(rgName)
    .flatMap(VirtualMachine::restartAsync)
    //...

Configurable client

You can customize various aspects of the client and pipeline.

AzureResourceManager azure = AzureResourceManager
    .configure()
    .withHttpClient(customizedHttpClient)
    .withPolicy(additionalPolicy)
    //...

Include single package

Instead of include the complete Azure Management Libraries, you can choose to include a single service package.

For example, here is sample maven dependency for Compute package.

<dependency>
  <groupId>com.azure.resourcemanager</groupId>
  <artifactId>azure-resourcemanager-compute</artifactId>
  <version>2.1.0</version>
</dependency>

Sample code to create the authenticated client.

ComputeManager manager = ComputeManager.authenticate(credential, profile);
manager.virtualMachines().list();

Troubleshooting

If you encounter any bugs, please file issues via GitHub Issues or checkout StackOverflow for Azure Java SDK.

HTTP client

An HttpClient implementation must exist on the classpath. See Include optional packages.

Latest azure-identity package specifies dependency on azure-core-http-netty package for convenience. If you would like to use a different HttpClient, please exclude azure-core-http-netty from azure-identity.

Enabling logging

Azure SDKs for Java offer a consistent logging story to help aid in troubleshooting application errors and expedite their resolution. The logs produced will capture the flow of an application before reaching the terminal state to help locate the root issue. View the logging wiki for guidance about enabling logging.

Sample code to enable logging in Azure Management Libraries.

AzureResourceManager azure = AzureResourceManager
    .configure()
    .withLogLevel(HttpLogDetailLevel.BASIC)
    .authenticate(credential, profile)
    .withDefaultSubscription();

ARM throttling

Azure Resource Manager applies throttling on the number of requests sent from client within certain span of time. For details, please refer to Guidance on ARM throttling.

Next steps

Contributing

For details on contributing to this repository, see the contributing guide.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request