[Red Hat OpenShift on IBM Cloud] OCP のバージョンアップでハマりやすいポイント (2024年冬版)

IBM Cloud で提供されている Red Hat OpenShift on IBM Cloud (RHOIC/ROKS) サービスの利用で避けて通ることをできないのが、 Red Hat OpenShift Container Platform (以下 OCP) のバージョンアップです。すでにサポートが終了している OCP 4.11 もしくは 非推奨化されている OCP 4.12 をご利用の方はそろそろバージョンアップができなくなってしまう (2025/2/26 予定, OCP のソフトウェア製品とはサポート期間が異なる) ので、バージョンアップを計画・実施されている頃と思います。
IBM Cloud コンソールやコマンドラインからマスターノードをバージョンアップさせた後に、ワークロードの特性に応じてワーカーノードを更新するという基本的なやり方は変わらないのですが、OCP 4.12 以降のバージョンのバージョンアップでは IBM Cloud Docs などをよく読まないとハマりやすいポイントがあり、この記事で整理します。

(2025/1/30追記)
これ以外にも問題が発生するパターンが見つかったそうなので、最下部に追加しました。

# バージョンアップの大まかなながれ

Red Hat OpenShift on IBM Cloud サービスではマイナーバージョンを 1 つずつあげていく必要があり、クラスター内のマスターノードと比べてワーカーノードは "-1" のマイナーバージョンでの稼働しかサポートされません。ソフトウェア製品（IBM Cloud 上での利用の場合 IPI/UPI でインストールしたケース）の OCP のように ELS to ELS でバージョンアップできるといいのですが、まだ対応していません。そのため、例えば OCP 4.12 から OCP 4.14 にバージョンアップしたい場合には以下のようにバージョンアップしていく必要があります。

- マスターノードを OCP 4.12 から OCP 4.13 にバージョンアップ
- ワーカーノードを OCP 4.12 から OCP 4.13 にバージョンアップ
- マスターノードを OCP 4.13 から OCP 4.14 にバージョンアップ
- ワーカーノードを OCP 4.13 から OCP 4.14 にバージョンアップ

とても簡単な手続きのように見えますが、廃止予定の API の利用有無の確認、サービスの継続的な提供の要否や ODF や Portworx のような SDS の利用、永続的に保持する必要があるデータやステートフルなアプリケーションなどの利用の有無を勘案して細かく手順を準備する必要がありますが、ケース・バイ・ケースで対応すべき内容が異なるので、それらは各自でご検討ください。今回のハマりやすいポイントはそれ以外の場所で発生するものを説明します。

# ハマりやすいポイント

<h3>その1 OCP 4.12 から OCP 4.13 へのマスターノード(クラスター)のバージョンアップ後に API サーバー や GUI コンソールにアクセスできない</h3>
<B>(発生条件) VPC 上で稼働するクラスター かつ マスターノードのエンドポイントとしてプライベートのみを選択している場合</B>

条件に該当するクラスターの場合、マスターノード/ API サーバーにアクセスの際、OCP 4.13を除く全てのバージョンではデフォルトの構成で Cloud Service Endpoint と呼ばれる IBM Cloud 内部からのみアクセスできるプライベートネットワーク（IP アドレスのレンジが 166.8.0.0/14）に存在するマスターノードへアクセスします。ところが、OCP 4.13 ではデフォルトの構成でワーカーノードと同じ VPC の内部に設置される Virtual Private Endpoint(VPE) を通じてマスターノードへアクセスします。単にアクセスするだけでなく、VPC の内部から参照されるプライベート DNS にもアクセスできる必要があります。そのため、それ以前のバージョンでアクセスできていた環境から、マスターノード/ API サーバーにアクセスできないケースが多く発生します。また IBM Cloud Shell からアクセスすることもできないので、バージョンアップ後にアクセスできるように対応する必要があります。

<B>(簡単な対応策)バージョンアップ後にアクセス方式を OCP 4.12 までの方式に戻す</B>
OCP 4.13 のみデフォルトが異なる マスターノード/API サーバーを他のバージョンに合わせるか、OCP 4.13 で導入されたアクセス方式でアクセスできるようにネットワークの構成を変更するかの 2 択です。後者の場合、OCP 4.14以降でこちらの方法を引き続き利用することも可能です。

