HelloWorld Ingress 配置教程

要快速搭好 HelloWorld Ingress，先把应用和 Service 部署好，再安装一个 Ingress Controller 并把它暴露出来，最后写一份正确的 Ingress 资源（host、path、pathType、tls、必要注解）。下面我会一步步演示可直接运行的 YAML、安装命令、测试命令和常见排错方法，兼顾 nginx 与 Traefik 两类控制器，并解释各字段为什么要这样写，让你能立刻把 HelloWorld 暴露到外网并排查常见问题。

Table of Contents

为什么需要 Ingress？先把原理说清楚

想像你有很多微服务，每个服务都有自己的 Service（ClusterIP/NodePort/LoadBalancer），但外网只有一个或少数几个 IP。Ingress 的作用是把外部请求从单点入口路由到集群内不同服务上，并在入口处做 TLS 终止、虚拟主机、路径路由等处理。Ingress 本身是一个 API 对象，但要真正生效必须有一个 Ingress Controller 去监听这些资源并配置底层的代理（比如 nginx、traefik、haproxy 等）。

要点回顾（简单）

Ingress 资源：描述路由规则（host、path、tls、注解）
Ingress Controller：实现Ingress行为，读取资源并配置代理
Service：Ingress 将请求转发到 ClusterIP/Service 的后端 Pod

环境与准备工作

下面这些是最常见的准备项，按需执行：

已安装 Kubernetes 集群（minikube、kind、云厂商 k8s 等）
kubectl 已配置并能访问集群
有 Helm （可选，但安装 controller 很方便）
熟悉基本 kubectl 操作（apply、get、describe、logs）

一：部署一个最小 HelloWorld 应用与 Service

先把应用和对应 Service 搭好，Ingress 只是把请求转过去。

Deployment + Service 示例

下面是一个简单的 nginx HelloWorld 示例（可直接 kubectl apply -f）：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: helloworld
spec:
  replicas: 2
  selector:
    matchLabels:
      app: helloworld
  template:
    metadata:
      labels:
        app: helloworld
    spec:
      containers:
      - name: nginx
        image: nginx:stable
        ports:
        - containerPort: 80
        # 简单自定义一个 index.html 可以用 ConfigMap 或直接改镜像
---
apiVersion: v1
kind: Service
metadata:
  name: helloworld-svc
spec:
  selector:
    app: helloworld
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
  type: ClusterIP

关键点：Service 名称要和 Ingress backend 指定的一致，端口也要对上（Service.port，不是 containerPort）。

二：安装 Ingress Controller（以 nginx 为例）

Ingress 只是声明，实际路由由 Controller 承担。这里给两个常见选项的简要安装方式。

方法 A：使用 Helm 安装 ingress-nginx

如果能访问 Helm 仓库，推荐：

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm install ingress-nginx ingress-nginx/ingress-nginx --namespace ingress-nginx --create-namespace

安装成功后会创建一个 Service（默认是 LoadBalancer 或 NodePort，取决于集群环境），用来接收外部流量。

方法 B：minikube / 本地调试

minikube：minikube addons enable ingress
kind：通常需要手动部署 Ingress Controller 并通过 NodePort/HostPort 暴露，或使用端口映射

验证 Controller 是否就绪

kubectl get pods -n ingress-nginx
kubectl get svc -n ingress-nginx 查看外部 IP 或 NodePort

三：写一个最简单的 Ingress（HTTP）并测试

先做最简单的路径路由：host + path 指向 helloworld-svc。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: helloworld-ingress
  annotations:
    kubernetes.io/ingress.class: "nginx"
spec:
  rules:
  - host: hello.example.com
    http:
      paths:
      - path: /hello
        pathType: Prefix
        backend:
          service:
            name: helloworld-svc
            port:
              number: 80

应用后请确认：

kubectl apply -f ingress.yaml
kubectl get ingress 查看 ADDRESS 和 HOSTS
从外部用 curl 测试（示例）：curl -H “Host: hello.example.com” http:///hello

四：TLS 配置（手动证书与 cert-manager）

Ingress 支持 TLS。两种常见方式：手动创建 tls secret，或使用 cert-manager 自动申请证书。

手动创建 TLS Secret

kubectl create secret tls hello-tls \
  --cert=./tls.crt \
  --key=./tls.key \
  -n default

Ingress 示例如下：

spec:
  tls:
  - hosts:
    - hello.example.com
    secretName: hello-tls
  rules:
  - host: hello.example.com
    http: ...

使用 cert-manager 自动申请 Let’s Encrypt 证书

简要流程：安装 cert-manager -> 创建 ClusterIssuer（ACME）-> 在 Ingress 上加注解并设置 tls.secretName。实际命令省略，这里要注意 cert-manager 需要能验证域名（HTTP-01 或 DNS-01）。

五：常见进阶场景与配置示例

路径重写（rewrite）

