v1 で Azure Kubernetes Service クラスターを作成してアタッチする

  • [アーティクル]

適用対象:Python SDK azureml v1

適用対象:Azure CLI ML 拡張機能 v1

重要

この記事では、CLI と SDK v1 を使用して Azure Kubernetes Service クラスターを作成またはアタッチする方法について説明します。これは、現在レガシ機能と見なされています。 v2 に推奨される方法を使用して Azure Kubernetes Service クラスターをアタッチするには、「v2 での Kubernetes コンピューティング ターゲットの概要」を参照してください。

Azure Machine Learning では、トレーニング済みの機械学習モデルを Azure Kubernetes Service にデプロイできます。 ただし、最初に Azure Machine Learning ワークスペースから Azure Kubernetes Service (AKS) クラスターを作成するか、既存の AKS クラスターをアタッチする必要があります。 この記事では、クラスターの作成とアタッチの両方について説明します。

前提条件

  • Azure Machine Learning ワークスペース。 詳細については、Azure Machine Learning ワークスペースの作成に関するページをご覧ください。

  • Machine Learning サービス向けの Azure CLI 拡張機能 (v1)、Azure Machine Learning Python SDK、または Azure Machine Learning Visual Studio Code 拡張機能。

    重要

    この記事の Azure CLI コマンドの一部では、Azure Machine Learning 用に azure-cli-ml、つまり v1 の拡張機能を使用しています。 v1 拡張機能のサポートは、2025 年 9 月 30 日に終了します。 その日付まで、v1 拡張機能をインストールして使用できます。

    2025 年 9 月 30 日より前に、ml (v2) 拡張機能に移行することをお勧めします。 v2 拡張機能の詳細については、Azure ML CLI 拡張機能と Python SDK v2 に関するページを参照してください。

  • Azure Virtual Network を使用して Azure Machine Learning ワークスペースと AKS クラスター間の通信をセキュリティで保護する場合、ワークスペースとその関連リソース (ストレージ、キー コンテナー、Azure Container Registry) には、AKS クラスターの VNET と同じ VNET 内にプライベート エンドポイントまたはサービス エンドポイントが必要です。 チュートリアルに従って、セキュリティで保護されたワークスペースを作成し、それらのプライベート エンドポイントまたはサービス エンドポイントを VNET に追加してください。

