AWS Load Balancer Controller v2.4系からのアップグレード完全ガイド

AWS Load Balancer Controller（以下 LBC）を v2.4 系のまま運用していませんか？

v2.4.7 は 2023 年 2 月のリリース。3 年以上前のバージョンです。

その間に Breaking Changes や重要なバグ修正が多数入っています。

本記事では、v2.4 系から v2.17（v2 系最新）までのリリースノートを読み解き、アップグレード時に押さえておくべきポイントを整理しました。

アップグレード前に知っておくべきこと

Kubernetes バージョンの要件

v2.5.0 以降は Kubernetes 1.22 以上 が必須です。

EKS 1.22 未満のクラスターでは先にクラスターのアップグレードが必要です。

とはいえ、EKS 1.32 以前はとっくに標準サポート期限が終了しているので、さすがにそこまで古いクラスターを運用している現場はないはず…ですよね？

アップグレードの基本手順

バージョンに関係なく、以下の 3 ステップは毎回発生します。

1. CRD の更新 — 新しいフィールドが追加されている
2. IAM ポリシーの更新 — 新機能に伴い必要な権限が増えている
3. コントローラの更新 — Helm upgrade または manifest の差し替え

Helm を使っている場合、helm upgrade は CRD を更新しません。

コントローラ更新の前に kubectl apply で CRD を適用する必要があります。

Kustomize や raw manifest で CRD とコントローラを同一ファイルで管理している場合は、manifest の差し替えだけで CRD も一緒に更新されます。

いずれの場合も、CRD → IAM → コントローラの順番は守りましょう。

バージョン別 Breaking Changes

v2.5.0 — 最大の変更点はここ

v2.4 系から上げるなら、ここが最大の壁です。

v2.5.0 から、LBC が type: LoadBalancer の Service のデフォルトコントローラになります。

新規 Service に自動で spec.loadBalancerClass: service.k8s.aws/nlb が設定され、NLB が作成されるようになります。

この変更が影響するのは type: LoadBalancer の Service だけです。

Ingress 経由で ALB を使っている環境では、type: LoadBalancer の Service を新規作成しない限り影響ありません。

ただし、既存の Classic Load Balancer（CLB）を type: LoadBalancer の Service で運用している場合は、意図しない NLB への切り替わりが起きる可能性があります。

対処法

この設定で従来の動作を維持できます。

type: LoadBalancer の Service を使っていない環境では影響ありません。

# Helm の場合
enableServiceMutatorWebhook: false

その他の変更

• IngressClassParams CRD に subnets、inboundCIDRs、sslPolicy フィールドが追加
• EndpointsFailOpen がデフォルト有効化
• 複数 TLS 証明書のサポート（ALB）

v2.5.3 — 非推奨 API の削除

地味だけど見落としがちな変更です。

• policy/v1beta1 PodDisruptionBudget のサポート削除（Kubernetes 1.22 以上が必須に）
• cert-manager.io/v1alpha2 のサポート削除 → cert-manager.io/v1 に統一

cert-manager の古い API バージョンを参照している manifest がないか、事前に確認しておきましょう。

v2.6.0 — NLB のセキュリティグループ対応

• NLB に対してフロントエンド・バックエンドのセキュリティグループ管理が追加
• Ingress Validating Webhook が非 LBC 管理の Ingress を無視するように変更
• ACM 証明書の自動検出で対応アルゴリズムが拡張

大きな Breaking Change はありませんが、CRD にフィールドが追加されています。

Helm の場合は kubectl apply での事前適用、Kustomize / raw manifest の場合は manifest の差し替えで対応しましょう。

v2.7.0 — mTLS と EKS Pod Identity

• mTLS（相互 TLS 認証） のサポート追加
• EKS Pod Identity のサポート追加（IRSA の後継）
• コントローラに Readiness Probe が追加

IAM 権限の追加が必要

注意点として、古いコントローライメージは Helm chart v1.7.0 以降で Readiness Probe の追加により起動に失敗します。

必ずイメージとチャートのバージョンを揃えてください。

v2.8.0 — CRD の拡張

IngressClassParams CRD と TargetGroupBinding CRD に新しいフィールドが追加されます。

• IngressClassParams: certificateArn、ipAddressType フィールド追加
• TargetGroupBinding: vpcID フィールド追加

CRD の更新が必須です。

Helm の場合は kubectl apply で事前適用、Kustomize / raw manifest の場合は manifest の差し替えで更新されます。

忘れるとコントローラが新しいフィールドを認識できず、意図した動作になりません。

v2.9.0 — AWS SDK の世代交代

内部で利用している AWS SDK が Go v1 から Go v2 に移行 しました。

ユーザーから見える変化は少ないですが、内部的には大きなリファクタリングです。

