クラスタをアップグレードする

このドキュメントでは、Google Distributed Cloud（GDC）のエアギャップ Kubernetes クラスタの Kubernetes バージョンをアップグレードする方法について説明します。クラスタに最新の Kubernetes の機能と修正を組み込むには、クラスタの定期的なアップグレードを計画する必要があります。

このドキュメントは、組織内の Kubernetes リソースの管理を担当するプラットフォーム管理者グループ内の IT 管理者、セキュリティ エンジニア、ネットワーク管理者などのユーザーを対象としています。詳細については、GDC エアギャップのドキュメントの対象読者をご覧ください。

始める前に

このドキュメントのタスクを完了するには、必要な権限をリクエストして環境を準備する必要があります。

IAM ロールをリクエストする

Kubernetes クラスタをアップグレードするために必要な権限を取得するには、特定のロールが必要です。プロジェクトと組織にスコープ設定されたロールをリクエストする必要があります。

組織のロール

Kubernetes クラスタで使用可能なアップグレード バージョンを一覧表示するには、組織の IAM 管理者に ユーザー クラスタ管理者（user-cluster-admin）ロールの付与を依頼してください。このロールは Namespace にバインドされていません。

標準クラスタを管理していて、プラットフォーム管理者グループからユーザー クラスタ管理者のロールを取得できない場合は、利用可能な Kubernetes アップグレード バージョンのリストを提供するよう依頼する必要があります。

プロジェクトのロール

クラスタのアップグレードを作成、削除、編集、表示するには、プロジェクト IAM 管理者に Standard クラスタ管理者（standard-cluster-admin）ロールの付与を依頼してください。このロールはプロジェクトの名前空間にバインドされます。

環境を準備する

API を使用して Kubernetes クラスタに対してコマンドを実行するには、次のリソースがあることを確認します。

  • gdcloud CLI をダウンロードしてインストールします。

  • kubectl CLI をインストールします。

  • Kubernetes クラスタ名を確認するか、プラットフォーム管理者グループのメンバーにクラスタ名を確認します。

  • これらの手順では、Kubernetes クラスタ名を使用して CLUSTER_NAME を置き換えます。

  • 管理 API サーバーの kubeconfig ファイルにログインして生成します。

  • これらの手順では、管理 API サーバーの kubeconfig パスを使用して MANAGEMENT_API_SERVER を置き換えます。

Kubernetes クラスタをアップグレードする

UserClusterUpgradeRequest API を使用して、既存の Kubernetes クラスタをアップグレードします。

API を使用して Kubernetes クラスタをアップグレードする手順は次のとおりです。

  1. UserClusterMetadata オブジェクトの kubernetesVersion 値を出力して、使用可能な Kubernetes アップグレード バージョンを一覧表示します。

    kubectl --kubeconfig MANAGEMENT_API_SERVER \
    get userclustermetadata -o=custom-columns='TARGET_VERSION:.spec.kubernetesVersion'

    MANAGEMENT_API_SERVER は、管理 API サーバーの kubeconfig ファイルのパスに置き換えます。

    このコマンドは、使用可能な Kubernetes バージョンのリストを返します。

    TARGET_VERSION