制限事項

  • AKS は、Azure Machine Learning ワークスペース内の単一のコンピューティング ターゲットとしてのみ作成またはアタッチできます。 1 つの AKS に対する複数のアタッチメンはサポートされていません。

  • Basic Load Balancer (BLB) ではなく Standard Load Balancer (SLB) をクラスターにデプロイする必要がある場合は、AKS ポータル、CLI、または SDK でクラスターを作成し、Azure Machine Learning ワークスペースにアタッチしてください。

  • パブリック IP アドレスの作成を制限する Azure Policy がある場合、AKS クラスターの作成は失敗します。 AKS では、エグレス トラフィックにパブリック IP が必要です。 エグレス トラフィックに関する記事では、いくつかの完全修飾ドメイン名を除き、パブリック IP を介したクラスターからのエグレス トラフィックをロックダウンする方法についても説明されています。 パブリック IP を有効にするには、次の 2 つの方法があります。

    Azure Machine Learning コントロール プレーンからこのパブリック IP への通信はありません。 これはデプロイのため、AKS コントロール プレーンと通信します。

  • AKS クラスターを接続するには、操作を実行するサービス プリンシパル/ユーザーに、クラスターを含む Azure リソース グループで所有者または共同作成者 Azure ロールベースのアクセス制御 (Azure RBAC) ロールを割り当てる必要があります。 サービス プリンシパル/ユーザーは、クラスターの Azure Kubernetes Service クラスター管理者ロールに割り当てられている必要があります。

  • API サーバーへのアクセスが有効な認可済みの IP 範囲を持つ AKS クラスターをアタッチする場合は、AKS クラスターの Azure Machine Learning コントロール プレーンの IP 範囲を有効にします。 Azure Machine Learning コントロール プレーンは、ペアになっているリージョンにまたがってデプロイされ、AKS クラスター上に推論ポッドをデプロイします。 API サーバーにアクセスできない場合、推論ポッドをデプロイすることはできません。 AKS クラスターで IP 範囲を有効にする場合、ペアになっているリージョンの両方に対して IP 範囲を使用します。

    承認済みの IP 範囲は、Standard Load Balancer でのみ機能します。

  • (Azure Private Link を使用して) プライベート AKS クラスターを使用する場合は、最初にクラスターを作成してから、ワークスペースにそれをアタッチする必要があります。 詳細については、「プライベート Azure Kubernetes Service クラスターを作成する」を参照してください。

  • パブリックの完全修飾ドメイン名 (FQDN) とプライベート AKS クラスターを使用することは Azure Machine Learning ではサポートされていません。

  • AKS クラスターのコンピューティング名は、Azure Machine Learning ワークスペース内で一意である必要があります。 アルファベット文字、数字、ダッシュを含めることができます。 先頭にはアルファベット文字、末尾にはアルファベット文字または数字を使用する必要があり、長さは 3 ～ 24 文字にする必要があります。

  • GPU ノードまたは FPGA ノード (または特定の SKU) にモデルをデプロイする場合は、特定の SKU でクラスターを作成する必要があります。 既存のクラスターにセカンダリ ノード プールを作成し、そのセカンダリ ノード プールにモデルをデプロイすることはサポートされていません。

  • クラスターを作成またはアタッチするときに、開発テストまたは運用のためにクラスターを作成するかどうかを選択できます。 運用のためではなく、開発、検証、テストのための AKS クラスターを作成する場合は、クラスターの目的を開発テストに設定します。 クラスターの目的を指定しない場合は、運用クラスターが作成されます。

    重要

    開発テスト クラスターは、運用レベルのトラフィックに適していないため、推論時間が長くなる可能性があります。 開発/テスト クラスターでは、フォールト トレランスも保証されません。

  • クラスターを運用に使用する場合は、クラスターを作成またはアタッチするときに、少なくとも 3 つのノードが含まれている必要があります。 dev-test クラスターの場合は、少なくとも 1 つのノードを含める必要があります。

  • Azure Machine Learning SDK では、AKS クラスターのスケーリングのサポートは提供されません。 クラスター内のノードをスケーリングするには、Azure Machine Learning Studio 内でご自分の AKS クラスターの UI を使用します。 クラスターの VM サイズではなく、ノード数のみを変更できます。 AKS クラスターにおけるノードのスケーリングの詳細については、次の記事を参照してください。

  • YAML 構成を使用してクラスターを直接更新しないでください。 Azure Kubernetes Services では YAML 構成による更新がサポートされていますが、Azure Machine Learning のデプロイでは変更が上書きされます。 上書きされない YAML フィールドは、"要求の制限" と "CPU とメモリ" の 2 つだけです。

  • Azure Machine Learning スタジオ UI、SDK、または CLI 拡張機能を使用して AKS クラスターを作成することは、べき等ではありません。 再度リソースを作成しようとすると、同じ名前を持つクラスターが既に存在するというエラーが発生します。

    • Azure Resource Manager テンプレートと Microsoft.MachineLearningServices/workspaces/computes リソースを使用して AKS クラスターを作成することも、べき等ではありません。 再度テンプレートを使用して既存のリソースを更新しようとすると、同じエラーが発生します。

Azure Kubernetes Service のバージョン

Azure Kubernetes Service では、さまざまな Kubernetes バージョンを使用してクラスターを作成できます。 使用可能なバージョンの詳細については、「Azure Kubernetes Service (AKS) でサポートされている Kubernetes のバージョン」を参照してください。