• NLB の TCP アイドルタイムアウトが設定可能に
• VPC のタグ指定による識別をサポート

IAM 権限の追加が必要

v2.9.0 と v2.9.1 には AWS Shield Advanced 利用環境でコントローラがクラッシュするバグがあります。

Shield Advanced を利用している場合は v2.9.2 以上にしてください。

v2.10.0 — マルチクラスター対応

• TargetGroupBinding CRD に multiClusterTargetGroup フィールド追加
• SageMaker HyperPod クラスター統合

IAM 権限の追加が必要

v2.11.0 — キャパシティ予約

• ALB のキャパシティ予約（LCU）サポート
• TargetGroupBinding に targetGroupName フィールド追加

IAM 権限の追加が必要

v2.12.0 — Webhook ポリシー変更

Webhook の failure policy がデフォルトで Fail から Ignore に変更されました。

これは DR（障害復旧）時の挙動を改善するための変更ですが、Readiness Gate の付与が保証されなくなる側面もあります。

厳格な検証が必要な場合は設定で Fail に戻せます。

IAM 権限の追加が必要

v2.13.0 — Gateway API の導入

• ALB/NLB 向けの基本的な Gateway API 実装が追加（Beta）
• Prometheus メトリクスが刷新
• ALB を NLB のターゲットにする機能（ALB-as-NLB-target）

IngressClassParams CRD に新フィールドが追加されています。

Helm の場合は kubectl apply で事前適用が必要です。

v2.14.0 — EndpointSlices デフォルト化

EndpointSlices がデフォルトで有効化されます。

従来の Endpoints API に代わり、EndpointSlices API からターゲットの Pod IP を取得するようになります。

Kubernetes 1.21 以降では EndpointSlice が正常に稼働しているため、通常は影響ありません。

問題が発生した場合は --enable-endpoint-slices=false でフォールバックできます。

CRD の変更

• IngressClassParams の singular name が ingressclassparams → ingressclassparam に修正
• IngressClassParams に LB name、SSL redirect port、WAFv2 ARN フィールド追加

v2.15.0〜v2.17.1 — 新機能の追加

Breaking Change はありません。

主な追加機能は以下のとおりです。

v2.17.0 の Global Accelerator 機能を使う場合は、追加の CRD 適用と IAM 権限、RBAC 更新が必要です。

使わない場合は設定不要です。

IAM ポリシーの差分まとめ

v2.4.7 から v2.17.1 までに追加が必要な IAM 権限を一覧にしました。

公式リポジトリの IAM ポリシードキュメント を丸ごと適用するのが確実です。

CRD 更新が必要なバージョン

以下のバージョンでは、コントローラ更新の前に CRD の再適用が必要です。

• v2.5.0 — IngressClassParams に新フィールド追加
• v2.8.0 — IngressClassParams、TargetGroupBinding に新フィールド追加
• v2.9.0 — IngressClassParams に listenerAttributes 追加
• v2.13.0 — IngressClassParams に新フィールド追加、Gateway API CRD
• v2.14.0 — IngressClassParams の singular name 修正、新フィールド追加

一気にアップグレードする場合は、最新版の CRD を 1 回適用すれば OK です。

v2.4 系からアップグレードする際のチェックリスト

• type: LoadBalancer の Service が存在するか確認する
  • 存在する場合は enableServiceMutatorWebhook=false の設定を検討
• cert-manager を使っている場合、API バージョンが cert-manager.io/v1 か確認する
• PodDisruptionBudget が policy/v1 で定義されているか確認する
• EndpointSlice が正常に存在するか確認する（kubectl get endpointslices -A）
• 最新の IAM ポリシーを適用する
• 最新の CRD を適用する（kubectl apply）
• AWS Shield Advanced を利用している場合、v2.9.2 以上を選択する
• コントローラを更新する
• 開発環境で先に適用し、ALB/NLB のターゲット登録が正常か確認する
• Ingress 経由のアクセスに問題がないことを確認する

まとめ

v2.4 系からのアップグレードで最も注意すべきは v2.5.0 の Service デフォルト動作変更 です。

ここさえ押さえれば、あとは CRD と IAM の更新を忘れずに行えば大きな問題にはなりません。

v2.17.1 までの間に、mTLS、EndpointSlices、Gateway API（Beta）、AWS SDK v2 移行など多くの改善が入っています。

古いバージョンのまま運用を続けるリスクも考慮して、計画的にアップグレードを進めましょう。

saratoga

フリーランスエンジニア

XYouTube

仕事にも趣味にも IT を駆使するフリーランスエンジニア。技術的な TIPS や日々の生活の中で深堀りしてみたくなったことを備忘録として残していきます。