如果你的后端期望根路径 /，但外部路由是 /app，需要做重写。nginx ingress 常用注解：

metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
  - http:
      paths:
      - path: /app
        pathType: Prefix
        backend: ...

注意：某些 nginx 版本对正则重写支持特殊注解，尽量使用简单的 Prefix + 固定 rewrite。

WebSocket / gRPC 支持

WebSocket：nginx ingress 默认支持，只要后端正确升级连接（Upgrade/Connection header）
gRPC：需要明确使用 HTTP/2，Ingress Controller 与 Service 之间需保持 HTTP/2，nginx-ingress 可通过注解或端口配置支持 gRPC

Canary 发布（简单示例）

可以通过两个 Ingress 或注解配合权重实现金丝雀。不同 controller 的实现不同：nginx 可用 TrafficSplit、或使用 ingress-nginx 的 canary 注解。

限流、白名单、基本认证

限流（rate-limit）：nginx.ingress.kubernetes.io/limit-connections、limit-rps 注解
IP 白名单：nginx.ingress.kubernetes.io/whitelist-source-range
Basic Auth：借助 Secret + nginx.ingress.kubernetes.io/auth-type: basic 等注解

六：完整示例（整套 YAML：Deployment + Service + Ingress + TLS secret 命令）

把前三步组合起来，你可以直接按顺序执行：

# 1) 部署应用与 Service（见上文示例）
kubectl apply -f helloworld-deployment-svc.yaml
2) 安装 ingress controller（示例 Helm）
helm install ingress-nginx ingress-nginx/ingress-nginx --namespace ingress-nginx --create-namespace
3) 创建 TLS Secret（若使用手动证书）
kubectl create secret tls hello-tls --cert=./tls.crt --key=./tls.key
4) 应用 Ingress 资源
kubectl apply -f helloworld-ingress.yaml

七：诊断与排错清单（最常遇到的问题）

下面是按症状给出的快速检查项，很实用。

Ingress 无 ADDRESS 或无法访问：确认 Ingress Controller Pod 是否就绪，Service 类型是否暴露外网（LoadBalancer/NodePort），并查看 Controller 日志。
访问返回 404：检查 Ingress 的 host 与 path 是否匹配请求（curl -H “Host: your-host” …），确认 Service 名称和端口是否正确。
TLS 证书不生效：检查 secret 是否在同一命名空间、secret 名称是否写对、cert-manager 的 Challenge 是否成功。
302/重定向循环：通常由后端与 ingress 都做了 TLS/HTTP 强制重定向，检查注解与后端配置。
WebSocket 断开：检查代理是否保留 Upgrade 头部与连接保持设置。

常用调试命令

kubectl describe ingress helloworld-ingress
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller
kubectl get svc -n ingress-nginx 查看外部地址或端口
curl -v -H “Host: hello.example.com” http:///hello

八：表格：Ingress 关键字段快速说明

字段	说明
rules[].host	虚拟主机名，用于基于 host 的路由匹配
rules[].http.paths[].path	路径匹配，例如 /hello 或 /api，配合 pathType 使用
rules[].http.paths[].pathType	匹配类型：Prefix、Exact、ImplementationSpecific（推荐 Prefix）
spec.tls	定义 TLS 使用的 hosts 与 secretName（用于 HTTPS）
metadata.annotations	Ingress Controller 专用配置（rewrite、限流、认证等）
kubernetes.io/ingress.class 或 ingressClassName	指定哪个 Controller 来处理该 Ingress

九：不同 Controller 的差异（简述）

不要把所有注解都当成通用：nginx、traefik、kong、istio 等 controller 的注解和功能实现各不相同。通常做法是：

选择一个 controller（团队一致）并读它的注解文档
尽量使用标准字段（host/path/tls），把 controller 特性放在 annotations

十：实战小贴士（那些能节省时间的经验）

开发环境把 host 映射到 Ingress IP（/etc/hosts 或 DNS）方便测试
优先用 Host header 做测试：curl -H “Host: hello.example.com” http://IP
路径匹配用 Prefix 更直观且兼容性好，正则仅在确有必要时使用
如果遇到 502/503，优先检查后端 Service 的 endpoints（kubectl get endpoints）是否为空
在多租户场景，注意 Ingress 与 Secrets 的命名空间限制和 RBAC 权限

说到这里，其实关键不在于记住每一个注解，而是理解请求从外到内的路径：外部 IP -> Ingress Controller -> Ingress 规则匹配 -> Service -> Pod。掌握了这条链路，遇到问题就能逐步缩小范围。按文中的 YAML 先跑一遍，遇到异常按诊断清单一步步排查，大多数问题都能迎刃而解。就这样，你可以开始把 HelloWorld 曝露出去，然后在这个基础上逐步加上 TLS、限流、Canary 等更复杂的逻辑。祝你调试顺利，记得把那些临时改动记录下来，以免下次忘了哪里改过。

返回首页