次のいずれかの方法を使用して Azure Kubernetes Service クラスターを作成する場合、作成されるクラスターの"バージョンを選択することはできません"。

  • Azure Machine Learning Studio、または Azure portal の Azure Machine Learning セクション。
  • Azure CLI 向けの Machine Learning 拡張機能。
  • Azure Machine Learning SDK。

これらの方法で AKS クラスターを作成するには、クラスターの既定のバージョンを使用します。 Kubernetes の新しいバージョンが利用可能になると、"既定のバージョンは時間とともに変化します"。

既存の AKS クラスターをアタッチする場合、現在サポートされているすべての AKS バージョンがサポートされています。

重要

Azure Kubernetes Service では、Blobfuse FlexVolume ドライバー (バージョン <=1.16 の場合) および Blob CSI driver (バージョン >=1.17 の場合) が使用されます。 そのため、クラスターのバージョンに合った正しい blobfuse 方式にデプロイするためには、クラスターのアップグレード後、Web サービスを更新または再デプロイすることが重要です。

Note

サポートが終了した古いクラスターがあるエッジ ケースがある場合があります。 この場合、アタッチ操作を行うとエラーが返され、現在サポートされているバージョンが一覧表示されます。

プレビュー バージョンをアタッチできます。 プレビュー段階の機能はサービス レベル アグリーメントなしで提供されており、運用環境のワークロードに使用することはお勧めできません。 特定の機能はサポート対象ではなく、機能が制限されることがあります。 プレビュー バージョンの使用のサポートは制限される場合があります。 詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。

使用可能なバージョンと既定のバージョン

AKS の使用可能なバージョンと既定のバージョンを確認するには、Azure CLI コマンド az aks get-versions を使用します。 たとえば、次のコマンドは、米国西部リージョンで使用可能なバージョンを返します。

az aks get-versions -l westus -o table

このコマンドの出力は次のテキストのようになります。

KubernetesVersion    Upgrades
-------------------  ----------------------------------------
1.18.6(preview)      None available
1.18.4(preview)      1.18.6(preview)
1.17.9               1.18.4(preview), 1.18.6(preview)
1.17.7               1.17.9, 1.18.4(preview), 1.18.6(preview)
1.16.13              1.17.7, 1.17.9
1.16.10              1.16.13, 1.17.7, 1.17.9
1.15.12              1.16.10, 1.16.13
1.15.11              1.15.12, 1.16.10, 1.16.13

Azure Machine Learning でクラスターを作成するときに使用される既定のバージョンを確認するには、--query パラメーターを使用して既定のバージョンを選択します。

az aks get-versions -l westus --query "orchestrators[?default == `true`].orchestratorVersion" -o table

このコマンドの出力は次のテキストのようになります。

Result
--------
1.16.13

利用可能なバージョンをプログラムで確認するには、Container Service Client - List Orchestrators REST API を使用します。 使用可能なバージョンを見つけるには、orchestratorType が Kubernetes になっているエントリを確認します。 関連付けられている orchestrationVersion エントリには、ワークスペースにアタッチできるバージョンが含まれています。

Azure Machine Learning を使用してクラスターを作成するときに使用される既定のバージョンを見つけるには、orchestratorType が Kubernetes、default が true になっているエントリを見つけます。 関連付けられている orchestratorVersion 値が既定のバージョンです。 次の JSON スニペットは、エントリの例を示しています。

...
 {
        "orchestratorType": "Kubernetes",
        "orchestratorVersion": "1.16.13",
        "default": true,
        "upgrades": [
          {
            "orchestratorType": "",
            "orchestratorVersion": "1.17.7",
            "isPreview": false
          }
        ]
      },
...

新しい AKS クラスターを作成する

推定所要時間: 約 10 分。

AKS クラスターの作成またはアタッチは、お使いのワークスペースでの 1 回限りのプロセスです。 複数のデプロイでこのクラスターを再利用できます。 クラスターまたはそれを含むリソース グループを削除した場合、次回デプロイする必要があるときに、新しいクラスターを作成する必要があります。 複数の AKS クラスターをワークスペースに接続できます。

