Azure Stack Hub で AKS エンジンを使用して Kubernetes クラスターをアップグレードする

[アーティクル]
12/01/2023

AKS エンジンを使用すると、最初に Azure Stack Hub 上のツールを使用してデプロイされた Kubernetes クラスターをアップグレードできます。 AKS エンジンを使用してクラスターを保守できます。メンテナンスタスクは、任意の IaaS システムと同様です。新しい更新プログラムの可用性に注意し、AKS エンジンを使用して適用する必要があります。

クラスターのアップグレード

アップグレードコマンドを実行すると、Kubernetes のバージョンと OS の基本イメージが更新されます。アップグレードコマンドを実行するたびに、クラスターのすべてのノードに対して、AKS エンジンは、使用される aks-engine のバージョンに関連付けられている AKS 基本イメージを使用して新しい VM を作成します。

AKS エンジンバージョン 0.73.0 以降では、コマンドを aks-engine upgrade 使用して、クラスター内のすべてのマスターノードとエージェントノードの通貨を維持できます。

AKS Engine バージョン 0.75.3 以降では、コマンドを aks-engine-azurestack upgrade 使用して、クラスター内のすべてのマスターノードとエージェントノードの通貨を維持できます。

Microsoft ではお客様のクラスターを管理しません。ただし、Microsoft では、クラスターの管理に使用できるツールと VM イメージを用意しています。

デプロイされたクラスターの場合、アップグレードには次の内容が含まれます。

Kubernetes
Azure Stack Hub Kubernetes プロバイダー
基本 OS

運用クラスターをアップグレードする場合は、次の点を考慮してください。

ターゲットクラスターに正しいクラスター仕様 (apimodel.json) とリソースグループを使用していますか?
クライアントコンピューターで AKS エンジンを実行し、アップグレード操作を実行する信頼できるマシンを使用していますか?
バックアップクラスターがあり、それが動作していることを確認します。
可能であれば、Azure Stack Hub 環境内の VM からコマンドを実行して、ネットワークホップと接続障害の可能性を減らします。
サブスクリプションにプロセス全体のための十分な領域があることを確認します。このプロセスでは、プロセス中に新しい VM が割り当てられます。
システムの更新やスケジュールされたタスクは計画されていません。
運用クラスターとまったく同じように構成されたクラスターで段階的なアップグレードをセットアップし、運用クラスターでアップグレードを実行する前に、そこでアップグレードをテストします。

新しい Kubernetes バージョンにアップグレードする手順

Note

aks-engine の新しいバージョンを使用していて、そのイメージがマーケットプレースで利用できる場合は、AKS 基本イメージもアップグレードされます。

次の手順では、最小限の手順でアップグレードを実行します。詳細については、 Kubernetes クラスターのアップグレードに関する記事を参照してください。

まず、アップグレードの対象となるバージョンを特定する必要があります。このバージョンは現在お持ちになっているバージョンによって異なります。そのバージョン値を使用してアップグレードを実行します。ご使用の AKS エンジンでサポートされている Kubernetes のバージョンを一覧表示するには、次のコマンドを実行します。

注意

AKSe バージョン 0.75.3 以降の場合、AKS エンジンのバージョンを取得するコマンドはです aks-engine-azurestack get-versions。
```
aks-engine get-versions --azure-env AzureStackCloud
```
AKS エンジン、AKS 基本イメージ、および Kubernetes バージョンの完全なマッピングについては、「サポートされている AKS エンジンのバージョン」を参照してください。

upgrade コマンドを実行するために必要な情報を収集します。コマンドでは upgrade 、次のパラメーターを使用します。

