安装 Istio
入口网关、集群内路由与 sidecar 注入。装对了是透明的,装错了表现为 503 与莫名其妙的 404。
FewBox 只用 Istio 的两件事:给外部流量一个入口,以及在集群内按主机名路由到具体服务。 熔断、限流、高级流量治理都没有用到——所以按最小 profile 装即可,不要引入额外的 CR。
1. 版本:固定小版本,不使用 addon
参考环境实测 1.30.2。Istio 的跨小版本行为差异(尤其是 Gateway / VirtualService 的字段
演进与 mTLS 默认值)会在不报错的地方悄悄改变路由,因此:
- 固定一个次版本(如 1.30.x),升级单独做一次变更;
- 不要用
microk8s enable istio——该 addon 的版本随 snap 走,装机时是多少以后就是多少, 且升级 snap 会连带升级 Istio; - 装完后用镜像标签确认实际版本,不要信
istioctl version(它可能因为 revision 不同而"看不见"):
kubectl get pods -A -l app=istiod \
-o jsonpath='{range .items[*]}{.metadata.namespace}{"/"}{.metadata.name}{"\t"}{.spec.containers[0].image}{"\n"}{end}'
2. 安装
从发布页下载 tar 包安装最稳;目标主机访问不了 GitHub 时,在本机下载后 scp 过去(大陆网络的完整处理见中国大陆网络):
# 在有网/能下载的机器上取发布包:https://github.com/istio/istio/releases
scp istio-1.30.0-linux-amd64.tar.gz <用户>@<主机>:/root/
tar -xzf istio-1.30.0-linux-amd64.tar.gz
cd istio-1.30.0
export PATH=$PWD/bin:$PATH
istioctl version
安装前确认镜像能拉(标签按您固定的次版本替换;走镜像加速时要带 --hosts-dir,见中国大陆网络):
sudo microk8s ctr images pull docker.io/istio/pilot:1.30.0
安装:
istioctl install --set profile=default --set hub=docker.io/istio
--set hub=docker.io/istio 把官方清单里的 registry.istio.io 换成 Docker Hub 上的官方镜像。
两个仓库都能用;需要镜像加速时(如中国大陆网络环境)换到 Docker Hub 更方便,原因见
中国大陆网络。
sidecar 的资源请求要压下来
default profile 给每个 istio-proxy 预留 100m CPU / 128Mi 内存。单机 4C/8G 上乘以 Pod 数会
直接吃满调度容量(新 Pod Pending)。压到 25m 起步:
istioctl install --set profile=default --set hub=docker.io/istio \
--set values.global.proxy.resources.requests.cpu=25m
装完看节点实际分配:
kubectl describe node <节点名> | grep -A6 "Allocated resources"
3. 入口:没有 LoadBalancer 就用 NodePort
单机 MicroK8s 没有 MetalLB,istio-ingressgateway 是 LoadBalancer 类型但 EXTERNAL-IP 永远
<pending>。这不影响使用——K8s 仍会给它分配 NodePort:
kubectl -n istio-system get svc istio-ingressgateway
参考环境的分工:
| Service 端口 | NodePort | 用途 |
|---|---|---|
| 80 | <http-nodeport> |
全部公网 HTTP,由边缘 nginx 反代进来 |
| 443 | <https-nodeport> |
未配置 TLS server,实际不使用;TLS 在边缘终止 |
| 15021 | <status-nodeport> |
就绪探针 |
查自己的 NodePort:
kubectl -n istio-system get svc istio-ingressgateway \
-o jsonpath='{.spec.ports[?(@.port==80)].nodePort}{"\n"}'
这个值就是边缘 nginx 里 proxy_pass 要填的端口。
不建议直接使用 443 的 NodePort。 端口通不代表能握手——
Gateway里没有配TLSserver 时, 打过去是明文 HTTP 或直接断连。证书放边缘,见下一章。
4. Gateway 与 VirtualService 的形状
入口有两个 Gateway(都在业务命名空间里,selector 都指向 istio: ingressgateway):
| Gateway | hosts | 端口 | 用途 |
|---|---|---|---|
internet |
产品域名及其通配(titanides.com、*.titanides.com) |
80 / HTTP | 公网入口 |
intranet |
*.internal.titanides.com |
80 / HTTP | 内网直连,调试用 |
内网域名怎么起:不要用
.local——RFC 6762 把它保留给 mDNS,macOS 和装了 Avahi 的 Linux 会先发组播查询,解析变慢,甚至随机失败。.lan很常见,但从未被保留,将来可能被正式注册,也可能 与客户已有的公网域撞名。2024 年 7 月 ICANN 已把.internal永久保留给私有网络 (IANA 公告)。 最简单的做法是挂在您自己的域名下面(如internal.titanides.com),内网 DNS 做视图(split-horizon); 确实需要一个独立后缀时,用.internal。
internet 只声明 80 端口,没有 tls: 段——这是有意的:证书在集群外,Istio 只看 Host 头。
所以诊断"域名打开是 404"时,第一步永远是确认请求带的 Host 与某个 VirtualService 的 hosts
完全一致,而不是去查证书。
每个对外服务一条 VirtualService。参考环境 12 条,分三类:
- 公网:
accounts.titanides.com、gateway.titanides.com、titanides.com与www.titanides.com、控制台域名各一条; - 内网:
tethys-*.titanides.com这类管理台; - mesh:
*-mesh两条,gateways: ["mesh"],hosts填的是 Service 名(如fewbox-thia-gateway)。这两条让集群内的 Pod 用 Service 名访问时也走 Istio 路由—— 没有它们,sidecar 之间的调用会绕过 VirtualService,CORS 与超时表现与外部访问不一致。
最容易错的一处:路由指向 subset
参考环境的 VirtualService 不是直连 Service,而是指向 DestinationRule 的 subset:
# VirtualService(片段)
http:
- route:
- destination:
host: fewbox-thia-gateway
port: { number: 80 }
subset: v4 # ← 指到 subset,不是 Service
---
# DestinationRule(片段)
spec:
host: fewbox-thia-gateway
subsets:
- name: v4
labels: { version: v4 } # ← subset 靠 Pod 标签选
trafficPolicy:
tls: { mode: ISTIO_MUTUAL }
于是升级一个服务要同步改四处,少一处就是 503(no healthy upstream):
| # | 位置 | 参考环境的值 |
|---|---|---|
| 1 | Deployment 名 | fewbox-<服务>-v4 |
| 2 | Pod 模板标签 version |
v4 |
| 3 | DestinationRule.subsets[].name 与 labels.version |
v4 |
| 4 | VirtualService 的 destination.subset |
v4 |
用 Bundle 部署时这四处由 operator 一起生成,不会错位;手工改镜像版本时最容易只改第 1 处, 现象是 Pod 全新、
kubectl get pods一切正常,但域名一访问就 503。判断依据:kubectl -n <ns> get dr <服务> -o yaml里的 subset 标签,与 Pod 实际标签对不上。
5. sidecar 注入与 mTLS
命名空间打标签即整命名空间注入:
kubectl label namespace <命名空间> istio-injection=enabled
注入后每个 Pod 是 2/2(业务容器 + istio-proxy)。已有 Pod 不会自动补 sidecar,要
kubectl rollout restart deploy。
参考环境的策略:
- 默认没有
PeerAuthentication,即 mTLS 为 permissive,不是 STRICT。这很重要:不带 sidecar 的客户端(如集群内的定时任务)仍能访问服务; - 若您启用 STRICT mTLS,定时任务那个每分钟敲 agent 的 CronJob 必须标
sidecar.istio.io/inject: "false"且不能走 STRICT,否则心跳静默停摆; - 同一个服务的 Service 选 Pod 用
app: fewbox-<服务>,sidecar 会把 canonical 标签补齐。
6. 可观测性(可选)
参考环境没有启用 tracing:istio-system 里只有 istiod 与 ingressgateway,没有
jaeger / prometheus / kiali,meshConfig 里也没有 enableTracing。业务侧的
OTEL_EXPORTER_OTLP_ENDPOINT 即使填了地址,TRACING_ENABLED=false 时也不会发数据。
需要时按这个顺序开(示例装的是官方 addon,仅适合 POC):
kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.30/samples/addons/prometheus.yaml
kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.30/samples/addons/jaeger.yaml
kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.30/samples/addons/kiali.yaml
Jaeger 的 Service 默认只开 14268 / 14250 / 9411,没有 OTLP 的 4317/4318。要收 OTLP 得开开关 并补端口:
kubectl -n istio-system set env deploy/jaeger COLLECTOR_OTLP_ENABLED=true
kubectl -n istio-system patch svc jaeger-collector --type=json -p='[
{"op":"add","path":"/spec/ports/-","value":{"name":"otlp-grpc","port":4317,"targetPort":4317,"protocol":"TCP"}},
{"op":"add","path":"/spec/ports/-","value":{"name":"otlp-http","port":4318,"targetPort":4318,"protocol":"TCP"}}
]'
然后注册 provider,并让 mesh 默认走它:
kubectl -n istio-system patch configmap istio --type merge -p '
data:
mesh: |
enableTracing: true
defaultProviders:
tracing:
- otel-tracing
extensionProviders:
- name: otel-tracing
opentelemetry:
service: jaeger-collector.istio-system.svc.cluster.local
port: 4317
- name: zipkin
zipkin:
service: zipkin.istio-system.svc.cluster.local
port: 9411
'
kubectl -n istio-system rollout restart deploy/istiod
kubectl rollout restart deploy -n <业务命名空间>
采样率用 Telemetry 资源控制(telemetry.istio.io/v1alpha1,1.30 上仍是 v1alpha1):
apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
name: mesh-tracing
namespace: istio-system
spec:
tracing:
- providers:
- name: otel-tracing
randomSamplingPercentage: 100.0 # 调试期;稳定后降到 10 以下
验证链路真的通了
不要只看 kubectl get pods 全绿——sidecar 里有没有这段配置是唯一证据:
POD=$(kubectl -n <业务命名空间> get pod -l app=<服务> -o jsonpath='{.items[0].metadata.name}')
kubectl -n <业务命名空间> exec "$POD" -c istio-proxy -- \
curl -s localhost:15000/config_dump | grep -B2 -A10 -i opentelemetry | head -40
看到 opentelemetry 的 exporter 段才算接上。看不到,说明 meshConfig 没生效或 Pod 没重启。
看 Traces 时不需要暴露 Jaeger 到公网,用端口转发 + SSH 隧道即可:
kubectl -n istio-system port-forward svc/tracing 16686:80
ssh -L 16686:127.0.0.1:16686 <用户>@<主机>
7. 装完自检
kubectl -n istio-system get pods # istiod 与 ingressgateway 均 Running
kubectl get gateway,vs -A # 入口与路由都在
kubectl get svc -n istio-system istio-ingressgateway # 记下 80 的 NodePort
curl -H 'Host: gateway.titanides.com' http://<节点IP>:<NodePort>/
最后那条是最快的判断:返回的不是 404,说明 Host 匹配与路由都通了;404 就去看 vs 的 hosts
拼写,503 就去看 subset。