次の例では、SDK と CLI を使用して新しい AKS クラスターを作成する方法を示します。

適用対象:Python SDK azureml v1

from azureml.core.compute import AksCompute, ComputeTarget

# Use the default configuration (you can also provide parameters to customize this).
# For example, to create a dev/test cluster, use:
# prov_config = AksCompute.provisioning_configuration(cluster_purpose = AksCompute.ClusterPurpose.DEV_TEST)
prov_config = AksCompute.provisioning_configuration()

# Example configuration to use an existing virtual network
# prov_config.vnet_name = "mynetwork"
# prov_config.vnet_resourcegroup_name = "mygroup"
# prov_config.subnet_name = "default"
# prov_config.service_cidr = "10.0.0.0/16"
# prov_config.dns_service_ip = "10.0.0.10"
# prov_config.docker_bridge_cidr = "172.17.0.1/16"

aks_name = 'myaks'
# Create the cluster
aks_target = ComputeTarget.create(workspace = ws,
                                    name = aks_name,
                                    provisioning_configuration = prov_config)

# Wait for the create process to complete
aks_target.wait_for_completion(show_output = True)

この例で使われているクラス、メソッド、パラメーターの詳細については、次のリファレンス ドキュメントをご覧ください。

既存の AKS クラスターをアタッチする

推定所要時間: 約 5 分です。

Azure サブスクリプションに AKS クラスターが既にある場合は、ワークスペースで使用できます。

ヒント

既存の AKS クラスターは、Azure Machine Learning ワークスペースと異なる Azure リージョンに存在してもかまいません。

警告

同じ AKS クラスターに対して複数のアタッチメントを同時に作成することは避けてください。 たとえば、2 つの異なる名前を使用して 1 つの AKS クラスターをワークスペースにアタッチしたり、1 つの AKS クラスターを別のワークスペースにアタッチしたりすることです。 新しい各アタッチメントによって前の既存のアタッチメントが破損し、予測できないエラーが発生します。

TLS やその他のクラスター構成設定を変更するためなど、AKS クラスターを再度アタッチしたい場合は、AksCompute.detach() を使用して既存のアタッチメントを先に削除しておいてください。

Azure CLI または portal を使用した AKS クラスターの作成の詳細については、次の記事をご覧ください。

次の例では、既存の AKS クラスターをワークスペースにアタッチする方法を示します。

適用対象:Python SDK azureml v1

from azureml.core.compute import AksCompute, ComputeTarget
# Set the resource group that contains the AKS cluster and the cluster name
resource_group = 'myresourcegroup'
cluster_name = 'myexistingcluster'

# Attach the cluster to your workgroup. If the cluster has less than 12 virtual CPUs, use the following instead:
# attach_config = AksCompute.attach_configuration(resource_group = resource_group,
#                                         cluster_name = cluster_name,
#                                         cluster_purpose = AksCompute.ClusterPurpose.DEV_TEST)
attach_config = AksCompute.attach_configuration(resource_group = resource_group,
                                         cluster_name = cluster_name)
aks_target = ComputeTarget.attach(ws, 'myaks', attach_config)

# Wait for the attach process to complete
aks_target.wait_for_completion(show_output = True)

この例で使われているクラス、メソッド、パラメーターの詳細については、次のリファレンス ドキュメントをご覧ください。

TLS 終端を使用した AKS クラスターの作成またはアタッチ

AKS クラスターを作成またはアタッチするときに、 AksCompute.provisioning_configuration() および AksCompute.attach_configuration() の構成オブジェクトを使用して TLS 終端を有効にすることができます。 どちらのメソッドからも、enable_ssl メソッドを持つ構成オブジェクトが返されます。この enable_ssl メソッドを使用して TLS を有効にすることができます。