おそらく前者の方が簡単かつリスクの小さい方法です。
`ibmcloud oc cluster master console-oauth-access` コマンドを実行して、コンソールや API サーバーへアクセスする方法を他のバージョンのデフォルト構成と同じにします。コマンドを実行するだけなのですが、マスターノードのリフレッシュ(再構成)が同時に実施されるため、1 時間程度の時間を要します。

新しい方式への対応はネットワークレイヤーの構成変更を行う必要があるので、それらを計画し実行するのには多大な労力を要するかと思います。それらと比べてこの方法はネットワークの構成変更は不要で、予め時間を確保して計画いただければ最も簡単かつリスクが低い方法となります。


実施するコマンド

```
ibmcloud oc cluster master console-oauth-access set --cluster "<cluster id>" --type legacy -f
```

<hr>
<h3>その2 クラスター/マスターノードのバージョンアップを開始した後、しばらくするとエラーになる</h3>
<B>(発生条件) すべてのクラスターの以下のバージョンアップ<br />
- OCP 4.13 から OCP 4.14へのクラスター/マスターノードのバージョンアップ<br />
- OCP 4.15 から OCP 4.16へのクラスター/マスターノードのバージョンアップ<br />
- 以降のバージョンアップでも同じように発生する可能性あり</B>

OpenShift は Kubernetes の商用ディストリビューションの一つですが、 Kubernetes ではバージョンアップとともに API の非推奨化や廃止が行われています。OpenShift でも同様にバージョンアップの際には API の非推奨化や廃止が行われます。
例えば OCP 4.13 から OCP 4.14 へのバージョンアップでは OCP 4.14 (Kubernetes 1.27) において非推奨化および廃止された API などを確認する必要があるのですが、確認を行ったということを明示的に示すことが求められるようになりました。
同様に OCP 4.15 から OCP 4.16 へのバージョンアップでも同様の確認を行ったことを明確に表明することが求められます。


<B>(対応策)決められたバージョンアップ前の確認コマンドを実行する</B>

管理者によるAPIの変更を確認したことの表明は OpenShift クラスターにログインして、oc コマンドを発行することで実施できます。特に OCP 4.12 から OCP 4.14 へ連続してバージョンアップする場合には はまりやすいポイントその 1 で説明したエンドポイントの変更を行わないとクラスターにログインすらできないので、その1の変更を行った後にその2の対応を行う必要があり、作業に十分な時間を確保して計画する必要があります。

コマンドの実行は OCP の `cluster-admin` (IBM Cloud IAM では `Kubernetes Service` に対する`サービス役割`の`管理者 (Manager)` )権限の役割を持つユーザーが以下のコマンドを実行します。

```4.13 > 4.14
oc -n openshift-config patch cm admin-acks --patch '{"data":{"ack-4.13-kube-1.27-api-removals-in-4.14":"true"}}' --type=merge
```

```4.15 > 4.16
oc -n openshift-config patch cm admin-acks --patch '{"data":{"ack-4.15-kube-1.29-api-removals-in-4.16":"true"}}' --type=merge
```

おそらく今後も OpenShift/Kubernetes の API の変更に伴い同様の手続きが必要になると考えられますので、バージョンアップを行う際にはこの確認手順も忘れずに含めるようにしてください。

<hr>
<h3>その3 OCP 4.14 から OCP 4.15 へのマスターノード(クラスター)のバージョンアップ後に 同じVPC内からObject StorageやVPCサービスのエンドポイントなどにアクセスできなくなる</h3>
<B>(発生条件) VPC上で稼働するクラスター</B>


OCP 4.13 以前のクラスターでは Worker Node を稼働させている VPC から 依存関係にある IBM Cloud 内のいくつかのサービスにアクセスする際 IaaS/PaaS サービス用の共用のプライベート・エンドポイントを利用してアクセスします。具体的には Object Storage、Virtual Private Cloud (VPC)、Container Registryの各サービスの呼び出しにプライベート・エンドポイントを利用しており、その様子を下図に図示しました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/83689/f4ddef99-0c6d-0048-0418-5685f040d2a2.png)