1.30.1000-gke.85

  2. クラスタのアップグレード先の Kubernetes バージョンを、前の出力からメモします。次の手順のアップグレード リクエストで指定する targetVersion は、これらの使用可能なバージョンのいずれかである必要があります。

  3. UserClusterUpgradeRequest リソースを作成して、クラスタのアップグレードをリクエストします。

      kubectl --kubeconfig MANAGEMENT_API_SERVER apply -f - <<EOF
  apiVersion: cluster.gdc.goog/v1
  kind: UserClusterUpgradeRequest
  metadata:
    name: CLUSTER_NAME
    namespace: CLUSTER_NAMESPACE
  spec:
    clusterRef:
      name: CLUSTER_NAME
    targetVersion: TARGET_VERSION
  EOF

    次のように置き換えます。

    • MANAGEMENT_API_SERVER: 管理 API サーバーの kubeconfig ファイルのパス。
    • CLUSTER_NAME: アップグレードする Kubernetes クラスタの名前（user-vm-2 など）。
    • CLUSTER_NAMESPACE: Kubernetes クラスタの Namespace。共有クラスタの場合は、platform Namespace を使用します。Standard クラスタの場合は、クラスタのプロジェクト Namespace を使用します。
    • TARGET_VERSION: 前の手順で特定したアップグレードのターゲット バージョン（1.30.1000-gke.85 など）。

    Kubernetes クラスタの平均アップグレード時間は約 20 分です。

  4. UserClusterUpgradeRequest リソースをモニタリングして、クラスタのアップグレードを検証します。

    kubectl --kubeconfig MANAGEMENT_API_SERVER \
    describe userclusterupgraderequest CLUSTER_NAME \
    -n CLUSTER_NAMESPACE

    次のように置き換えます。

    • MANAGEMENT_API_SERVER: 管理 API サーバーの kubeconfig ファイルのパス。
    • CLUSTER_NAME: アップグレードする Kubernetes クラスタの名前（user-vm-2 など）。
    • CLUSTER_NAMESPACE: Kubernetes クラスタの Namespace。共有クラスタの場合は、platform Namespace を使用します。Standard クラスタの場合は、クラスタのプロジェクト Namespace を使用します。

    出力の Spec セクションを確認します。Current Version と Target Version が含まれます。Current Version と Target Version が異なる場合、アップグレードはまだ進行中です。

    Spec:
  ...
  Current Version: 1.29.500-gke.60
  Target Version: 1.30.1000-gke.85
Status:
  Conditions:
  - Message: Upgrade is in progress
    Reason: UpgradeInProgress
    Status: "False"
    Type: Succeeded

    Succeeded 条件のステータスが True で、Current Version が Target Version と一致する場合、アップグレードは完了し、成功しています。

    Succeeded 条件のステータスが False の場合、アップグレードは失敗しています。Kubernetes クラスタのアップグレードに関連するエラーが発生した場合は、インフラストラクチャ オペレーター グループにお問い合わせください。

アップグレード後にクラスタ サブコンポーネントを確認する

Kubernetes クラスタが正常にアップグレードされたら、クラスタのすべてのサブコンポーネントが正常であることを確認することをおすすめします。

クラスタ内のサブコンポーネントの障害を確認します。

  1. ReconciliationError メッセージが表示されるサブコンポーネントがないことを確認します。

    kubectl --kubeconfig MANAGEMENT_API_SERVER \
    get subcomponent -n CLUSTER_NAME -o json | jq -r \
    '.items[] |  select(.status.conditions[]?.reason == "ReconciliationError") |
    select(.status.featureDisabled != true) |  "Sub-Component: \(.metadata.name)
    - \(.status.conditions[]?.message)"'

    出力にサブコンポーネントが返された場合は、インフラストラクチャ オペレーター グループにお問い合わせください。

  2. Reconciling メッセージが表示されるサブコンポーネントがないことを確認します。

    kubectl --kubeconfig MANAGEMENT_API_SERVER \
    get subcomponent -n CLUSTER_NAME -o json | jq -r \
    '.items[] |  select(.status.conditions[]?.reason == "Reconciling") |
    select(.status.featureDisabled != true) | select( "\(.status)" |
    contains("PreinstallPending") | not) | "Sub-Component: \(.metadata.name)
    - \(.status.conditions[]?.message)"'

    コントロール プレーン ノードが 3 つ、ワーカーノードが 3 つの Kubernetes クラスタの場合、アップグレードには約 20 分かかります。20 分経ってもサブコンポーネントが Reconciling 状態のままの場合は、インフラストラクチャ オペレーター グループにお問い合わせください。

次のステップ