パラメーター	例	説明
azure-env	AzureStackCloud	AKS エンジンに対して、ターゲットプラットフォームが Azure Stack Hub であることを示すには、`AzureStackCloud` を使用します。
location	local	Azure Stack Hub のリージョン名。 ASDK の場合、リージョンは `local` に設定されます。
resource-group	kube-rg	新しいリソースグループの名前を入力するか、既存のリソースグループを選択します。リソース名は、英数字かつ小文字にする必要があります。
subscription-id	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	サブスクリプション ID を入力します。詳細については、「プランへのサブスクライブ」を参照してください。
api-model	./kubernetes-azurestack.json	クラスター構成ファイルまたは API モデルへのパス。
client-id	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	サービスプリンシパル GUID を入力します。 Azure Stack Hub 管理者がサービスプリンシパルを作成したときにアプリケーション ID として識別されたクライアント ID。
client-secret	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	サービスプリンシパルシークレットを入力します。これは、サービスの作成時に設定するクライアントシークレットです。
identity-system	adfs	省略可能。 Active Directory フェデレーションサービス (AD FS) を使用している場合に、ID 管理ソリューションを指定します。

値を指定して、次のコマンドを実行します。

注意

AKSe バージョン 0.75.3 以降の場合、AKS エンジンをアップグレードするコマンドはです aks-engine-azurestack upgrade。

aks-engine upgrade \
--azure-env AzureStackCloud \
--location <for an ASDK is local> \
--resource-group kube-rg \
--subscription-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--api-model kube-rg/apimodel.json \
--upgrade-version 1.18.15 \
--client-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--client-secret xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--identity-system adfs # required if using AD FS

何らかの理由でアップグレード操作でエラーが発生した場合は、問題に対処した後に upgrade コマンドを再実行できます。 AKS エンジンは、前回失敗した操作を再開します。

OS イメージのみをアップグレードする手順

サポートされている Kubernetes バージョン情報の一覧を確認し、アップグレードを計画している aks-engine と AKS 基本イメージのバージョンがあるかどうかを判断します。 AKS エンジンバージョン 0.73.0 以下の場合は、aks-engine のバージョンを表示するには、を実行します aks-engine version。 AKS エンジンバージョン 0.75.3 以降を使用している場合は、aks-engine のバージョンを表示するには、を実行します aks-engine-azurestack version。
必要に応じて、aks-engine をインストールしたマシンで ./get-akse.sh --version vx.xx.x を実行して AKS エンジンをアップグレードします。x.xx.x は、対象のバージョン情報に置き換えます。
使用する予定の Azure Stack Hub Marketplace で必要な AKS 基本イメージのバージョンを追加するには、社内の Azure Stack Hub オペレーターに依頼します。
既に使用しているものと同じバージョンの Kubernetes を使用し、--force を追加して aks-engine upgrade コマンドを実行します。例については、「アップグレードの強制」を参照してください。

クラスターを OS バージョン Ubuntu 20.04 に更新する手順

AKS エンジンバージョン 0.75.3 以降では、クラスター VM を Ubuntu 18.04 から 20.04 にアップグレードできます。次の手順に従います。

デプロイ中に生成された api-model.json ファイルを探して編集します。これは、aks-engine でのアップグレードまたはスケーリング操作に使用されるのと同じファイルである必要があります。 AKS エンジンバージョン 0.75.3 以降では、を使用します aks-engine-azurestack。
masterProfile と agentPoolProfiles のセクションを見つけ、これらのセクション内で distro の値を aks-ubuntu-20.04 に変更します。
新しい Kubernetes バージョンにアップグレードする手順で行う場合と同様に、api-model.json ファイルを保存し、 aks-engin upgrade コマンドで api-model.json ファイルを使用します。

AKS エンジン v0.70.0 以降でストレージボリュームを使用している場合にクラスターをアップグレードする手順

クラウドプロバイダー for Azure プロジェクト (、ツリー外クラウドプロバイダー、または外部クラウドプロバイダーとも呼ばれますcloud-controller-manager) は、Azure クラウド用の Kubernetes クラウドプロバイダーインターフェイスを実装します。ツリー外実装は、非推奨のツリー内実装に代わる実装です。

Kubernetes v1.21 以降の Azure Stack Hub では、AKS エンジンベースのクラスターではのみを使用 cloud-controller-managerします。そのため、Kubernetes v1.21 以降のクラスターをデプロイするには、API モデル (例) でをにtrue設定orchestratorProfile.kubernetesConfig.useCloudControllerManagerする必要があります。 AKS エンジンのアップグレードプロセスでは、フラグが自動的に useCloudControllerManager 更新されます。

注意

アップグレードに関する考慮事項: Kubernetes クラスターを v1.20 (またはそれ以前のバージョン) から v1.21 (またはそれ以上のバージョン) にアップグレードするプロセスでは、ツリー内ボリュームプロビジョナーに kubernetes.io/azure-disk 依存するワークロードにダウンタイムが発生します。 Kubernetes v1.21 以降にアップグレードする前に、アプリケーションデータの完全バックアップを実行し、クラスターストレージリソース (PV および PVC) を新しいボリュームプロビデターに移行できることを実稼働前環境で検証することを強くお勧めします。 Azure Disk CSI ドライバーに移行する方法については、こちらを参照してください。

ボリュームプロビジョンダー

ツリー内ボリュームプロビジョン機能は、ツリー内クラウドプロバイダーとのみ互換性があります。そのため、v1.21 以降のクラスターには、ユーザーワークロードが永続ストレージに依存している場合は、コンテナーストレージインターフェイス (CSI) ドライバーを含める必要があります。 Azure Stack Hub で利用できるいくつかのソリューションを次に示します。

AKS エンジンは、Azure Stack Hub で CSI ドライバーを既定で有効 にしません 。 CSI ドライバーを必要とするワークロードの場合は、アドオン (Linux 専用クラスター) を明示的に有効azuredisk-csi-driverにするか、を使用Helmしてグラフ (Linux または Windows クラスター) をインストールazuredisk-csi-driverできます。

永続ストレージを Azure Disk CSI ドライバーに移行する

AKS エンジンベースのクラスターを v1.20 (またはそれ以前のバージョン) から v1.21 (またはそれ以降のバージョン) にアップグレードするプロセスでは、このプロビジョニング機能がクラウドプロバイダー for Azure の一部ではされていないため、ツリー内ボリュームプロビジョナーにkubernetes.io/azure-disk依存するワークロードにダウンタイムが発生します。

基になる Azure ディスクに保持されているデータを保持する必要がある場合は、クラスターのアップグレードプロセスが完了したら、次の追加の手順が必要です。

1. Azure Disk CSI ドライバーを手動でインストールする

次のスクリプトでは、を使用 Helm して Azure Disk CSI ドライバーをインストールします。

DRIVER_VERSION=v1.10.0
helm repo add azuredisk-csi-driver https://raw.githubusercontent.com/kubernetes-sigs/azuredisk-csi-driver/master/charts
helm install azuredisk-csi-driver azuredisk-csi-driver/azuredisk-csi-driver \
  --namespace kube-system \
  --set cloud=AzureStackCloud \
  --set controller.runOnMaster=true \
  --version ${DRIVER_VERSION}

2. ストレージクラスを置き換える

kube-addon-managerでは、ツリー内ストレージクラス (disk.csi.azure.com) が手動で削除されると、Azure Disk CSI ドライバーストレージクラス (kubernetes.io/azure-disk) が自動的に作成されます。

IN_TREE_SC="default managed-premium managed-standard"

# Delete deprecated "kubernetes.io/azure-disk" storage classes
kubectl delete storageclasses ${IN_TREE_SC}

# Wait for addon manager to create the "disk.csi.azure.com" storage class resources
kubectl get --watch storageclasses

3. 永続ボリュームを再作成する

Azure Disk CSI ドライバーがインストールされ、ストレージクラスが置き換えられたら、次の手順では、Azure Disk CSI ドライバー (または代替 CSI ソリューション) を使用して永続ボリューム (PV) と永続ボリューム要求 (PVC) を再作成します。

