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

[アーティクル]
10/30/2024

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

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

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

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

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

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

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

Note

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 管理ソリューションを指定します。

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

Note

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 以降でストレージボリュームを使用している場合にクラスターをアップグレードする手順

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

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

Note

アップグレードに関する考慮事項: 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 ドライバーを必要とするワークロードの場合は、azuredisk-csi-driver addon (Linux 専用クラスター) を明示的に有効にするか、Helmを使用してazuredisk-csi-driver グラフ (Linux または Windows クラスター) をインストールすることができます。

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

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

基になる 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では、ツリー内ストレージクラス (kubernetes.io/azure-disk) が手動で削除されると、Azure Disk CSI ドライバーストレージクラス (disk.csi.azure.com) が自動的に作成されます。

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

次の移行 script はテンプレートとして提供されています。

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

アップグレードの強制

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

Note

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 エンジンを使用して 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. ストレージクラスを置き換える