Azure Batch Client Library for Python

Common errors

• ModuleNotFoundError: No module named 'azure.batch'

  cause The 'azure-batch' package is not installed in the Python environment.
  fix Install the package using pip: 'pip install azure-batch'.

• AttributeError: 'BatchServiceClient' object has no attribute 'job'

  cause The 'BatchServiceClient' object does not have a 'job' attribute; the correct attribute is 'job_operations'.
  fix Use 'batch_service_client.job_operations' instead of 'batch_service_client.job'.

• TypeError: __init__() missing 1 required positional argument: 'batch_url'

  cause The 'batch_url' parameter is required when initializing 'BatchServiceClient'.
  fix Provide the 'batch_url' parameter when creating the client: 'BatchServiceClient(credentials, batch_url)'.

• ImportError: cannot import name 'BatchServiceClient' from 'azure.batch'

  cause The import statement is incorrect; 'BatchServiceClient' should be imported from 'azure.batch' directly.
  fix Use 'from azure.batch import BatchServiceClient' instead of 'from azure.batch.models import BatchServiceClient'.

• ValueError: The 'id' parameter is required and cannot be None.

  cause The 'id' parameter is missing or set to None when creating a job or pool.
  fix Ensure that the 'id' parameter is provided and not None when creating a job or pool.

Warnings

• breaking Version 15.x and above introduces significant changes and improvements from v14.x and below. A migration guide is available in the official GitHub repository's README.
  Fix: Consult the official migration guide for `azure-batch` in the Azure SDK for Python GitHub repository to adapt your code. This often involves changes to client instantiation and model usage.
• breaking The `lifetime statistics API` was removed in version 14.0.0. Specifically, `job.get_all_lifetime_statistics` and `pool.get_all_lifetime_statistics` are no longer supported.
  Fix: Remove calls to `get_all_lifetime_statistics` methods. You may need to implement custom logic to track lifetime statistics if needed, using other available APIs.
• deprecated CertificateOperations-related methods were deprecated in version 14.0.0 and were scheduled for removal after February 2024. Users are advised to use Azure KeyVault Extension instead.
  Fix: Migrate any certificate management logic to use Azure KeyVault Extension. Avoid using the deprecated CertificateOperations methods.
• gotcha Microsoft Entra ID (formerly Azure AD) authentication using `azure-identity` and `DefaultAzureCredential` is strongly recommended for `azure-batch`. Some Batch capabilities require this, and Batch account API authentication can be restricted to only Microsoft Entra ID, rejecting shared key authentication.
  Fix: Always prefer `DefaultAzureCredential` from `azure-identity` for authentication. Ensure your application or user principal has appropriate Azure RBAC roles assigned to the Batch account.
• gotcha When installing packages on Batch compute nodes, if using StartTask, ensure the Python environment is correctly set up. Common issues include `pip` not being recognized or incorrect Python versions.
  Fix: Use a platform image that comes with a suitable Python environment (e.g., Ubuntu 18.04 LTS for Python 3.6). If custom packages are needed, use a `StartTask` to install them (e.g., `pip install -r requirements.txt`) or consider custom VM images. Ensure correct paths for Python executables.
• gotcha The default task retention time for all tasks was changed from infinite to 7 days. This means task-related files and stdout/stderr logs will only be available for 7 days by default.
  Fix: If longer retention is required, explicitly set the `retention_time` property when creating tasks or jobs. Ensure critical output files are persisted to an Azure Storage account.

Install

• pip install azure-batch azure-identity Install stable version with Azure Identity
• pip install azure-batch==15.1.0b3 azure-identity Install latest preview (v15+) with Azure Identity

Imports

• BatchServiceClient
  wrong:

  from azure.batch.batch_service_client import BatchServiceClient

  correct:

  from azure.batch import BatchServiceClient

  Direct import from the top-level package is standard.
• models
  wrong:

  from azure.batch.models import ...

  correct:

  from azure.batch import models

  Models are typically exposed directly under the `azure.batch` namespace for convenience.
• DefaultAzureCredential

  from azure.identity import DefaultAzureCredential

  The standard credential type for authenticating with Azure services using Microsoft Entra ID.
• SharedKeyCredentials

  from azure.batch.batch_auth import SharedKeyCredentials

  Used for shared key authentication, though Microsoft Entra ID is now recommended.

Quickstart

This quickstart demonstrates how to instantiate `BatchServiceClient` using the recommended `DefaultAzureCredential` from `azure-identity`. It retrieves the Batch account URL from an environment variable and then lists the existing pools. For shared key authentication, an alternative commented-out section is provided.

import os
from azure.batch import BatchServiceClient
from azure.identity import DefaultAzureCredential

# Retrieve Batch account details from environment variables
batch_account_url = os.environ.get("AZURE_BATCH_ACCOUNT_URL", "https://<your-batch-account>.westus.batch.azure.com")

# Authenticate using DefaultAzureCredential (recommended for Azure AD)
# This will attempt to authenticate via environment variables, managed identity, etc.
try:
    credential = DefaultAzureCredential()
    batch_client = BatchServiceClient(credential, batch_url=batch_account_url)
    
    # Example: List existing pools
    pools = batch_client.pool.list()
    print(f"Successfully connected to Azure Batch. Found {len(pools)} pools.")
    for pool in pools:
        print(f"  - Pool ID: {pool.id}, VM Size: {pool.vm_size}")

except Exception as e:
    print(f"Error connecting to Azure Batch: {e}")
    print("Please ensure AZURE_BATCH_ACCOUNT_URL is set and your environment is authenticated (e.g., via Azure CLI).")

# For shared key authentication (less recommended, but available):
# batch_account_name = os.environ.get("AZURE_BATCH_ACCOUNT_NAME", "<your-batch-account-name>")
# batch_account_key = os.environ.get("AZURE_BATCH_ACCOUNT_KEY", "<your-batch-account-key>")
# if batch_account_name and batch_account_key:
#     from azure.batch.batch_auth import SharedKeyCredentials
#     creds = SharedKeyCredentials(batch_account_name, batch_account_key)
#     batch_client_shared_key = BatchServiceClient(creds, batch_url=batch_account_url)
#     print("Successfully connected with Shared Key credentials.")