※本記事はアフィリエイト広告(PR)を含みます。
本線でクラスタを3台に増やしました。Pod は動いています。kubectl get pods は Running と出ます。
これは【深掘り】の記事です。本線の順路ではありません。 読まなくても先へ進めます。 本線の 1台落としてもPodは移る — kubeadmで組む3台クラスタ の続きとして、そのクラスタの中で動いているアプリを、外のブラウザから開けるようにする回です。
この記事のコマンドは、すべてVMの中(Ubuntu Server)で打ちます。 Windows の PowerShell では打ちません。打つ場所は、本線で組んだクラスタのコントロールプレーン(
cp1)です。 前提: kubeadmで組む3台クラスタを終えて、kubectl get nodesで3台ともReadyになっていること。 本線で作ったものには触りません。 練習用にingdemoという名前空間を新しく作って、そこだけで完結させます。最後に全部消します。 メモリを 500MB ほど余分に使います。 ワーカーが 2GB しかない構成なので、後半に入る前にfree -hを一度見てください。
そして、ブラウザからは何も見えません。
前回、Service を作って ClusterIP と NodePort を触りました。NodePort なら、たしかに外から開けます。ただしアドレスは http://192.168.1.51:31234/ のような形になります。ポート番号が付いていて、番号は自動で決まり、しかもサービスを増やすたびに別の番号が増えていきます。
そこで、Kubernetes の入門記事に必ず出てくるこの1行を書きます。
type: LoadBalancer
「これで本物のIPアドレスが1つもらえて、80番で開ける」と書いてあります。書いて、kubectl get svc を打ちます。
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
app-a LoadBalancer 10.107.42.118 <pending> 80:31712/TCP 12s
EXTERNAL-IP が <pending> です。
10秒待ちます。変わりません。1分待ちます。変わりません。私はここで10分待ちました。 そのあと kubectl describe を読んで、kubectl logs を探して、ノードを再起動して、クラスタの組み方を間違えたのだと思って作り直しました。
壊れていません。設定ミスでもありません。
<pending>は「IPアドレスを割り当ててくれる人が、まだ現れていない」という意味です。 そして自前のクラスタには、その人は永遠に現れません。
この記事は、その1行の意味を理解して、代わりに何を置くかを決める回です。 置くものが Ingress です。
対象レベル: 中級〜上級 / 区分: 発展
この記事でわかること
type: LoadBalancerは「ロードバランサを作る機能」ではなく、「作ってほしいという注文票」だということ。注文を受ける人はクラスタの外にいる- クラウドでは、その注文を受ける人(クラウドコントローラ)が最初から住んでいる。 だから同じYAMLがAWSでは動いて、自前では
<pending>になる - Ingress は「設定」であって「動くもの」ではないこと。Ingress Controller を入れるまで、書いても本当に何も起きない
pathTypeのPrefixは文字列の前方一致ではなく、/で区切った要素の一致だということ。/aは/abに一致しないrewrite-targetは Kubernetes の機能ではなく、コントローラごとの独自の注釈だということ。ingress-nginx で動いたものは Traefik では動かない- 外へ出す方法は NodePort・LoadBalancer・Ingress の3つしかなく、選び方は「自前かクラウドか」と「HTTPかどうか」の2軸で決まること
- Gateway API は Ingress の後継で、この記事で使う ingress-nginx は2026年3月で保守が終わった(引退済み)こと
この記事でやること
type: LoadBalancerの Service を実際に作り、<pending>を自分の目で再現する- MetalLB を入れて
<pending>が消えるところを見て、それでも足りないものを確認する - Ingress のYAMLだけを先に書いて、何も起きないことを確かめてから ingress-nginx を入れる
- アプリを2つ立て、
/aと/b、そしてホスト名で振り分ける - 自己署名の証明書で TLS を有効にする
- 繋がらないときの切り分けを4段階で実行する。最後にコントローラごと全部消す
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| Ingress | 「このホスト名のこのパスは、このServiceへ」という振り分けの設定を書いた紙。紙なので、単体では何もしない |
| Ingress Controller | その紙を読んで、実際にリクエストを振り分けるプログラム。クラスタの中で Pod として動く。nginx 版や Traefik 版がある |
| IngressClass | Ingress Controller を複数入れたときに、どの紙をどのコントローラが担当するかを示す名札。ingressClassName: nginx の nginx がこれ |
| クラウドコントローラ | クラウドの中で動く Kubernetes の部品。type: LoadBalancer の注文を受けて、クラウドのAPIを叩いて本物のロードバランサを作る担当者 |
| MetalLB | 自前のクラスタに、その「担当者」を後から住まわせるソフト。空いているIPを自分で渡す役をする |
| 注釈(annotation) | リソースに付ける自由なメモ書き。Kubernetes 本体は中身を見ない。 読むのはそれを見る特定のプログラムだけ |
| 自己署名証明書 | 認証局を通さず、自分で自分に発行した証明書。中身の暗号化は本物と同じだが、ブラウザは「知らない発行者」として警告を出す |
① 先に地図 — 外へ出す方法は3つしかない
細かい話に入る前に、選択肢の全体を先に置きます。 ここを持っていないと、次の節で <pending> を見たときに「他の方法があるのか」が分からなくなります。
| 方法 | 何が起きるか | アドレスの形 |
|---|---|---|
| NodePort | 全ノードの同じ高い番号のポートが開く。そこへ来た通信がServiceへ入る | http://ノードのIP:31712/ |
| LoadBalancer | 「外にロードバランサを1台作って」という注文が出る。作る人がいれば専用IPが付く | http://203.0.113.10/ |
| Ingress | 1つの入口を全アプリで共有し、ホスト名とパスで振り分ける | http://a.example.com/ |
この3つは、置き換えの関係ではありません。 実際には積み上がっています。
ブラウザ
|
[ Ingress ] ← ホスト名とパスを見て振り分ける(L7)
|
[ Ingress Controller の Service ] ← これ自体が NodePort か LoadBalancer
|
[ Service ] [ Service ] ← ClusterIP でよくなる
| |
[ Pod ] [ Pod ]
Ingress を入れても、NodePort や LoadBalancer が要らなくなるわけではありません。 要る数が「アプリの数」から「1つ」に減るだけです。ここが最初は分かりませんでした。
「ホスト名とパスを見て振り分ける」は、OSI参照モデルの回で書いた L7 の話そのものです。NodePort と LoadBalancer は中身を見ません(L4)。Ingress は中身を見ます(L7)。 そして、nginxのリバースプロキシの回で location /api/ { proxy_pass ...; } と書いたあれが、Kubernetes の言葉に置き換わったものが Ingress です。 やっていることは同じです。
② <pending> を自分で再現する
読んで納得するより、出したほうが早いです。
練習場を作る
本線で作ったものと混ざらないように、名前空間を分けます。
いま自分がどこにいるかを確認します。
namespace: ingdemo
この記事の間、kubectl はすべて ingdemo に対して動きます。 最後の後片づけで元に戻します。
アプリを1つ立てる
traefik/whoami という小さなイメージを使います。アクセスすると、自分のホスト名・受け取ったパス・ヘッダをそのまま返すだけのプログラムです。どのPodが答えたのか、どんなパスで届いたのかが目で見えるので、振り分けの確認に向いています。
deployment "app-a" successfully rolled out
type: LoadBalancer の Service を書く
ここが本題です。ファイルに書きます。
apiVersion: v1
kind: Service
metadata:
name: app-a-lb
spec:
type: LoadBalancer
selector:
app: app-a
ports:
- port: 80
targetPort: 80
適用します。
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
app-a-lb LoadBalancer 10.104.9.201 <pending> 80:31712/TCP 5s
<pending> が出ました。 変化を待ってみます。
1分待っても、行は1度も更新されません。 Ctrl+C で止めます。
[スクリーンショット: 01_external-ip-pending.png] kubectl get svc app-a-lb の結果で、EXTERNAL-IP の列が <pending> になっている画面を撮ってください。
なぜ待っても変わらないのか
エラーが出ていないところが厄介です。 出来事を探します。
Events: <none>
イベントすら空です。 これが答えのヒントです。
Kubernetes 本体には、ロードバランサを作る機能が入っていません。
type: LoadBalancer を書いたとき、Kubernetes がやることはこれだけです。
- ClusterIP を割り当てる(やった)
- NodePort を1つ確保する(やった。上の
80:31712/TCPの31712がそれです) - 「外部IPを1つ付けてください」という状態を作って、放置する
3番を拾いに来る担当者が、クラウドコントローラです。AWS の EKS なら、この状態を見つけて AWS のAPIを叩き、本物の NLB を作り、そのアドレスを EXTERNAL-IP に書き戻します。GCP でも Azure でも同じです。
自前で kubeadm から組んだクラスタには、その担当者がいません。 誰も拾いません。だから <pending> のままです。これは正常な動作です。
「クラウドで動いたYAMLを自前に持ってくると動かない」の代表例がこれです。 YAMLは間違っていません。周りの環境が違うだけです。逆も起きます。自前で書いた NodePort 前提の手順書は、クラウドではポートが塞がれていて動きません。
念のため、NodePort としては動いていることを確かめておきます。ノードのIPを調べます。
NAME STATUS ROLES AGE VERSION INTERNAL-IP
cp1 Ready control-plane 6d v1.31.1 192.168.1.51
w1 Ready <none> 6d v1.31.1 192.168.1.52
w2 Ready <none> 6d v1.31.1 192.168.1.53
確保された NodePort(この例では 31712)を叩きます。自分の環境の番号に読み替えてください。
Hostname: app-a-6d4b8f9c7-x2klm
IP: 127.0.0.1
IP: 10.244.1.7
RemoteAddr: 10.244.0.1:41234
GET / HTTP/1.1
中身は生きています。 EXTERNAL-IP が付いていないだけです。
選択肢は3つ
ここで取れる道は3つです。どれも正解になり得ます。
| 選択肢 | やること | 向いている場面 |
|---|---|---|
| NodePort で妥協する | type: LoadBalancer をやめて NodePort にし、番号付きURLを受け入れる | 学習用・社内ツール・アプリが1〜2個 |
| MetalLB を入れる | IPを配る担当者を自前で住まわせる。 <pending> は本当に消える | 自宅・社内のオンプレで、IPを何個か自由に使えるとき |
| Ingress を使う | 入口を1つにまとめて、ホスト名とパスで振り分ける | アプリが3個以上・ドメイン名で分けたい・TLSをまとめたい |
この記事は3番目を採ります。 ただし 2番目を先に1回だけ実際にやります。 <pending> が消える瞬間を見ておかないと、「Ingress を入れれば <pending> が消える」という間違った覚え方をするからです。消しているのは Ingress ではありません。
③ MetalLB を入れて <pending> を消す(1回だけ)
この節は任意です。 メモリが厳しい場合、あるいは自宅のネットワークで空いているIPを勝手に使えない場合は、この節を飛ばして④へ進んでください。 以降は飛ばしても成立するように書いてあります。
空いているIPを決める
MetalLB がやることは単純です。「この範囲のIPは自由に使っていい」と教えておくと、<pending> の Service にそこから1つ渡します。
範囲は、VMと同じネットワークで、他の機器とルーターのDHCPが使っていない帯を選んでください。 重複させると、同じIPを2台が名乗る状態になり、家の中のネットワークが不安定になります。ルーターの設定画面でDHCPの割り当て範囲を確認してから決めます。
この記事では 192.168.1.240 から 192.168.1.250 の11個を使います。
入れる
deployment "controller" successfully rolled out
範囲を教えます。
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
name: home-pool
namespace: metallb-system
spec:
addresses:
- 192.168.1.240-192.168.1.250
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
name: home-l2
namespace: metallb-system
spec:
ipAddressPools:
- home-pool
<pending> が消える
さっき作った Service を、作り直す必要はありません。
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
app-a-lb LoadBalancer 10.104.9.201 192.168.1.240 80:31712/TCP 9m
IPが付きました。 叩きます。
Hostname: app-a-6d4b8f9c7-x2klm
IP: 127.0.0.1
IP: 10.244.1.7
ポート番号なしの80番で開きました。
それでも足りないもの
では MetalLB を入れれば終わりでしょうか。 アプリを2つ目、3つ目と増やしてみると分かります。
- アプリの数だけIPを消費します。 11個しか用意していないので、12個目で
<pending>に戻ります - どのアプリがどのIPか、誰も覚えられません。 DNSに全部登録することになります
- TLSの証明書を、IPの数だけ用意することになります
「1つのIPを全アプリで共有して、名前とパスで振り分けたい」 ——これが Ingress の動機です。MetalLB は Ingress の代わりではなく、その下に敷くものです。
この2つの層の違いが、最初どうしても分かりませんでした。 分け方はこうです。
MetalLB は「IPを配る係」。Ingress は「1つのIPに来た通信を振り分ける係」。仕事が別です。
④ Ingress を書いても、本当に何も起きない
ここが、この記事で一番伝えたいところです。
まず Ingress だけを書いてみる
Ingress Controller はまだ入れていません。 その状態で、Ingress のYAMLだけを書きます。
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: first
spec:
rules:
- host: demo.local
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: app-a-lb
port:
number: 80
ingress.networking.k8s.io/first created
created と出ます。 エラーは1つも出ません。受け付けられました。
確認します。
NAME CLASS HOSTS ADDRESS PORTS AGE
first <none> demo.local 80 18s
ADDRESS が空です。 そして5分待っても空のままです。
[スクリーンショット: 02_ingress-no-address.png] kubectl get ingress の結果で、ADDRESS の列が空になっている画面を撮ってください。
出来事を見ます。
Events: <none>
また空です。 <pending> のときと同じ形です。
Ingress は「動くもの」ではない
理由は同じです。
Ingress は、振り分けのルールを書いた紙です。 紙を読んで、実際に通信を振り分けるプログラムが別に要ります。それが Ingress Controller です。
kubectl apply でやったことは、紙をクラスタの掲示板に貼っただけです。読む人がいなければ、貼ったまま何も起きません。 Kubernetes はそれをエラーにしません。「あとで読む人が来るかもしれない」からです。
ここを知らないと、YAMLを何時間も疑うことになります。 私は path の書き方が悪いのだと思って、/、/*、/.* と3種類試しました。全部同じ結果です。当たり前でした。
この構図は、Kubernetes のあちこちに出てきます。
| 紙(設定) | 読む人(コントローラ) | 読む人がいないと |
|---|---|---|
| Ingress | Ingress Controller | 何も起きない |
type: LoadBalancer | クラウドコントローラ / MetalLB | <pending> |
| PersistentVolumeClaim | ストレージのプロビジョナ | Pending |
「applyが通った」は「動いている」ではありません。 Kubernetes での確認は、必ず「誰が読んだか」まで見ます。
⑤ ingress-nginx を入れる
どれを入れるか
Ingress Controller は1つではありません。中身が違うだけで、読む紙は同じ Ingress です。
| コントローラ | 中身 | 特徴 |
|---|---|---|
| ingress-nginx | nginx | 2026年3月で保守終了(引退済み)。資料が一番多いので、この記事では旧方式の理解用に使う |
| Traefik | Traefik | 設定がリソース指向。k3s に最初から入っている |
| HAProxy Ingress | HAProxy | L4寄りの制御が細かい |
この記事は ingress-nginx を入れます。 理由は、nginxのリバースプロキシの回で書いた設定が、そのまま中で生成されるからです。知っているものが中で動いているほうが、壊れたときに読めます。
名前が紛らわしいものが2つあります。
ingress-nginx… Kubernetes プロジェクトが作っている。この記事で入れるのはこちらnginx-ingress… nginx社(F5)が作っている別物。注釈の名前が違うので、混ぜると動きません
検索で出てきたページの注釈をコピーする前に、どちらのドキュメントかを確認してください。
メモリの確認
入れる前に空きを見ます。
total used free shared buff/cache available
Mem: 3.8Gi 1.9Gi 0.4Gi 12Mi 1.5Gi 1.7Gi
available が 500MB を切っているなら、先に何か止めてください。 ingress-nginx の Pod 自体は 100〜200MB 程度ですが、2GB のワーカーで他のPodが動いていると、そこそこ効きます。
入れる
「baremetal」向けのマニフェストを使います。 これはコントローラ自身の Service を NodePort で作る版です。既定の cloud 版を入れると、コントローラの Service が type: LoadBalancer になり、また <pending> を見ることになります(MetalLB を入れた人はそれでも動きます)。ingress-nginx は2026年3月で保守が終わり、以降はセキュリティ修正も出ません。 ここでは Ingress の仕組みを理解する練習用として、最後の版 v1.15.1 を入れます。本番で新しく使うのはやめてください。
起動を待ちます。初回はイメージの取得で1〜2分かかります。
deployment "ingress-nginx-controller" successfully rolled out
動いているものを見ます。
NAME READY STATUS RESTARTS AGE
pod/ingress-nginx-controller-7d4c8b6f8d-mn4rc 1/1 Running 0 92s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S)
service/ingress-nginx-controller NodePort 10.99.184.22 <none> 80:31090/TCP,443:32410/TCP
service/ingress-nginx-controller-admission ClusterIP 10.108.55.101 <none> 443/TCP
[スクリーンショット: 03_ingress-controller-running.png] kubectl -n ingress-nginx get pods,svc の結果で、コントローラの Pod が Running になっている画面を撮ってください。
設定用のジョブ(admission-create と admission-patch)は、一度だけ動いて終わると、この版ではすぐ消えるので一覧に出ません。 古い版では 0/1 Completed のまま残るので、失敗したのかと驚くことがあります。
このあと何度も使うので、80番のNodePortを変数に入れておきます。
31090 / 32410
export はいまのシェルにしか残りません。 VMに入り直したら打ち直してください。
さっきの Ingress を見直す
コントローラを入れただけで、貼ってあった紙が読まれます。
NAME CLASS HOSTS ADDRESS PORTS AGE
first <none> demo.local 80 11m
まだ ADDRESS が空です。 理由は CLASS が <none> だからです。
どのコントローラが担当するかを、紙に書いていません。
担当を書きます。使える名札を確認します。
NAME CONTROLLER PARAMETERS AGE
nginx k8s.io/ingress-nginx <none> 3m
ing-first.yaml に1行足します。
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: first
spec:
ingressClassName: nginx
rules:
- host: demo.local
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: app-a-lb
port:
number: 80
NAME CLASS HOSTS ADDRESS PORTS AGE
first nginx demo.local 192.168.1.51,192.168.1.52,192.168.1.53 80 12m
ADDRESS が付きました。 読む人が現れた印です。
ADDRESS が付いたかどうかが、Ingress が生きているかの最初の判定になります。 空なら、通信の前にコントローラかクラスの問題です。
通してみる
demo.local というホスト名で来たときだけ振り分ける設定なので、ホスト名を名乗って叩きます。
Hostname: app-a-6d4b8f9c7-x2klm
IP: 10.244.1.7
RemoteAddr: 10.244.0.9:52310
GET / HTTP/1.1
Host: demo.local
X-Forwarded-For: 192.168.1.51
X-Forwarded-Proto: http
X-Real-Ip: 192.168.1.51
通りました。 そして注目するところがあります。
X-Forwarded-ForとX-Real-Ipが付いています。自分では送っていません。
これを足したのは Ingress Controller の中の nginx です。 OSI参照モデルの回で「ヘッダを足せるのが L7 の証拠」と書いた、あれと同じものが出ています。Ingress は中身を読んで、書き換えて、渡しています。
ホスト名を名乗らないとどうなるかも見ておきます。
404
一致するルールが1つも無いと 404 です。 アプリの 404 ではなく、Ingress Controller が返した 404 です。この2つを見分けられないと切り分けができません。 見分け方は後ろの⑨で書きます。
⑥ パスとホスト名で振り分ける
ここからが、Ingress を使う本当の理由です。
アプリを2つにする
2つ目を立てます。ついでに、さっき LoadBalancer で作った Service を ClusterIP に戻します。 Ingress の後ろのServiceは、外に出す必要がありません。
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
app-a ClusterIP 10.101.77.4 <none> 80/TCP 20s
app-b ClusterIP 10.109.12.88 <none> 80/TCP 20s
app-a-lb を消したので、さっきの first の Ingress は壊れています。 このあと作り直します。
パスで振り分ける
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: by-path
spec:
ingressClassName: nginx
rules:
- host: demo.local
http:
paths:
- path: /a
pathType: Prefix
backend:
service:
name: app-a
port:
number: 80
- path: /b
pathType: Prefix
backend:
service:
name: app-b
port:
number: 80
確かめます。答えた側のホスト名が変わるかを見ます。
Hostname: app-a-6d4b8f9c7-x2klm
Hostname: app-b-5f9c74d6b8-qz8tp
別のアプリが答えました。 1つのポートで2つのアプリが動いています。
[スクリーンショット: 04_path-routing.png] /a と /b に curl して、Hostname: が app-a と app-b に分かれている画面を撮ってください。
受け取ったパスがどうなっているかも見ます。
GET /a HTTP/1.1
/a がそのまま後ろへ渡っています。 アプリ側から見ると、自分は /a というURLで動いていることになります。 ここが後で問題になります(⑦で扱います)。
pathType の Prefix と Exact の違い
Prefix は「文字列の前方一致」ではありません。 ここは正しく覚える価値があります。
Prefixは、パスを/で区切った「要素」ごとの一致です。
path: /a の場合の判定はこうなります。
| 来たパス | Prefix | Exact | 理由 |
|---|---|---|---|
/a | 一致 | 一致 | 完全に同じ |
/a/ | 一致 | 不一致 | 要素としては /a と同じ。Exact は文字列が違う |
/a/detail | 一致 | 不一致 | 要素 a から始まっている |
/ab | 不一致 | 不一致 | 文字列としては前方一致だが、要素は ab で別物 |
/A | 不一致 | 不一致 | 大文字小文字は区別する |
実際に確かめます。
200
404
/ab が 404 になりました。 文字列の前方一致だと思っていると、この404の理由が絶対に分かりません。 私はここで30分溶かしました。
pathType には3つ目があります。
| 値 | 意味 |
|---|---|
Prefix | / 区切りの要素の前方一致。普段はこれ |
Exact | 完全一致。末尾の / の有無まで区別する |
ImplementationSpecific | 判定をコントローラに丸投げする。 ingress-nginx では正規表現が使える |
ImplementationSpecific は「未指定」ではありません。 「コントローラごとに動きが変わってよい」という明示的な指定です。移植性を捨てる代わりに正規表現を得る、という取引になります。
Exact の挙動も見ておきます。ing-path.yaml の /b の pathType だけ Exact に変えて適用します。
200
404
末尾のスラッシュ1文字で 404 です。 ブラウザは末尾に / を足すことがあるので、Exact は狙って使うとき以外は避けます。 確認したら Prefix に戻してください。
ホスト名で振り分ける
本命はこちらです。 パスではなく、名前で分けます。
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: by-host
spec:
ingressClassName: nginx
rules:
- host: a.demo.local
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: app-a
port:
number: 80
- host: b.demo.local
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: app-b
port:
number: 80
NAME CLASS HOSTS ADDRESS PORTS AGE
by-host nginx a.demo.local,b.demo.local 192.168.1.51,192.168.1.52,192.168.1.53 80 8s
by-path nginx demo.local 192.168.1.51,192.168.1.52,192.168.1.53 80 14m
Ingress は複数あってよく、コントローラは全部まとめて1つの設定に組み立てます。 ホスト名が重ならない限り、共存します。
まずヘッダで確認します。
Hostname: app-a-6d4b8f9c7-x2klm
Hostname: app-b-5f9c74d6b8-qz8tp
同じIP・同じポート・同じパスで、名前だけで分かれました。
/etc/hosts に足して、名前で開く
-H "Host: ..." は curl の小細工です。 ブラウザでは使えません。名前を本当に引けるようにします。
demo.local は自分専用の練習用の名前です。 実在するドメインを勝手に書かないでください。
VMの中で編集します。
末尾に1行足します。
192.168.1.51 demo.local a.demo.local b.demo.local
引けるか確かめます。
192.168.1.51 a.demo.local
ホスト名で叩けるようになりました。
Hostname: app-a-6d4b8f9c7-x2klm
Hostname: app-b-5f9c74d6b8-qz8tp
Windows のブラウザから開きたい場合は、Windows 側にも同じ行が要ります。 場所は C:\Windows\System32\drivers\etc\hosts で、管理者権限のメモ帳でないと保存できません。 保存に失敗したときは、書き換えたつもりで元のままです。 開く前に、PowerShell で Get-Content C:\Windows\System32\drivers\etc\hosts | Select-Object -Last 3 を打って、行が入ったか確認してください。
戻し方: 足した1行を消して保存するだけです。他の行は消さないでください。 127.0.0.1 localhost の行を消すと、別の不具合が出ます。
rewrite-target — Kubernetes の機能ではない
⑥の途中で見たとおり、path: /a で振り分けると、アプリには /a というパスがそのまま届きます。
多くのアプリはこれで壊れます。 アプリは自分が / の下にいるつもりなので、/a/style.css を /style.css として探しに行きます。
そこで、後ろへ渡すときにパスを削ります。
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: by-rewrite
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
ingressClassName: nginx
rules:
- host: rw.demo.local
http:
paths:
- path: /a(/|$)(.*)
pathType: ImplementationSpecific
backend:
service:
name: app-a
port:
number: 80
/etc/hosts の行に rw.demo.local を足してから、確かめます。
GET /hello HTTP/1.1
/a が消えて、/hello として届きました。 $2 は正規表現の2つ目の括弧、つまり (.*) の中身です。
ここで一番大事なのは、動いたことではありません。
nginx.ingress.kubernetes.io/rewrite-targetは、Kubernetes の仕様に存在しません。 これは ingress-nginx が独自に読んでいる、ただのメモ書き(注釈)です。
確かめられます。 注釈の名前を1文字変えて適用してみてください。
エラーは出ません。 そして書き換えも起きません。 Kubernetes は注釈の中身を検査しないからです。
この性質から、次のことが言えます。
- Traefik に乗り換えると、この注釈は無視されます。 Traefik は
Middlewareというリソースで同じことをします nginx-ingress(nginx社版)でも名前が違います。 検索で出た注釈をコピーしても効きません- 注釈が効かないとき、
kubectlはいつも成功します。 成功したのに変わらないときは、まず注釈のスペルを疑ってください
「Ingress は共通、注釈は方言」と覚えると整理できます。そして実務のIngressは、たいてい方言の部分が一番長くなります。 この歪みを直そうとしているのが、後で触れる Gateway API です。
⑦ TLS を付ける — 自己署名で確かめる
Ingress のもう1つの役目が、証明書を1か所にまとめることです。
この節では、自分のVMの中だけで完結する自己署名の証明書を使います。 本番のドメインでは試さないでください。 理由は2つです。Let’s Encrypt には失敗の回数制限があり、短時間で叩くとそのドメインが数時間ブロックされます。 そして外から到達できるサーバーでないと、そもそも発行されません。
証明書を作る
..+..+.......+..+.......+...+..+......+...
-----
できたものを確認します。
subject=CN = a.demo.local
notBefore=Sep 25 04:12:03 2026 GMT
notAfter=Sep 25 04:12:03 2027 GMT
subjectAltName を入れているのが要点です。 CN だけの証明書は、いまのブラウザとcurlは受け付けません。 これを知らずに -addext を省くと、後で「名前が一致しない」で必ず詰まります。
Secret にする
証明書はファイルのままでは使えません。クラスタの中に置きます。
NAME TYPE DATA AGE
demo-tls kubernetes.io/tls 2 3s
kubernetes.io/tls という型が付いているのが大事です。 ただの Secret に手で tls.crt を入れても、Ingress Controller は使いません。
Ingress に付ける
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: by-tls
spec:
ingressClassName: nginx
tls:
- hosts:
- a.demo.local
secretName: demo-tls
rules:
- host: a.demo.local
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: app-a
port:
number: 80
tls: の hosts: と rules: の host: は、必ず同じ名前にします。 片方だけ直すと、既定の証明書(Kubernetes Ingress Controller Fake Certificate)が出てきます。その名前が出たら、この2つのズレを疑ってください。
by-host の a.demo.local と重なるので、先に消してから適用します。
確かめる
HTTPS用のNodePortに繋ぎます。
Hostname: app-a-6d4b8f9c7-x2klm
通りました。 -k を外すとどうなるかも、必ず見ておきます。
curl: (60) SSL certificate problem: self-signed certificate
これが自己署名の限界です。 暗号は本物と同じ強さでかかっています。 足りないのは「この証明書を保証する第三者」だけです。通信が読まれるかどうかと、相手が本物かどうかは、別の話です。
どの証明書が使われたかも見られます。
* subject: CN=a.demo.local
[スクリーンショット: 05_tls-selfsigned.png] -k なしで curl して、自己署名の証明書エラーが出ている画面を撮ってください。
本物の証明書はどうするか
名前だけ置いておきます。
cert-manager… クラスタに入れておくと、Ingress を見て証明書を自動で取得し、期限が来る前に自動で更新する部品です。Let’s Encrypt と組み合わせるのが定番です。
ただし、外から到達できるドメインとサーバーが要ります。 練習用のVMには入れません。 HTTPS強制の回で手動でやったことを、Kubernetes の中で自動にするもの、と考えておけば十分です。
⑧ Gateway API — Ingress の後継
Ingress を覚えた直後に言うのは気が引けますが、後継が既にあります。
⑥で見たとおり、Ingress の本体の仕様は小さく、実務で必要なことのほとんどが注釈に逃げています。 ヘッダの書き換えも、重み付きの振り分けも、TLSの細かい設定も、全部が方言です。そして注釈は型が無く、間違っても何も言われません。
Gateway API は、そこを作り直したものです。
| Ingress | Gateway API |
|---|---|
Ingress 1種類 | GatewayClass / Gateway / HTTPRoute に分かれている |
| 注釈で拡張 | 仕様として型のあるフィールドで書く |
| 誰が何を決めるか曖昧 | インフラ担当が Gateway、アプリ担当が HTTPRoute と役割で分かれる |
この記事で入れた ingress-nginx は、2026年3月で保守が終わりました。 以降はセキュリティ修正も出ず、Kubernetes の SIG Network と Security Response Committee は、利用者にすぐ Gateway API か別の Ingress コントローラへ移るよう勧めています。Ingress という仕組み自体は非推奨になっていませんが、これから作るなら Gateway API か保守中のコントローラを選んでください(Gateway API もコントローラを別途入れる必要があります)。
押さえておくのはこの1点だけで十分です。
いま注釈で書いていることが、将来は正式なフィールドになる。 だから注釈を「Kubernetesの機能」だと覚えないほうがいい。
⑨ どれを使うか — 自前かクラウドかで変わる
ここまでの3つを、2軸の表にまとめます。
| 自前(kubeadm / k3s / 自宅) | クラウド(EKS / GKE / AKS) | |
|---|---|---|
| NodePort | 動く。 番号付きURLになる。学習と社内ツールなら十分 | 動くが、セキュリティグループで塞がれていることが多い。使わない |
| LoadBalancer | <pending>。 MetalLB を入れれば動く。IPを消費する | そのまま動く。 1つ作るたびに課金される |
| Ingress | Controller を自分で入れる。 その Controller が NodePort か MetalLB を使う | Controller を自分で入れる。 その Controller が LoadBalancer を1つ使う |
そして、選ぶときの判断はもっと単純です。
| 状況 | 選ぶもの |
|---|---|
| 動けばいい・自分しか使わない | NodePort |
| HTTP以外(DBやゲームサーバーなど)を外に出す | LoadBalancer(自前なら MetalLB) |
| HTTP/HTTPS のアプリが2個以上ある | Ingress |
| ドメイン名で分けたい・証明書をまとめたい | Ingress |
一番よくある間違いは、「Ingress を使えば LoadBalancer は要らない」だと思うことです。 ①の図のとおり、クラウドの Ingress は、下で LoadBalancer を1つ使っています。 アプリごとに1つずつ作るのをやめて、全体で1つにまとめているだけです。そしてその1つが、そのまま料金の差になります。
もう1つの間違いは、「Ingress は何でも外に出せる」です。 Ingress は HTTP と HTTPS 専用です。 MySQL や Redis を外に出したいときには使えません。そこは LoadBalancer か NodePort の仕事です。マネージドKubernetesの回で書いた「EKSでも消えない仕事」に、この判断も入ります。
自宅のネットワークで空いているIPを使えない場合は、公開IPが最初から付いてくるVPSに小さなクラスタを組んで、NodePortやIngressの振る舞いを外から確かめる方法もあります。さくらのVPS
は東京・大阪・石狩からリージョンを選べる国産VPSで、2026年11月時点の公式表示では2GB(3コア・100GB)が月払い1,738〜1,958円(税込、リージョンで異なる)、クレジットカード払いなら2週間の無料お試しがあります。お試し中は外向き通信が10Mbpsに制限され、解約しないと自動で本登録になる点は先に確認してください。
⑩ 繋がらないときの切り分け
Ingress が繋がらないときの原因は、だいたい4つのどこかにあります。 必ずこの順番で見ます。 順番を飛ばすと、動いているものを疑って時間を溶かします。
1. Controller は動いているか
Running かつ 1/1 でなければ、ここから先を見ても無駄です。
Pending のままなら、たいていメモリ不足です。 0/3 nodes are available: Insufficient memory のような文が出ます。
2. Ingress に ADDRESS が付いたか
空なら、通信の問題ではありません。 見るのは2つです。
CLASS が <none>、または ingressclass に無い名前を書いていると、誰も読みません。 ④で見たとおりです。
3. Service とアプリは生きているか
Ingress を通さずに、中から直接叩きます。
ここで繋がらないなら、Ingress は無関係です。 Service のセレクタか Pod の問題です。先にそちらを直します。
Service が Pod を掴んでいるかは、これで一発で分かります。
NAME ENDPOINTS AGE
app-a 10.244.1.7:80 31m
ENDPOINTS が <none> なら、Service はどのPodにも繋がっていません。 ラベルのズレです。
4. パスとホスト名は合っているか
404 が出たとき、それが誰の404かを見分けます。
HTTP/1.1 404 Not Found
Server: nginx
Server: nginx だけで本文が短いものは、Ingress Controller が返した404(=ルールに一致しなかった)です。アプリまで届いていません。
最後の手段は、組み立てられた設定をそのまま読むことです。
これが一番速いことがよくあります。 nginxのリバースプロキシの回で読んだのと同じ形の設定が、Ingress から自動生成されて入っています。 自分の path がここに現れていなければ、YAMLは読まれていません。
ログも見ます。アクセスのたびに1行出ます。
ログに1行も出ないなら、通信がコントローラまで届いていません。 そこはファイアウォールかポート番号の問題で、Ingress の設定の問題ではありません。本線で ufw を触っている場合は、NodePort の範囲が開いているか確認してください。
つまずいたところ
<pending> を「クラスタの組み方の失敗」だと思って、kubeadm からやり直した。 3台を全部作り直して2時間かけて、まったく同じ <pending> が出てようやく考え直しました。エラーが出ていないものを「壊れている」と判断したのが間違いでした。 Events: <none> は「何も起きていない」であって「失敗した」ではありません。誰も担当していない状態を表す表示です。
Ingress を apply して created が出たので、動いていると思い込んだ。 そこから path の書き方を3種類試して、host を消してみて、名前空間を疑いました。Controller を入れていませんでした。 kubectl apply が通ることは、動作の保証を1ミリもしません。 それ以来、apply のあとに必ず get で ADDRESS か EXTERNAL-IP を見るようにしています。
ingress-nginx の cloud 版を入れて、また <pending> を見た。 公式ドキュメントのトップにあるコマンドをコピーしました。導入コマンドが環境別に分かれていることに気づいていませんでした。 自前のクラスタなら baremetal、クラウドなら cloud です。同じ製品なのに入れるファイルが違うというのは、そのとき初めて知りました。
/ab が 404 になる理由が分からず30分溶かした。 path: /a を Prefix にしたので、/ab も通ると思っていました。Prefix は文字列の前方一致ではなく、/ 区切りの要素の一致です。 仕様書を読むまで分かりませんでした。言葉が同じでも意味が違うものの代表例です。
rewrite-target の注釈を打ち間違えて、1時間気づかなかった。 nginx.ingress.kubernetes.io の kubernetes を kuberentes と打っていました。kubectl は何も言いません。注釈はただの文字列だからです。 それ以来、注釈が効かないときは、まずスペルをコピーで貼り直すことにしています。
自己署名の証明書で、CN だけ指定して詰まった。 curl が「名前が一致しない」と言い続けました。いまの検証は subjectAltName を見ます。 CN は互換のために残っているだけで、実質もう使われていません。古い記事のコマンドをそのままコピーしたのが原因でした。
tls: の hosts: だけ直して、rules: の host: を直し忘れた。 出てきたのは Kubernetes Ingress Controller Fake Certificate という、見覚えのない証明書でした。一致する証明書が無いときの既定値です。この名前が出たら、必ず名前のズレを疑ってください。
Ingress を消したのに、コントローラを消し忘れて2日間メモリを食われていた。 ワーカーで別のPodが Pending になり、原因を探して見つけました。Ingress Controller は、Ingress を全部消しても動き続けます。 後片づけでは必ず両方消します。
後片づけ
作ったものを全部消します。対象を必ず読んでから打ってください。
Ingress と証明書を消します。
アプリを消します。
名前空間ごと消します。中に残っていたものもまとめて消えます。
ここを忘れると、メモリを食われ続けます。 Ingress Controller を消します。
③をやった人は、MetalLB も消します。
既定の名前空間を戻します。 これを忘れると、次回 kubectl get pods が何も返さず混乱します。
/etc/hosts に足した行を消します。
足した1行だけを消してください。 127.0.0.1 localhost などの行は残します。
作ったファイルを消します。秘密鍵が含まれています。
空きメモリが戻ったか見ます。
本線で作ったものが無事か確認します。
まとめ — 理解できたこと
type: LoadBalancerは機能ではなく注文票。 注文を受ける担当者はクラスタの外にいて、自前のクラスタには最初からいない。だから<pending>は正常な状態Events: <none>は「失敗」ではなく「誰も担当していない」。 エラーが出ないことを「動いている」と読まない- 同じYAMLがクラウドで動いて自前で止まるのは、YAMLの問題ではなく周りの環境の差。 逆方向も同じだけ起きる
- Ingress は紙。読む人(Ingress Controller)を入れるまで、
applyが通っても何も起きない。 同じ構図がtype: LoadBalancerにも PVC にもある ADDRESSが付いたかどうかが、Ingress が読まれた印。 空なら通信ではなくクラスとコントローラを見るingressClassNameを書かないと、コントローラを入れても担当が決まらないpathType: Prefixは文字列の前方一致ではない。/で区切った要素の一致なので、/aは/abに一致しないExactは末尾のスラッシュまで区別する。 狙って使うとき以外はPrefixrewrite-targetは Kubernetes の仕様に無い。 ingress-nginx が独自に読む注釈で、Traefik では効かない。しかも間違えてもエラーにならない- 「Ingress は共通、注釈は方言」。 実務の Ingress は方言のほうが長くなる。その歪みを直しているのが Gateway API
- Gateway API は後継。Ingress は非推奨ではないが、ingress-nginx は2026年3月で保守終了。 これから作るなら Gateway API か保守中のコントローラ。注釈をKubernetesの機能だと覚えないことだけが今日の収穫
- 自己署名の証明書でも、暗号の強さは本物と同じ。 足りないのは第三者の保証だけ。
subjectAltNameが無い証明書は、いまのcurlもブラウザも受け付けない - Ingress は HTTP と HTTPS 専用。 DBを外に出すときは LoadBalancer か NodePort の仕事
- Ingress を入れても LoadBalancer が不要になるのではなく、必要な数が「アプリの数」から「1つ」に減る。 クラウドではその差がそのまま料金になる
- 繋がらないときは4段階。 Controller が動いているか →
ADDRESSが付いたか → Service が Pod を掴んでいるか → パスとホスト名が合っているか。順番を飛ばさない - Ingress を全部消しても、Ingress Controller は動き続ける。 片づけるときは両方消す
参考リンク
- roadmap.sh — Kubernetes
- Kubernetes 公式 — Ingress
- Kubernetes 公式 — Ingress Controllers
- Kubernetes 公式 — Service の type
- Kubernetes 公式 — Gateway API
- Gateway API 公式サイト
- ingress-nginx 公式ドキュメント
- ingress-nginx — 導入方法
- ingress-nginx — 注釈の一覧
- ingress-nginx — Rewrite の例
- MetalLB 公式サイト
- MetalLB — Layer 2 の設定
- cert-manager 公式ドキュメント
- Traefik — Kubernetes Ingress プロバイダ
- traefik/whoami のリポジトリ
次に読む
この記事は 【深掘り】Kubernetes の 5 / 15 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- LoadBalancer が pending になる理由
- Ingress Controller とパス・ホスト振り分け
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント