K3sで検証していたHorizontal Pod Autoscaler（HPA）のマニフェストを、そのまま標準Kubernetes（kubeadmで構築したクラスタ）に適用したら、kubectl topが何も返さず、HPAも一切スケールしなかった——そんな経験をしたインフラエンジニアは少なくないはずだ。原因は多くの場合、metrics-serverの有無という、意外なほど基本的なところにある。K3sでは最初から動いていたものが、標準Kubernetesでは動かない。この記事では、その差がなぜ生まれるのかを公式ドキュメントベースで整理し、切り分け手順までまとめる。
1. kubectl topが無反応になった日
話はシンプルだ。K3sの検証環境で組んだHPA付きのDeploymentを、本番相当の標準Kubernetes（kubeadmでブートストラップしたクラスタ）に移した。マニフェスト自体に変更はない。ところがkubectl top podsを叩いても何も返らず、HPAのステータスを見るとunknownのまま張り付いている。
Kubernetes公式のHPAウォークスルーには、前提条件としてこう明記されている。
To follow this walkthrough, you also need to use a cluster that has a Metrics Server deployed and configured.
つまりHPAを使うには、Metrics Serverがデプロイされ、正しく設定されていることが大前提になる。K3sではこの前提が最初から満たされているため意識する機会がなかっただけで、標準Kubernetesでは自分で満たす必要がある条件だったわけだ。
2. K3sがmetrics-serverを最初から同梱している理由
K3s公式ドキュメント「Packaged Components」には、K3sが標準で同梱するアドオンが明記されている。
K3s comes with a number of packaged components that are deployed as AddOns via the manifests directory:
coredns,traefik,local-storage, andmetrics-server.
coredns（DNS）、traefik（Ingress）、local-storage（ローカルストレージ）と並んで、metrics-serverが標準コンポーネントの1つとして明記されている。これらは/var/lib/rancher/k3s/server/manifests配下に自動配置され、K3sの起動時にkubectl apply相当の処理で自動デプロイされる。同じ内容はSUSEの公式ドキュメントでも確認できる。
K3sは「軽量シングルバイナリでKubernetesを動かす」ことを目的に設計されており、運用に最低限必要なアドオンを最初からバンドルする方針を取っている。metrics-serverを無効化する手順が公開されているのも、裏を返せば「標準で有効になっている」ことの証左だ。kubectl topコマンドとHPAの両方が、インストール直後から動く設計になっている。K3sベースのマネージドサービスであるKuboも、この同梱方針をそのまま引き継いでいる。
3. 標準Kubernetes（kubeadm）にmetrics-serverが入っていない理由
一方、kubeadmはKubernetesのコントロールプレーンの最小構成を提供することに主眼を置いたツールだ。CNI、Ingress Controller、そしてmetrics-serverといったアドオンは、どれもkubeadmのインストール対象に含まれない。
Kubernetes公式の「Resource metrics pipeline」には、この点がはっきり書かれている。
You must deploy the metrics-server or alternative adapter that serves the Metrics API to be able to access it.
同ページでは、metrics-serverを「クラスタアドオンコンポーネント（cluster addon component）」と位置づけ、HPA・VPA・kubectl topのすべてがこのMetrics APIに依存すると説明している。つまり、kubeadmでクラスタを作っただけでは、HPAもVPAもkubectl topも最初から動く保証はないということだ。
導入自体は難しくない。metrics-server公式リポジトリが提供するcomponents.yamlを次のように適用すればいい。
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
問題は、「これを忘れていた／知らなかった」というケースが、K3sから移行してきたチームほど起きやすいという点だ。K3sでは誰も意識していなかった工程が、標準Kubernetesでは必須の一手間になる。EKSやAKSのような標準Kubernetesベースのマネージドサービスでも、この種のアドオン導入は利用者側の作業として残ることが多い。Kubo CloudはK3sベースでPure Kubernetesを提供するため、こうした初期セットアップの手間がそもそも発生しない。
4. metrics-serverが無いとHPA/kubectl topはどう壊れるか
metrics-serverが存在しない、またはPodが起動していない状態でHPAを動かそうとすると、典型的には次のようなエラーに遭遇する。
failed to get cpu utilization: unable to get metrics for resource cpu: no metrics returned from resource metrics API
オンコール対応向けのトラブルシューティング記事では、このエラーに遭遇した際の切り分け手順が次のようにまとめられている。
- metrics-serverの存在確認bash
kubectl get deployment metrics-server -n kube-system kubectl get pods -n kube-system -l k8s-app=metrics-server - メトリクス取得の動作確認bash
kubectl top nodes kubectl top pods -n default - APIサービスの登録状態確認ここでbash
kubectl get apiservices | grep metricsv1beta1.metrics.k8s.ioのStatusがTrueになっているかを確認する。Falseであれば、metrics-server自体の起動に問題がある可能性が高い。
この3段階を踏めば、「HPAの設定ミスなのか」「そもそもmetrics-serverが無いのか」をすぐに切り分けられる。K3s環境しか触ったことがないチームほど、この切り分け手順自体を知らないことが多い。
5. K3s同梱版と自前インストール版でmetrics-serverの挙動が違うことも
もう一つ注意したいのが、「metrics-serverを入れたのに、K3sの頃と挙動が違う」というケースだ。metrics-serverのリソース監視を解説した記事によれば、metrics-serverのバイナリ自体の--metric-resolutionのデフォルトは60秒だが、公式マニフェストでは--metric-resolution=15sに設定されている。どちらの値で動いているかによって、HPAがスケール判断に使うメトリクスの鮮度が変わる。
加えて、自己署名証明書のkubeletに対応するための--kubelet-insecure-tlsのようなフラグも、ディストリビューションやインストール方法によって有効/無効が異なる。K3s同梱版の設定と、components.yamlをそのまま適用した自前インストール版の設定は、必ずしも一致しない。「同じmetrics-serverのはずなのに、HPAの反応速度が違う」と感じたら、まずこの設定差を疑うべきだ。
小規模クラスタでは、metrics-server自体のリソース消費にも注意したい。典型的な起動要件はCPU 100m／メモリ200Mi程度のrequestsとされており、ノードリソースが逼迫している環境ではこのオーバーヘッドも無視できない。
まとめ：K3sベースならこの手間がそもそも発生しない
HPAやkubectl topが動かない原因の多くは、設定ミスではなく「metrics-serverが無い」という前提条件の欠落にある。K3sは公式ドキュメントの通りmetrics-serverを標準同梱しているため、この問題自体に遭遇しない。一方、標準Kubernetes（kubeadm）を自前で運用する場合は、metrics-serverの導入とフラグ設定を自分たちでチェックリスト化しておく必要がある。
この「最初から動く」か「毎回チェックリストを回すか」という差は、運用コストとして地味に効いてくる。KuboはK3sベースのマネージドKubernetesサービスで、metrics-serverを含む標準アドオンが最初から動く状態で提供される。AWS EKSやAzure AKSで同様の初期セットアップに手間をかけているなら、Pure Kubernetesな構成を月額48,000円〜ですぐに試せる。
今回のようなクラスタ移行時の"見えない前提条件の差"は、HPA/metrics-server以外にも数多く存在する。標準Kubernetesを自前運用していて同種の手間を抱えているなら、お問い合わせからKuboの構成を相談してみてほしい。