このページでは、GKE On-Prem をアップグレードする方法について説明します。
ターゲット バージョン
GKE On-Prem バージョン 1.3.2 以降では、同じマイナー リリースまたは次のマイナー リリースに含まれる任意のバージョンに直接アップグレードできます。たとえば、1.3.2 から 1.3.5、または 1.5.2 から 1.6.1 にアップグレードできます。
現在のバージョンが 1.3.2 より古い場合は、まず順次アップグレードを行い、バージョン 1.3.2 にする必要があります。たとえば、1.3.0 から 1.3.2 にアップグレードするには、1.3.0 から 1.3.1 にアップグレードしてから、1.3.1 から 1.3.2 にアップグレードする必要があります。
バージョン 1.3.2 以降から次のマイナー リリースに含まれないバージョンにアップグレードする場合は、現在のバージョンとその目的のバージョンの間にあるマイナー バージョンの 1 つからアップグレードする必要があります。たとえば、バージョン 1.3.2 からバージョン 1.6.1 にアップグレードする場合、直接アップグレードすることはできません。まず、バージョン 1.3.2 からバージョン 1.4.x にアップグレードする必要があります。x は、このマイナー リリースのすべてのパッチリリースを表します。その後、バージョン 1.5.x にアップグレードすると、最終的にバージョン 1.6.1 にアップグレードできます。
アップグレード プロセスの概要
gkeadm
ツールをダウンロードします。gkeadm
のバージョンは、アップグレードのターゲット バージョンと同じにする必要があります。gkeadm
を使用して管理ワークステーションをアップグレードします。管理ワークステーションから、管理クラスタをアップグレードします。
管理ワークステーションから、ユーザー クラスタをアップグレードします。
アップグレード ポリシー
管理クラスタをアップグレードした後:
新しく作成するユーザー クラスタには、管理クラスタと同じバージョンが必要です。
既存のユーザー クラスタをアップグレードする場合は、管理クラスタと同じバージョンにアップグレードする必要があります。
管理クラスタを再度アップグレードする前に、すべてのユーザー クラスタを現在の管理クラスタと同じバージョンにアップグレードする必要があります。
構成ファイルと情報ファイルの場所を探す
現在の管理ワークステーションを作成したときに、gkeadm create config
によって生成された管理ワークステーション構成ファイルに入力しました。このファイルのデフォルト名は admin-ws-config.yaml
です。
現在の管理ワークステーションを作成したときに、gkeadm
によって情報ファイルが作成されています。このファイルのデフォルト名は、現在の管理ワークステーションの名前と同じです。
管理ワークステーションの構成ファイルと情報ファイルを探します。これらのファイルはこのガイドの手順を実施するために必要です。これらのファイルが現在のディレクトリにあり、デフォルトの名前が付いている場合は、gkeadm upgrade admin-workstation
を実行するときにファイルを指定する必要はありません。これらのファイルが別のディレクトリにある場合や、ファイル名を変更した場合は、--config
フラグと --info-file
フラグを使用して指定します。
管理ワークステーションのアップグレード
管理ワークステーションをアップグレードするには、まず gkeadm
ツールの新バージョンをダウンロードし、それを使用して管理ワークステーションの構成をアップグレードします。gkeadm
のバージョンは、アップグレードのターゲット バージョンと一致する必要があります。
gkeadm
のダウンロード
最新バージョンの gkeadm
をダウンロードするには、GKE On-Prem ページの gkeadm のダウンロード手順を行ってください。
管理ワークステーション構成のアップグレード
gkeadm upgrade admin-workstation --config [AW_CONFIG_FILE] --info-file [INFO_FILE]
ここで
[AW_CONFIG_FILE] は、管理ワークステーションの構成ファイルのパスです。ファイルが現在のディレクトリにあり、名前が
admin-ws-config.yaml
の場合、このフラグを省略できます。[INFO_FILE] は情報ファイルのパスです。ファイルが現在のディレクトリにある場合は、このフラグを省略できます。このファイルのデフォルト名は、管理ワークステーションの名前と同じです。
上記のコマンドによって、以下のタスクが実行されます。
現在の管理ワークステーションのホーム ディレクトリにあるすべてのファイルをバックアップします。バックアップ対象には次のファイルが含まれます。
GKE On-Prem 構成ファイル。このファイルのデフォルト名は
config.yaml
です。管理クラスタとユーザー クラスタの kubeconfig ファイル
vCenter サーバーのルート証明書(このファイルにはオーナーの読み取り権限とオーナーの書き込み権限が必要)。
許可リストに登録したサービス アカウントの JSON キーファイル(このファイルにはオーナーの読み取り権限とオーナーの書き込み権限が必要)。
connect-register、connect-agent、logging-monitoring サービス アカウントの JSON キーファイル。
新しい管理ワークステーションを作成し、バックアップされたすべてのファイルを新しい管理ワークステーションにコピーします。
古い管理ワークステーションを削除します。
known_hosts
から古い管理ワークステーションを削除する
管理ワークステーションに静的 IP アドレスがある場合は、管理ワークステーションをアップグレードした後、古い管理ワークステーションを known_hosts
ファイルから削除する必要があります。
known_hosts
から古い管理ワークステーションを削除する:
ssh-keygen -R [ADMIN_WS_IP]
ここで、[ADMIN_WS_IP] は管理ワークステーションの IP アドレスです。
GKE On-Prem 構成ファイルにバンドルパスを設定する
新しい管理ワークステーションで、GKE On-Prem 構成ファイルを開きます。bundlepath
の値を、新しい管理ワークステーション上のバンドル ファイルのパスに設定します。
bundlepath: "/var/lib/gke/bundles/gke-onprem-vsphere-[VERSION]-full.tgz"
ここで、[VERSION] はアップグレードのターゲット バージョンです。
ノード OS イメージと Docker イメージを更新する
新しい管理ワークステーションで、次のコマンドを実行します。
gkectl prepare --config [CONFIG_FILE] [FLAGS]
ここで
[CONFIG_FILE] は、新しい管理ワークステーション上の GKE On-Prem 構成ファイルです。
[FLAGS] は、オプションのフラグのセットです。たとえば、vSphere インフラストラクチャのチェックをスキップする
--skip-validation-infra
フラグを指定できます。
上記のコマンドによって、以下のタスクが実行されます。
必要に応じて、vSphere 環境に新しいノードの OS イメージをコピーし、その OS イメージをテンプレートとしてマークします。
非公開 Docker レジストリを構成した場合は、更新された Docker イメージを非公開 Docker レジストリに push します。
十分な IP アドレスが使用可能であることを確認する
新しい管理ワークステーションで、このセクションの手順を行います。
アップグレードを行う前に、クラスタに使用可能な IP アドレスが十分にあることを確認します。
DHCP
アップグレード中、GKE On-Prem は管理クラスタ内に 1 つの一時ノードを作成し、関連する各ユーザー クラスタ内に 1 つの一時ノードを作成します。DHCP サーバーが、これらの一時ノードに十分な IP アドレスを提供できることを確認してください。詳細については、管理クラスタとユーザー クラスタに必要な IP アドレスをご覧ください。
静的 IP
アップグレード中、GKE On-Prem は管理クラスタ内に 1 つの一時ノードを作成し、関連する各ユーザー クラスタ内に 1 つの一時ノードを作成します。管理クラスタと各ユーザー クラスタに対して、十分な IP アドレスが予約されていることを確認します。クラスタノードより少なくとも 1 つ以上多い IP アドレスを、クラスタごとに予約しておく必要があります。詳細については、静的 IP アドレスの構成をご覧ください。
管理クラスタのノード数を指定します。
kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] get nodes
ここで、[ADMIN_CLUSTER_KUBECONFIG] は管理クラスタの kubeconfig ファイルのパスです。
次に、管理クラスタ用に予約されたアドレスを表示します。
kubectl get cluster --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] -o yaml
出力の reservedAddresses
フィールドに、管理クラスタノード用に予約されている IP アドレスの数が表示されます。たとえば、次の出力は、管理クラスタノード用に 5 つの IP アドレスが予約されていることを示しています。
...
reservedAddresses:
- gateway: 21.0.135.254
hostname: admin-node-1
ip: 21.0.133.41
netmask: 21
- gateway: 21.0.135.254
hostname: admin-node-2
ip: 21.0.133.50
netmask: 21
- gateway: 21.0.135.254
hostname: admin-node-3
ip: 21.0.133.56
netmask: 21
- gateway: 21.0.135.254
hostname: admin-node-4
ip: 21.0.133.47
netmask: 21
- gateway: 21.0.135.254
hostname: admin-node-5
ip: 21.0.133.44
netmask: 21
予約された IP アドレスの数は、管理クラスタ内のノードの数より少なくとも 1 つ以上多い数である必要があります。そうでない場合は、クラスタ オブジェクトを編集して追加のアドレスを予約できます。
クラスタ オブジェクトを開いて編集します。
kubectl edit cluster --kubeconfig [ADMIN_CLUSTER_KUBECONFIG]
reservedAddresses
の下に gateway
、hostname
、ip
、netmask
を記載したブロックを追加します。
各ユーザー クラスタで同じ手順を行います。
ユーザー クラスタ内のノード数を確認するには:
kubectl --kubeconfig [USER_CLUSTER_KUBECONFIG] get nodes
ここで、[USER_CLUSTER_KUBECONFIG] はユーザー クラスタの kubeconfig ファイルのパスです。
ユーザー クラスタ用に予約されたアドレスを表示するには:
kubectl get cluster --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \ -n [USER_CLUSTER_NAME] [USER_CLUSTER_NAME] -o yaml
ここで
[ADMIN_CLUSTER_KUBECONFIG] は、管理クラスタの kubeconfig ファイルのパスです。
[USER_CLUSTER_NAME] は、ユーザー クラスタの名前です。
ユーザー クラスタのクラスタ オブジェクトを編集するには:
kubectl edit cluster --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \ -n [USER_CLUSTER_NAME] [USER_CLUSTER_NAME]
(省略可)新しい vSphere 機能を無効にする
新しい GKE On-Prem バージョンには、特定の VMware vSphere 機能に関する新機能やサポートが含まれています。場合によっては、GKE On-Prem バージョンにアップグレードすると、このような機能が自動的に有効になります。GKE On-Prem のリリースノートで新機能について学びます。GKE On-Prem 構成ファイルに新しい機能が表示されることがあります。
新しい GKE On-Prem バージョンで自動的に有効になり、構成ファイルによって実行される新しい機能を無効にする必要がある場合は、クラスタをアップグレードする前に以下の手順に沿って操作を行います。
アップグレードした管理ワークステーションから、現在の構成ファイルとは異なる名前で新しい構成ファイルを作成します。
gkectl create-config --config [CONFIG_NAME]
新しい構成ファイルを開き、機能のフィールドをメモしておきます。ファイルを閉じます。
現在の構成ファイルを開き、新しい機能のフィールドを追加します。フィールドの値を
false
または同等の値に設定します。構成ファイルを保存します。
クラスタをアップグレードする前に、リリースノートを確認してください。アップグレード後に既存のクラスタの構成を宣言型の方法で変更することはできません。
管理クラスタのアップグレード
新しい管理ワークステーションで、このセクションの手順を行います。
アップグレードのターゲット バージョンは gkeadm
バージョンと同じでなければなりません。
次のコマンドを実行します。
gkectl upgrade admin \ --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \ --config [ADMIN_CLUSTER_CONFIG_FILE] \ [FLAGS]
ここで
[ADMIN_CLUSTER_KUBECONFIG] は、管理クラスタの kubeconfig ファイルです。
[ADMIN_CLUSTER_CONFIG_FILE] は、新しい管理ワークステーション上の GKE On-Prem 管理クラスタの構成ファイルです。
[FLAGS] は、オプションのフラグのセットです。たとえば、vSphere インフラストラクチャのチェックをスキップする
--skip-validation-infra
フラグを指定できます。
ユーザー クラスタのアップグレード
新しい管理ワークステーションで、このセクションの手順を行います。
アップグレードのターゲット バージョンは gkeadm
バージョンと同じでなければなりません。
gkectl
gkectl upgrade cluster \ --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \ --config [USER_CLUSTER_CONFIG_FILE] \ --cluster-name [CLUSTER_NAME] \ [FLAGS]
ここで
[ADMIN_CLUSTER_KUBECONFIG] は、管理クラスタの kubeconfig ファイルです。
[CLUSTER_NAME] は、アップグレードするユーザー クラスタの名前です。
[USER_CLUSTER_CONFIG_FILE] は、新しい管理ワークステーション上の GKE On-Prem ユーザー クラスタの構成ファイルです。
[FLAGS] は、オプションのフラグのセットです。たとえば、vSphere インフラストラクチャのチェックをスキップする
--skip-validation-infra
フラグを指定できます。
Console
ユーザー クラスタは、インストール時または作成後に Google Cloud コンソールに登録できます。Google Cloud コンソールの GKE メニューから、登録済みの GKE On-Prem クラスタと Google Kubernetes Engine クラスタを表示してログインできます。
GKE On-Prem ユーザー クラスタのアップグレードが有効になると、Google Cloud コンソールに通知が表示されます。この通知をクリックすると、使用可能なバージョンのリストとクラスタをアップグレードするために実行できる gkectl
コマンドが表示されます。
Google Cloud Console の GKE メニューに移動します。
ユーザー クラスタの [通知] 列に、[アップグレード可能] があればそれをクリックします。
gkectl upgrade cluster
コマンドをコピーします。管理ワークステーションから、
gkectl upgrade cluster
コマンドを実行します。ここで、[ADMIN_CLUSTER_KUBECONFIG] は管理クラスタの kubeconfig ファイル、[CLUSTER_NAME] はアップグレードするユーザー クラスタの名前です。[USER_CLUSTER_CONFIG_FILE] は、新しい管理ワークステーション上の GKE On-Prem ユーザー クラスタ構成ファイルです。
アップグレードの再開
管理クラスタのアップグレード完了後にユーザー クラスタのアップグレードが中断された場合、--skip-validation-all
フラグを指定して同じアップグレード コマンドを実行することで、そのユーザー クラスタのアップグレードを再開できます。
gkectl upgrade cluster \ --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \ --config [USER_CLUSTER_CONFIG_FILE] \ --cluster-name [CLUSTER_NAME] \ --skip-validation-all
管理クラスタのアップグレードを再開する
管理クラスタのアップグレードは中断しないでください。現時点では、管理クラスタのアップグレードは常に再開できるとは限りません。なんらかの理由で管理クラスタのアップグレードが中断された場合は、サポートにお問い合わせください。
アップグレード後に新しいユーザー クラスタを作成する
管理ワークステーションと管理クラスタをアップグレードした後は、作成する新しいユーザー クラスタのバージョンがアップグレードのターゲット バージョンと同じである必要があります。
既知の問題
以下は、クラスタのアップグレードに関連する既知の問題です。
バージョン 1.1.0-gke.6、1.2.0-gke.6: stackdriver.proxyconfigsecretname
フィールドが削除される
stackdriver.proxyconfigsecretname
フィールドはバージョン 1.1.0-gke.6 で削除されました。フィールドが構成ファイルに存在する場合、GKE On-Prem のプリフライト チェックはエラーを返します。
この問題を回避するには、1.2.0-gke.6 にアップグレードする前に構成ファイルから proxyconfigsecretname
フィールドを削除しておきます。
Stackdriver が古いバージョンを参照する
バージョン 1.2.0-gke.6 以前では、Stackdriver はクラスタ アップグレードの後に構成を更新できないことが報告されています。Stackdriver は以前のバージョンを参照しているため、Stackdriver はテレメトリー パイプラインの最新の機能を受け取ることができません。この問題により、Google サポートによるクラスタのトラブル シューティングが難しくなることがあります。
クラスタを 1.2.0-gke.6 にアップグレードした後、管理クラスタとユーザー クラスタに対して次のコマンドを実行します。
kubectl --kubeconfig=[KUBECONFIG] \ -n kube-system --type=json patch stackdrivers stackdriver \ -p '[{"op":"remove","path":"/spec/version"}]'
ここで、[KUBECONFIG] はクラスタの kubeconfig ファイルへのパスです。
PodDisruptionBudgets を使用するワークロードが中断する
現時点では、クラスタをアップグレードすると、PodDisruptionBudgets(PDB)を使用するワークロードで中断やダウンタイムが発生することがあります。
バージョン 1.2.0-gke.6: アップグレード後に Prometheus と Grafana が無効になる
ユーザー クラスタでは、アップグレード中に Prometheus と Grafana は自動的に無効になります。ただし、構成データと指標データは失われません。管理クラスタでは、Prometheus と Grafana が引き続き有効です。
手順については、GKE On-Prem のリリースノートをご覧ください。
バージョン 1.1.2-gke.0: 削除済みユーザー クラスタノードが vSAN データストアから削除されない
手順については、GKE On-Prem のリリースノートをご覧ください。
バージョン 1.1.1-gke.2: vSAN データストア フォルダ内のデータディスクが削除できる
vSAN データストアを使用している場合は、VMDK を保存するフォルダを作成する必要があります。既知の問題により、フォルダのファイルパスではなく、Universally Unique Identifier(UUID)のパスを vcenter.datadisk
に指定する必要があります。この不一致によりアップグレードが失敗する可能性があります。
手順については、GKE On-Prem のリリースノートをご覧ください。
バージョン 1.0.2-gke.3 からバージョン 1.1.0-gke.6 にアップグレードする: OIDC に関する問題
OpenID Connect(OIDC)が構成されているバージョン 1.0.11、1.0.1-gke.5、1.0.2-gke.3 クラスタは、バージョン 1.1.0-gke.6 にアップグレードできません。この問題は、バージョン 1.1.1-gke.2 で修正されています。
インストール時にバージョン 1.0.11、1.0.1-gke.5、1.0.2-gke.3 のクラスタを OIDC で構成した場合、クラスタをアップグレードできません。代わりに、新しいクラスタを作成する必要があります。
バージョン 1.0.11 からバージョン 1.0.2-gke.3 にアップグレードする
バージョン 1.0.2-gke.3 では、次の OIDC フィールド(usercluster.oidc
)が導入されています。これらのフィールドによって、Google Cloud コンソールからクラスタにログインできるようになります。
usercluster.oidc.kubectlredirecturl
usercluster.oidc.clientsecret
usercluster.oidc.usehttpproxy
OIDC を使用する場合、Google Cloud コンソールからクラスタにログインしない場合でも、clientsecret
フィールドは必須です。OIDC を使用するには、clientsecret
にプレースホルダの値を指定する必要があります。
oidc: clientsecret: "secret"
ノードがアップグレード プロセスを完了できない
追加の中断を許可できない PodDisruptionBudget
オブジェクトが構成されている場合、ノードのアップグレードを繰り返し試行しても、コントロール プレーン バージョンへのアップグレードが失敗する可能性があります。このエラーを回避するには、Deployment
または HorizontalPodAutoscaler
をスケールアップして、PodDisruptionBudget
構成を維持しながらノードをドレインすることをおすすめします。
中断を許可しないすべての PodDisruptionBudget
オブジェクトを表示するには、次を行います。
kubectl get poddisruptionbudget --all-namespaces -o jsonpath='{range .items[?(@.status.disruptionsAllowed==0)]}{.metadata.name}/{.metadata.namespace}{"\n"}{end}'
付録
バージョン 1.1.0-gke.6 で有効になっている VMware DRS ルールについて
バージョン 1.1.0-gke.6 以降、GKE On-Prem はユーザー クラスタのノードに対して VMware Distributed Resource Scheduler(DRS)の反アフィニティ ルールを自動的に作成し、データセンター内の少なくとも 3 つの物理ホストにそれらを分散させます。バージョン 1.1.0-gke.6 以降、この機能は新しいクラスタと既存のクラスタで自動的に有効になります。
アップグレードを行う前に、vSphere 環境が次の条件を満たしていることを確認してください。
- VMware DRS が有効になっていること。VMware DRS には、vSphere Enterprise Plus ライセンス エディションが必要です。DRS を有効にする方法については、クラスタ内の VMware DRS の有効化をご覧ください。
vcenter
フィールドで指定された vSphere ユーザー アカウントにHost.Inventory.EditCluster
権限があること。- 利用可能な物理ホストが少なくとも 3 つあること。
vSphere 環境が上記の条件を満たさない場合でも、ユーザー クラスタをアップグレードできます。ただし、1.3.x から 1.4.x にアップグレードする場合は、反アフィニティ グループを無効にする必要があります。詳細については、GKE On-Prem リリースノートの既知の問題をご覧ください。
ダウンタイム
アップグレード中のダウンタイムについて
リソース | 説明 |
---|---|
管理クラスタ | 管理クラスタが停止しても、ユーザー クラスタのコントロール プレーンとワークロードは、ダウンタイムの原因となった障害の影響を受けない限り引き続き実行されます。 |
ユーザー クラスタのコントロール プレーン | 通常、ユーザー クラスタ コントロール プレーンには目立ったダウンタイムはありません。ただし、Kubernetes API サーバーへの長時間実行の接続が切断され、再確立する必要がある場合があります。この場合、API 呼び出し元は、接続が確立するまで再試行する必要があります。最悪のケースでは、アップグレード中に最大 1 分間のダウンタイムが発生することがあります。 |
ユーザー クラスタノード | アップグレードでユーザー クラスタ ノードの変更が必要な場合、GKE On-Prem はノードをローリング方式で再作成し、これらのノードで実行されている Pod を再スケジュールします。ワークロードへの影響を防ぐには、適切な PodDisruptionBudgets とアンチ アフィニティ ルールを構成します。 |
トラブルシューティング
詳しくは、トラブルシューティングをご覧ください。
新しいノードが作成されたが、正常でない
- 現象
手動負荷分散モードを使用しているときに、新しいノードが自身をユーザー クラスタ コントロール プレーンに登録しません。
- 考えられる原因
ノードの Ingress 検証が有効になり、ノードの起動プロセスがブロックされている可能性があります。
- 解決策
検証を無効にするには、次のコマンドを実行します。
kubectl patch machinedeployment [MACHINE_DEPLOYMENT_NAME] -p '{"spec":{"template":{"spec":{"providerSpec":{"value":{"machineVariables":{"net_validation_ports": null}}}}}}}' --type=merge
gkectl
を使用してクラスタの問題を診断する
クラスタの問題を特定し、クラスタの情報を Google と共有するために、gkectl diagnose
コマンドを使用します。クラスタの問題を診断するをご覧ください。
gkectl
コマンドを冗長モードで実行する
-v5
stderr
に対する gkectl
エラーのロギング
--alsologtostderr
管理ワークステーションで gkectl
ログを見つける
デバッグフラグを渡さない場合でも、次の管理ワークステーション ディレクトリで gkectl
ログを表示できます。
/home/ubuntu/.config/gke-on-prem/logs
管理クラスタで Cluster API ログを見つける
管理コントロール プレーンの起動後に VM が起動しない場合は、管理クラスタの Cluster API コントローラのログを調べてデバッグを試すことができます。
kube-system
Namespace で Cluster API コントローラ Pod の名前を確認します。ここで、[ADMIN_CLUSTER_KUBECONFIG] は管理クラスタの kubeconfig ファイルのパスです。kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] -n kube-system get pods | grep clusterapi-controllers
Pod のログを開きます。ここで、[POD_NAME] は Pod の名前です。必要に応じて、
grep
または同様のツールを使用してエラーを検索します。kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] -n kube-system logs [POD_NAME] vsphere-controller-manager