クラスターの OCP バージョンを 4.13 から 4.14 および 4.14 から 4.15 に上げるタイミングで、プライベート・エンドポイントを利用していた各サービスへの呼び出しが Virtual Private Endpoint(VPE) を利用した呼び出しに変更されます。各バージョンで使用するエンドポイントとIPアドレスのレンジについては表にまとめました。もともとワーカーノードとマスターノードの通信は OCP 4.12 でも VPE を通じて行われますが、それと同じように VPC のサブネットに割り当てられている IP アドレスのレンジからそれぞれのサービス用の VPE に対して IP アドレスが払い出されて使用されます。またこれらは VPC から利用するプライベート DNS のエントリーとして登録され、各エンドポイントのホスト名はバージョンアップの前後で変わらないものの、名前を解決した際の IP アドレスが共用の IP アドレスから VPC 内の固有の IP アドレスに変更されます。この様子を下図に図示しました。オレンジの点線部分が赤の実線のような形に変更されます。また、以降の図において、Red Hat OpenShift on IBM Cloudサービス (RHOIC/ROKS) 用のエンドポイントは簡単のため省略します。



| 機能/サービス | 利用されるエンドポイント | OCP 4.13 | OCP 4.14 | OCP 4.15 - 4.17 |
|:----------:|:-----------:|:-----------:|:------------:|:------------:|
| OpenShift クラスター API サーバー | `<clusterid>.vpe.private.<region>.containers.cloud.ibm.com` | VPE  <br /> (お客様VPCのIPアドレス) |  VPE  <br/> (お客様VPCのIPアドレス) |  VPE  <br/> (お客様VPCのIPアドレス) |
| Red Hat OpenShift on IBM Cloud サービス | `api.<region>.containers.cloud.ibm.com` | (N/A) |  VPE  <br/> (お客様VPCのIPアドレス) |  VPE  <br/> (お客様VPCのIPアドレス) |
| Container Registry サービス | `icr.io` <br/><br/> `*.icr.io` | プライベート・エンドポイント <br />  166.8.0.0/14  |   VPE  <br/> (お客様VPCのIPアドレス) |   VPE  <br/> (お客様VPCのIPアドレス) |
| VPC IaaS サービス  | `<region>.private.iaas.cloud.ibm.com` | プライベート・エンドポイント <br />  166.8.0.0/14 | プライベート・エンドポイント <br />  166.8.0.0/14 | VPE  <br/> (お客様VPCのIPアドレス) |
| Object Storage サービス | `config.direct.cloud-object-storage.cloud.ibm.com` <br /><br />  `s3.direct.<region>.cloud-object-storage.appdomain.cloud` <br /><br /> `*.s3.direct.<region>.cloud-object-storage.appdomain.cloud` |ダイレクト・エンドポイント <br /> 161.26.0.0/16 | ダイレクト・エンドポイント <br />  161.26.0.0/16 | VPE  <br/> (お客様VPCのIPアドレス) |

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/83689/bb9b1cbd-2198-25ff-1ae7-8aa492c95cf9.png)


VPE を通じたアクセスについて、一見すると何も影響が無いようにも見えますが、例えば OpenShift 上で稼働するアプリケーションが Object Storage にアクセスする必要がある場合で、かつ VPC のセキュリティグループを厳格に設定し、Object Storage の VPE の IP アドレスに対してアクセスを許可していないようなケースでは、接続できないといった問題が発生します。

OpenShift クラスターと 仮想サーバーなど が同居しているようなケースではもう少し問題が複雑です。

OCP 4.14 以前のバージョンのクラスターが稼働している場合で、Object Storage や VPC サービスのエンドポイントにプライベート・エンドポイントを通じてアクセスしていると仮定します。このとき、各エンドポイントへの呼び出しの様子を図示すると下図のようになります。黒い実線が仮想サーバーからの呼び出しを示します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/83689/dba44544-fcc7-31f8-f1a3-16a21721a9e7.png)

これをバージョンアップして OCP 4.15 の環境とすると Object Storage や VPC サービスの呼び出しに対し VPE が利用されるようになるものの、仮想サーバーなど、 OpenShift クラスターの外にあるリソースから同一のエンドポイントを呼び出すような構成変更は自動的には実施されません。具体的には OpenShift クラスターに関するセキュリティグループ`kube-<cluster id>` (<clustter id>は実際のidに置換される) では VPE へ接続するためのポリシーが設定されるものの、VPC 内の他のリソースには同様のルールは適用されません。これらは手動で適用する必要があり、厳格に運用されているセキュリティグループを利用している場合、仮想サーバーから VPE へ接続できず、エラーとなった事例がありました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/83689/278c8112-b4cc-8816-f682-bae56ef1daa2.png)