次の例は、内部で Microsoft 証明書を使用して、TLS 証明書の自動生成と構成で TLS 終端を有効にする方法を示しています。

適用対象:Python SDK azureml v1

   from azureml.core.compute import AksCompute, ComputeTarget
   
   # Enable TLS termination when you create an AKS cluster by using provisioning_config object enable_ssl method

   # Leaf domain label generates a name using the formula
   # "<leaf-domain-label>######.<azure-region>.cloudapp.azure.com"
   # where "######" is a random series of characters
   provisioning_config.enable_ssl(leaf_domain_label = "contoso")
   
   # Enable TLS termination when you attach an AKS cluster by using attach_config object enable_ssl method

   # Leaf domain label generates a name using the formula
   # "<leaf-domain-label>######.<azure-region>.cloudapp.azure.com"
   # where "######" is a random series of characters
   attach_config.enable_ssl(leaf_domain_label = "contoso")

次の例は、カスタム証明書とカスタム ドメイン名を使用して TLS 終端を有効にする方法を示しています。 カスタム ドメインと証明書を使用する場合は、スコアリング エンドポイントの IP アドレスを指すように DNS レコードを更新する必要があります。「DNS を更新する」を参照してください。

適用対象:Python SDK azureml v1

   from azureml.core.compute import AksCompute, ComputeTarget

   # Enable TLS termination with custom certificate and custom domain when creating an AKS cluster
   
   provisioning_config.enable_ssl(ssl_cert_pem_file="cert.pem",
                                        ssl_key_pem_file="key.pem", ssl_cname="www.contoso.com")
    
   # Enable TLS termination with custom certificate and custom domain when attaching an AKS cluster

   attach_config.enable_ssl(ssl_cert_pem_file="cert.pem",
                                        ssl_key_pem_file="key.pem", ssl_cname="www.contoso.com")

Note

AKS クラスター上のモデルのデプロイをセキュリティで保護する方法の詳細については、「TLS を使用して Azure Machine Learning による Web サービスをセキュリティで保護する」を参照してください。

プライベート IP で内部ロード バランサーを使用する AKS クラスターの作成または接続

AKS クラスターを作成または接続するときに、内部ロード バランサーを使用するようにクラスターを構成できます。 内部ロード バランサーを使用すると、AKS へのデプロイに関するスコア付けエンドポイントには、仮想ネットワーク内でプライベート IP が使用されます。 次のコード スニペットは、AKS クラスターの内部ロード バランサーを構成する方法を示しています。

適用対象:Python SDK azureml v1

内部ロード バランサーを使用する AKS クラスターを作成するには、load_balancer_type と load_balancer_subnet パラメーターを使用します。

from azureml.core.compute.aks import AksUpdateConfiguration
from azureml.core.compute import AksCompute, ComputeTarget

# When you create an AKS cluster, you can specify Internal Load Balancer to be created with provisioning_config object
provisioning_config = AksCompute.provisioning_configuration(load_balancer_type = 'InternalLoadBalancer')

# Create the cluster
aks_target = ComputeTarget.create(workspace = ws,
                                name = aks_name,
                                provisioning_configuration = provisioning_config)

# Wait for the create process to complete
aks_target.wait_for_completion(show_output = True)

重要

AKS クラスターが内部ロード バランサーを使用して構成されている場合、Microsoft 提供の証明書を使用することはサポートされていません。TLS を有効にするにはカスタム証明書を使用する必要があります。

Note

推論環境をセキュリティで保護する方法の詳細については、Azure Machine Learning 推論環境のセキュリティ保護に関する記事を参照してください。

AKS クラスターをデタッチする

ワークスペースからクラスターをデタッチするには、次のいずれかの方法を使用します。

警告

Azure Machine Learning スタジオ、SDK、または機械学習のための Azure CLI 拡張機能を使用して AKS クラスターをデタッチしても、AKS クラスターは削除されません。 クラスターを削除する方法については、AKS と共に Azure CLI を使用する方法に関するページをご覧ください。