これは、これらのリソースが最初にデプロイされた方法に応じて異なる複数ステップのプロセスです。手順の概要は次のとおりです。

移行する PV + PVC ペアを参照するデプロイまたはステートフルセットを削除します (必要に応じてバックアップリソース定義)。
PV の persistentVolumeReclaimPolicy プロパティが value Retain に設定されていることを確認します (例)。
移行する PV + PVC ペアを削除します (必要に応じてリソース定義をバックアップします)。
移行するには、オブジェクトを削除し、元の AzureDisk を参照するオブジェクトをazureDiskcsi追加して、PV のリソース定義を更新します (例)。
PV リソース/秒、PVC リソース/秒 (必要な場合)、最後にデプロイまたはステートフルセットを次の順序で再作成します。

次の移行スクリプトは、テンプレートとして提供されます。

移行スクリプトを実行した後、ポッドが "ボリュームをアタッチまたはマウントできません" というエラーでスタックしている場合は、 Azure Disk CSI ドライバーがインストールされ、ストレージクラスが再作成されたことを確認します。

アップグレードの強制

クラスターを強制的にアップグレードする必要がある場合があります。たとえば、1 日目に最新の Kubernetes バージョンを使用して、切断された環境にクラスターをデプロイするとします。次の日に、Ubuntu が、Microsoft の新しい AKS 基本イメージによってもたらされる脆弱性に対する修正プログラムをリリースします。既にデプロイしたのと同じ Kubernetes バージョンを使用してアップグレードを強制することで、この新しいイメージを適用できます。

注意

AKSe バージョン 0.75.3 以降の場合、AKS エンジンをアップグレードするコマンドはです aks-engine-azurestack upgrade。

aks-engine upgrade \
--azure-env AzureStackCloud   
--location <for an ASDK is local> \
--resource-group kube-rg \
--subscription-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--api-model kube-rg/apimodel.json \
--upgrade-version 1.18.15 \
--client-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--client-secret xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--force

手順については、アップグレードの強制に関するセクションを参照してください。

次のステップ

Azure Stack Hub 上の AKS エンジンについて確認する
AKS エンジンを使用して Azure Stack Hub で Kubernetes クラスターをスケーリングする

Azure Stack Hub で AKS エンジンを使用して Kubernetes クラスターをアップグレードする

クラスターのアップグレード

新しい Kubernetes バージョンにアップグレードする手順

OS イメージのみをアップグレードする手順

クラスターを OS バージョン Ubuntu 20.04 に更新する手順

AKS エンジン v0.70.0 以降でストレージボリュームを使用している場合にクラスターをアップグレードする手順

ボリュームプロビジョンダー

永続ストレージを Azure Disk CSI ドライバーに移行する

1. Azure Disk CSI ドライバーを手動でインストールする

2. ストレージクラスを置き換える

3. 永続ボリュームを再作成する

アップグレードの強制

次のステップ

フィードバック

フィードバック

その他のリソース

Azure Stack Hub で AKS エンジンを使用して Kubernetes クラスターをアップグレードする

クラスターのアップグレード

新しい Kubernetes バージョンにアップグレードする手順

OS イメージのみをアップグレードする手順

クラスターを OS バージョン Ubuntu 20.04 に更新する手順

AKS エンジン v0.70.0 以降でストレージ ボリュームを使用している場合にクラスターをアップグレードする手順

ボリューム プロビジョンダー

永続ストレージを Azure Disk CSI ドライバーに移行する

1. Azure Disk CSI ドライバーを手動でインストールする

2. ストレージ クラスを置き換える

3. 永続ボリュームを再作成する

アップグレードの強制

次のステップ

フィードバック

フィードバック

その他のリソース

AKS エンジン v0.70.0 以降でストレージボリュームを使用している場合にクラスターをアップグレードする手順

ボリュームプロビジョンダー

2. ストレージクラスを置き換える