背景

Kubernetesは現在4か月に新しいバージョンをリリースしており、自分たちのプロジェクトで管理するKubernetesクラスターも定期的なバージョン更新が必要です。特にAmazon EKSのようなクラウドプロバイダーが提供するKubernetesサービスは、ある期間までに一定以上のバージョンに更新していないと、プロバイダー側で強制的にバージョンを更新します。AWSではクラスターのバージョンを延長サポートするようなサービスも開始していますが、定期的な更新をしないことが運用するサービス自体のSLA、コストなどに影響してしまいます。

さて、クラスターの更新を行う上で面倒なことの一つが、クラスター上で稼働するリソースのAPIバージョンも併せて更新する必要がある場合です。Kubernetesクラスターのバージョンによっては特定のリソースのAPIバージョンを合わせる必要があり、それができていない場合は該当するリソースが利用できなくなります。これまではクラスター上のリソースのAPIバージョンを一つずつ確認し、利用するAPIバージョンが廃止されていないかチェックする必要がありました。

今回Amazon EKSに追加されたUpgrade insightsは、クラスター上のリソースのAPIバージョンをチェックし、アップグレードするうえで問題になる場合はユーザーに分かるよう表示してくれます。またUpgrade insightsを利用するうえで必要な事前作業などがないため、EKSを利用するユーザーは無条件で利用可能です。

なお、詳細は以下ドキュメントをご確認ください。

docs.aws.amazon.com

AWSブログでも本機能は紹介されています。

aws.amazon.com

検証

今回はAmazon EKS ver 1.25の上にHPAリソースを作成します。ただしHPAのAPIバージョンは autoscaling/v2beta2 という少し古いものを利用し、Upgrade insightsがそれを検知するか確認しました。

# Amazon EKSのバージョン
$ kubectl version
Client Version: version.Info{Major:"1", Minor:"22", GitVersion:"v1.22.0", GitCommit:"c2b5237ccd9c0f1d600d3072634ca66cefdf272f", GitTreeState:"clean", BuildDate:"2021-08-04T18:03:20Z", GoVersion:"go1.16.6", Compiler:"gc", Platform:"linux/amd64"}
Server Version: version.Info{Major:"1", Minor:"25+", GitVersion:"v1.25.16-eks-8cb36c9", GitCommit:"3a3ea80e673d7867f47bdfbccd4ece7cb5f4a83a", GitTreeState:"clean", BuildDate:"2023-11-22T21:53:22Z", GoVersion:"go1.20.10", Compiler:"gc", Platform:"linux/amd64"}
WARNING: version difference between client (1.22) and server (1.25) exceeds the supported minor version skew of +/-1

# metrics-serverの作成
$ kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/download/v0.6.4/components.yaml

# テスト用のDeployment / HPAの作成
$ kubectl apply -f sample-hpa.yaml

$ kubectl get pods
NAME                    READY   STATUS    RESTARTS   AGE
sample-6c6899cc-xk5xd   1/1     Running   0          67s

$ kubectl get hpa
NAME     REFERENCE           TARGETS   MINPODS   MAXPODS   REPLICAS   AGE
sample   Deployment/sample   0%/50%    1         3         1          72s

※使用した sample-hpa.yaml はここをクリック

apiVersion: apps/v1
kind: Deployment
metadata:
  name: sample
spec:
  replicas: 1
  selector:
    matchLabels:
      app: sample-app
  template:
    metadata:
      labels:
        app: sample-app
    spec:
      containers:
        - image: nginx
          name: sample-pod
          resources:
            requests:
              #memory: "64Mi"
              cpu: "250m"
            limits:
              #memory: "128Mi"
              cpu: "500m"
---
apiVersion: autoscaling/v2beta2
kind: HorizontalPodAutoscaler
metadata:
  name: sample
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: sample
  minReplicas: 1
  maxReplicas: 3
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 50

上記リソースを作成後、Amazon EKSのメニューから Upgrade insights を確認すると、エラーが発生することを確認できます。

該当する項目を選択すると Deprecated APIs removed in Kubernetes v1.26 とあるように、Kubernetesをv1.26に更新するうえで削除されるAPIがあることを表示しています。

画面下部には具体的にエラーを発生させるAPIと、それを利用するリソースが表示されます。その中にはHPAのAPIも含まれています。

HPA APIをクリックすると、廃止するAPIの詳細などが表示されます。

さらにリソースのほうを選択すると、リソースの情報ページに遷移します。

なお、AWS CLIからも上記情報は確認できます。具体的には list-insights describe-insight などのコマンドを利用します。

クラスターに対するUpgrade insightsのリストを表示