適用対象:Python SDK azureml v1

aks_target.detach()

トラブルシューティング

クラスターの更新

Azure Kubernetes Service クラスターにインストールされている Azure Machine Learning コンポーネントの更新プログラムは、手動で適用する必要があります。

これらの更新プログラムを適用するには、Azure Machine Learning ワークスペースからクラスターをデタッチしてから、クラスターをワークスペースに再アタッチします。

適用対象:Python SDK azureml v1

compute_target = ComputeTarget(workspace=ws, name=clusterWorkspaceName)
compute_target.detach()
compute_target.wait_for_completion(show_output=True)

クラスターをワークスペースに再アタッチする前に、まず azureml-fe 関連リソースを削除する必要があります。 クラスターにアクティブなサービスがない場合は、次のコードを使用して azureml-fe 関連リソースを削除できます。

kubectl delete sa azureml-fe
kubectl delete clusterrole azureml-fe-role
kubectl delete clusterrolebinding azureml-fe-binding
kubectl delete svc azureml-fe
kubectl delete svc azureml-fe-int-http
kubectl delete deploy azureml-fe
kubectl delete secret azuremlfessl
kubectl delete cm azuremlfeconfig

クラスターで TLS が有効な場合は、クラスターを再アタッチするときに TLS/SSL 証明書と秘密キーを指定する必要があります。

適用対象:Python SDK azureml v1

attach_config = AksCompute.attach_configuration(resource_group=resourceGroup, cluster_name=kubernetesClusterName)

# If SSL is enabled.
attach_config.enable_ssl(
    ssl_cert_pem_file="cert.pem",
    ssl_key_pem_file="key.pem",
    ssl_cname=sslCname)

attach_config.validate_configuration()

compute_target = ComputeTarget.attach(workspace=ws, name=args.clusterWorkspaceName, attach_configuration=attach_config)
compute_target.wait_for_completion(show_output=True)

TLS/SSL 証明書と秘密キーがなくなった場合、または Azure Machine Learning によって生成された証明書を使用している場合は、kubectl を使用してクラスターに接続し、シークレット azuremlfessl を取得することで、クラスターをデタッチする前にファイルを取得できます。

kubectl get secret/azuremlfessl -o yaml

Note

Kubernetes では、Base64 でエンコードされた形式でシークレットが格納されます。 シークレットの cert.pem コンポーネントと key.pem コンポーネントを attach_config.enable_ssl に提供する前に、Base-64 でデコードする必要があります。

Webservice のエラー

AKS の多くの Webservice エラーは、kubectl を使用してクラスターに接続することでデバッグできます。 AKS クラスターの kubeconfig.json を取得するには、以下を実行します

適用対象:Azure CLI ML 拡張機能 v1

az aks get-credentials -g <rg> -n <aks cluster name>

クラスターをデタッチした後、クラスターにアクティブなサービスが存在しない場合は、再度アタッチする前に azureml-fe 関連リソースを削除してください。

kubectl delete sa azureml-fe
kubectl delete clusterrole azureml-fe-role
kubectl delete clusterrolebinding azureml-fe-binding
kubectl delete svc azureml-fe
kubectl delete svc azureml-fe-int-http
kubectl delete deploy azureml-fe
kubectl delete secret azuremlfessl
kubectl delete cm azuremlfeconfig

ロード バランサーにはパブリック IP を指定しない

AKS クラスターを作成またはアタッチしようとして、要求が拒否されたというメッセージを受け取る場合があります。これは "ロード バランサーにはパブリック IP を指定しない" ためです。 このメッセージは、パブリック IP アドレスでの AKS クラスターの使用を禁止するポリシーを管理者が適用したときに帰されます。

この問題を解決するには、load_balancer_type パラメーターと load_balancer_subnet パラメーターを使用し、クラスターを作成/アタッチします。 詳細については、「内部ロード バランサー (プライベート IP)」を参照してください。

次のステップ