<B>(対応策)既存のリソースから新たに作成されたVPEへのアクセスを可能とする
ための構成を行う</B>

上述のような環境でも仮想サーバーなどの IaaS のリソースから Object Storage や VPC サービスのエンドポイントを呼び出せるようにするためには、VPE を呼び出せるような新たなセキュリティ・グループを定義することが最も簡単な方法です。下図の Virtual Server から Object Storage や VPC サービスの VPE へつながる矢印の部分にあたる通信を許可するセキュリティ・グループを作成します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/83689/3d5c0c2f-6736-5475-0884-3d02ed125113.png)

Red Hat OpenShift on IBM Cloud (RHOIC/ROKS) サービスにより作成されたセキュリティ・グループにポリシーを追加することもできますが、今後のバージョンアップやマスターノードのリフレッシュで設定が失われる可能性があるので、別途新しいセキュリティグループを作成されることを推奨いたします。


# (2025/1/30追記) その他に問題が発生するケース

VPC上で稼働するクラスターで OCP 4.13 から OCP 4.14へバージョンアップする際に、サービスエンドポイントがPrivate Endpointのみ、Public Gateway経由での外部への通信を一切許可しないクラスターではバージョンアップが失敗することがあるそうです。
こちらの[ガイド](https://cloud.ibm.com/docs/openshift?topic=openshift-telemetry#oc_disable_telemetry_reports)に従いエラーの原因となる Telemetry 機能をOFFとしていだくようお願いたします。


# まとめ
以上のように、過去の Red Hat OpenShift on IBM Cloud (RHOIC/ROKS)  サービスのバージョンアップと同じだと思い込んで実際に作業を行うとエラーに遭遇してしまいます。特に「その3」は他のリソースにも影響が及びかねない問題で、注意いただきたいポイントです。適切に計画していれば、つまらない問題でハマることは減ると思います。
実際にハマってからこの記事を見てくださった方もいらっしゃるかもしれませんが、なるべくこのような問題に遭遇しないことをお祈り申し上げます。

# 参考文献

(全般)

- [Red Hat OpenShift on IBM Cloud バージョン情報](https://cloud.ibm.com/docs/openshift?topic=openshift-openshift_versions) 

(ハマりやすいポイント その1)

- [OCP 4.12 > OCP 4.13 VPCクラスターのアクセス権限の変更 (表2の最下行参照)](https://cloud.ibm.com/docs/openshift?topic=openshift-cs_versions_413#413_before)

(ハマりやすいポイント その2)

- [OCP 4.13 > OCP 4.14 へのクラスターのアップグレード可能状態の確認](https://cloud.ibm.com/docs/openshift?topic=openshift-cs_versions_414#status-check-414)
- [OCP 4.13 > OCP 4.14 管理者による承認の実施](https://docs.openshift.com/container-platform/4.14/updating/preparing_for_updates/updating-cluster-prepare.html#update-preparing-ack_updating-cluster-prepare)
- [OCP 4.15 > OCP 4.16 へのクラスターのアップグレード可能状態の確認](https://cloud.ibm.com/docs/openshift?topic=openshift-cs_versions_416#status-check-416) 
- [OCP 4.15 > OCP 4.16 管理者による承認の実施](https://docs.openshift.com/container-platform/4.16/updating/preparing_for_updates/updating-cluster-prepare.html#update-preparing-ack_updating-cluster-prepare) 

(ハマりやすいポイント その3)

- [OCP 4.13 > OCP 4.14 ネットワーキングの変更](https://cloud.ibm.com/docs/openshift?topic=openshift-cs_versions_414#networking_414) 
- [OCP 4.14 > OCP 4.15 VPEゲートウェイ作成情報 (OCP 4.13 > OCP 4.14の情報を含む) ](https://cloud.ibm.com/docs/openshift?topic=openshift-cs_versions_415#sbd-allow-outbound-after)