$ aws eks list-insights --cluster-name eks-cluster --region ap-northeast-1
{
    "insights": [
        {
            "id": "40163eec-bc6d-4927-b740-4d9e8bdc5ae1",
            "name": "Deprecated APIs removed in Kubernetes v1.26",
            "category": "UPGRADE_READINESS",
            "kubernetesVersion": "1.26",
            "lastRefreshTime": "2024-01-03T15:10:10+09:00",
            "lastTransitionTime": "2024-01-03T15:10:09+09:00",
            "description": "Checks for usage of deprecated APIs that are scheduled for removal in Kubernetes v1.26. Upgrading your cluster before migrating to the updated APIs supported by v1.26 could cause application impact.",
            "insightStatus": {
                "status": "ERROR",
                "reason": "Deprecated API usage detected within last 30 days and your cluster is on Kubernetes v1.25."
            }
        },
        {
            "id": "d1836d3e-736e-4535-9533-c04d961d1c7b",
            "name": "Deprecated APIs removed in Kubernetes v1.29",
            "category": "UPGRADE_READINESS",
            "kubernetesVersion": "1.29",
            "lastRefreshTime": "2024-01-03T15:10:10+09:00",
            "lastTransitionTime": "2024-01-03T15:10:09+09:00",
            "description": "Checks for usage of deprecated APIs that are scheduled for removal in Kubernetes v1.29. Upgrading your cluster before migrating to the updated APIs supported by v1.29 could cause application impact.",
            "insightStatus": {
                "status": "PASSING",
                "reason": "No deprecated API usage detected within the last 30 days."
            }
        },
        {
            "id": "4e88e2db-fb41-4d87-85ee-fe76dd0f92ab",
            "name": "Deprecated APIs removed in Kubernetes v1.27",
            "category": "UPGRADE_READINESS",
            "kubernetesVersion": "1.27",
            "lastRefreshTime": "2024-01-03T15:10:10+09:00",
            "lastTransitionTime": "2024-01-03T15:10:09+09:00",
            "description": "Checks for usage of deprecated APIs that are scheduled for removal in Kubernetes v1.27. Upgrading your cluster before migrating to the updated APIs supported by v1.27 could cause application impact.",
            "insightStatus": {
                "status": "PASSING",
                "reason": "No deprecated API usage detected within the last 30 days."
            }
        }
    ]
}

エラーを検知したinsightsの詳細を確認する

$ aws eks describe-insight --region ap-northeast-1 --id 40163eec-bc6d-4927-b740-4d9e8bdc5ae1 --cluster-name eks-cluster
{
    "insight": {
        "id": "40163eec-bc6d-4927-b740-4d9e8bdc5ae1",
        "name": "Deprecated APIs removed in Kubernetes v1.26",
        "category": "UPGRADE_READINESS",
        "kubernetesVersion": "1.26",
        "lastRefreshTime": "2024-01-03T15:10:10+09:00",
        "lastTransitionTime": "2024-01-03T15:10:09+09:00",
        "description": "Checks for usage of deprecated APIs that are scheduled for removal in Kubernetes v1.26. Upgrading your cluster before migrating to the updated APIs supported by v1.26 could cause application impact.",
        "insightStatus": {
            "status": "ERROR",
            "reason": "Deprecated API usage detected within last 30 days and your cluster is on Kubernetes v1.25."
        },
        "recommendation": "Update manifests and API clients to use newer Kubernetes APIs if applicable before upgrading to Kubernetes v1.26.",
        "additionalInfo": {
            "EKS update cluster documentation": "https://docs.aws.amazon.com/eks/latest/userguide/update-cluster.html",
            "Kubernetes v1.26 deprecation guide": "https://kubernetes.io/docs/reference/using-api/deprecation-guide/#v1-26"
        },
        "resources": [
            {
                "insightStatus": {
                    "status": "ERROR"
                },
                "kubernetesResourceUri": "/apis/autoscaling/v2beta2/namespaces/default/horizontalpodautoscalers/sample"
            }
        ],
        "categorySpecificSummary": {
            "deprecationDetails": [
                {
                    "usage": "/apis/flowcontrol.apiserver.k8s.io/v1beta1/flowschemas",
                    "replacedWith": "/apis/flowcontrol.apiserver.k8s.io/v1beta3/flowschemas",
                    "stopServingVersion": "1.26",
                    "startServingReplacementVersion": "1.26",
                    "clientStats": []
                },
                {
                    "usage": "/apis/flowcontrol.apiserver.k8s.io/v1beta1/prioritylevelconfigurations",
                    "replacedWith": "/apis/flowcontrol.apiserver.k8s.io/v1beta3/prioritylevelconfigurations",
                    "stopServingVersion": "1.26",
                    "startServingReplacementVersion": "1.26",
                    "clientStats": [
                        {
                            "userAgent": "eks-k8s-metrics",
                            "numberOfRequestsLast30Days": 32,
                            "lastRequestTime": "2024-01-03T14:31:01+09:00"
                        }
                    ]
                },
                {
                    "usage": "/apis/autoscaling/v2beta2/horizontalpodautoscalers",
                    "replacedWith": "/apis/autoscaling/v2/horizontalpodautoscalers",
                    "stopServingVersion": "1.26",
                    "startServingReplacementVersion": "1.23",
                    "clientStats": [
                        {
                            "userAgent": "kubectl",
                            "numberOfRequestsLast30Days": 7,
                            "lastRequestTime": "2024-01-03T13:25:44+09:00"
                        }
                    ]
                }
            ]
        }
    }
}