GeekIt

istioctl命令速查

安装管理、配置分析、proxy-config 排查、运行时调试、流量验证、注入与升级等 118 条命令

共 118 条命令 · 10 类场景 · 点击右侧图标可复制

命令说明复制
istioctl version查看客户端版本
istioctl version --remote查看控制面与数据面各组件版本,升级前后必看
istioctl install --set profile=default -y按默认 profile 安装控制面
istioctl install -f istio-config.yaml -y用自定义 IstioOperator 配置安装
istioctl profile list列出内置 profile(minimal、default、demo、ambient 等)
istioctl profile dump demo查看某个 profile 的完整配置,便于裁剪
istioctl profile diff default demo对比两个 profile 的差异,规划生产配置
istioctl manifest generate -f istio-config.yaml > istio.yaml只生成清单不安装,适合 GitOps 管理
istioctl install --set revision=1-20-1 -y按修订版本安装,支持金丝雀升级
istioctl tag list查看修订标签与默认版本映射
istioctl tag set prod --revision 1-20-1把命名空间注入指向指定修订版本
istioctl x uninstall --purge卸载 Istio 并清理 CRD(谨慎,会丢失全部配置)
istioctl --context prod -n istio-system version指定集群上下文与命名空间
命令说明复制
istioctl analyze -A全集群配置检查,最常用的巡检命令
istioctl analyze -n app只检查指定命名空间
istioctl analyze -f service.yaml检查本地 YAML 文件,无需连接集群
istioctl analyze --use-kube=false -f ./manifests离线分析整个目录
istioctl analyze --suppress "IST0102=Namespace/app"抑制已知告警,聚焦新问题
istioctl proxy-status查看每个 Envoy 的配置同步状态(SYNCED/STALE/NOT SENT)
istioctl proxy-status <pod>只看单个 Pod 的同步情况
istioctl proxy-status -o wide显示更多列,含版本与推送时间
istioctl x precheck升级前环境预检,提前发现不兼容
istioctl experimental precheck旧版本中的预检命令名
istioctl analyze 报 IST0101引用的资源不存在,多为 Gateway 或 Service 名字写错
istioctl analyze 报 IST0102命名空间未开启注入或缺少 istio-injection 标签
命令说明复制
istioctl proxy-config cluster <pod>查看 Envoy 集群列表,确认目标服务是否被识别
istioctl proxy-config listener <pod>查看监听器,确认端口是否被劫持
istioctl proxy-config route <pod>查看路由表,核对 VirtualService 是否生效
istioctl proxy-config endpoint <pod>查看端点列表,为空说明没有可用后端
istioctl proxy-config bootstrap <pod>查看 Envoy 启动配置(含控制面地址)
istioctl proxy-config secret <pod>查看证书与密钥状态,排查 mTLS 问题
istioctl proxy-config ecds <pod>查看 ECDS 配置,网关场景常用
istioctl pc all <pod> -o json > proxy.json导出全量配置,便于离线分析
istioctl pc route <pod> -o json | jq用 jq 精确提取路由字段
istioctl pc cluster <pod> --fqdn svc.ns.svc.cluster.local按服务名过滤集群
istioctl pc endpoint <pod> --cluster "outbound|80||svc.ns.svc.cluster.local"按集群名查端点,定位 503 的有效手段
istioctl pc listener <pod> --port 8080只看指定端口的监听器
istioctl pc cluster <pod> | grep -i "outbound|inbound"快速区分出入向集群
命令说明复制
istioctl proxy-config log <pod> --level debug临时调高 Envoy 日志级别,复现问题必备
istioctl proxy-config log <pod> --level warning排查完恢复默认级别,避免日志暴涨
istioctl proxy-config log <pod>查看当前各模块日志级别
kubectl exec <pod> -c istio-proxy -- pilot-agent request GET /stats获取 Envoy 统计指标
kubectl exec <pod> -c istio-proxy -- pilot-agent request GET /config_dump导出完整配置,与 istioctl 结果交叉验证
kubectl exec <pod> -c istio-proxy -- pilot-agent request POST /logging?level=debug通过 pilot-agent 动态调整日志级别
kubectl exec <pod> -c istio-proxy -- pilot-agent request GET /clusters查看集群与健康状态
kubectl exec <pod> -c istio-proxy -- pilot-agent request GET /listeners查看监听器详情
kubectl exec <pod> -c istio-proxy -- pilot-agent request GET /server_info查看 Envoy 版本与启动参数
kubectl logs <pod> -c istio-proxy --tail=200查看 sidecar 日志,访问日志与错误都在这里
istioctl dashboard envoy <pod>打开 Envoy 管理界面查看配置与统计
istioctl dashboard controlz <istiod-pod>打开控制面调试界面,查看推送与内部状态
命令说明复制
istioctl x describe pod <pod>查看 Pod 生效的路由、目标规则与 mTLS 状态
istioctl experimental describe pod <pod>旧版本的描述命令
istioctl x describe svc <svc>查看服务维度的策略与端点
kubectl get virtualservice,destinationrule,gateway,serviceentry -A确认自定义资源是否真正创建
istioctl pc route <pod> --name 80查看某端口的完整路由配置
istioctl pc listener <pod> -o json | jq ".dynamic_listeners[].name"列出全部监听器名称,确认端口是否被接管
istioctl analyze -n app 报 virtualservice 冲突同类主机重复定义会导致规则互相覆盖
istioctl proxy-status 显示 STALE配置未推送成功:检查 istiod 日志与连接状态
istioctl x authz check <pod>检查 AuthorizationPolicy 是否按预期放行
istioctl experimental metrics <pod>查看该代理的关键指标摘要
istioctl proxy-config endpoint <pod> | grep -v HEALTHY筛出异常端点
istioctl x wait <resource>等待资源状态就绪,脚本化发布时有用
命令说明复制
istioctl kube-inject -f deploy.yaml | kubectl apply -f -手工注入 sidecar 后应用
istioctl kube-inject -f deploy.yaml -o injected.yaml只生成注入后的 YAML,便于审查
kubectl label namespace app istio-injection=enabled开启命名空间自动注入
kubectl label namespace app istio.io/rev=1-20-1修订版本模式下按标签注入
sidecar.istio.io/inject: "true"单 Pod 级别强制注入注解
sidecar.istio.io/inject: "false"排除个别 Pod,避免影响特殊工作负载
kubectl get pod <pod> -o jsonpath="{.spec.containers[*].name}"确认 istio-proxy 容器是否存在
istioctl proxy-config bootstrap <pod> | grep -i "discovery"确认代理连接的是哪个 istiod
istioctl tag set default --revision 1-20-1 --overwrite切换默认注入版本
kubectl rollout restart deploy -n app注入配置变更后重建 Pod 生效
istioctl x revision list查看可用的控制面修订版本
istioctl analyze 后确认 pod 同时存在 app 与 istio-proxy 容器注入失败多为 webhook 或标签问题
命令说明复制
istioctl x precheck升级前检查集群版本、CRD 与配置兼容性
istioctl install --set revision=canary -y先装新版本控制面,与旧版本并存
istioctl tag set prod --revision canary把业务命名空间切到新修订
kubectl rollout restart deploy -n app重建工作负载以接入新控制面
istioctl proxy-status确认全部 Envoy 已同步到新版本
istioctl version --remote对比控制面与数据面版本是否一致
istioctl upgrade -y原地升级(会短暂影响控制面,生产建议用修订方式)
istioctl tag set prod --revision 1-19-3回滚:把标签指回旧修订
istioctl x uninstall --revision canary升级完成后卸载旧修订
istioctl manifest generate -f old.yaml > old.yaml.bak升级前保留清单,作为回滚依据
升级后 istioctl analyze -A 复查确认没有新增配置告警
升级前备份:Gateway、VirtualService、PeerAuthentication 等 CRCRD 变更可能导致旧配置不兼容
命令说明复制
istioctl create-remote-secret --name=cluster2 > cluster2-secret.yaml生成远端集群凭据用于多集群互联
istioctl x remote-clusters查看已发现的多集群成员
istioctl x workload entry configure -f workload.yaml -o outdir为虚拟机或裸机工作负载生成接入配置
istioctl x workload group create -f group.yaml创建 WorkloadGroup,统一管理外部工作负载
istioctl experimental add-to-mesh <deployment>把已有工作负载接入网格
istioctl --context cluster2 proxy-status切到另一个集群查看代理状态
多集群安装需开启 values.global.multiCluster网络不互通时使用 east-west gateway
istioctl proxy-config endpoint <pod> | grep <remote-cluster>确认跨集群端点是否被发现
istioctl analyze -A 在多集群环境需分别执行每个集群独立分析配置一致性
istioctl dashboard kiali通过 Kiali 查看多集群拓扑与流量
命令说明复制
503 UF(upstream connect error)上游连接失败:多为目标服务无端点、端口错或 mTLS 不匹配
503 NR(no route found)路由未命中:核对 VirtualService 的 host 与端口是否匹配
istioctl pc endpoint <pod> 结果为空服务无就绪端点:检查 Pod 就绪探针与 Service selector
istioctl x describe pod <pod> 看 mTLS 状态STRICT 与 PERMISSIVE 不一致会导致双向 TLS 握手失败
istioctl pc secret <pod>证书缺失或过期时在这里直接暴露
istioctl proxy-config log <pod> --level debug 后复现定位具体 Envoy 拒绝原因
kubectl logs <pod> -c istio-proxy | grep -i "error\|warn"提取代理层告警
istioctl proxy-status 长时间 NOT SENT代理与控制面连接异常,检查 istiod 与网络策略
istiod 日志中的 push error配置推送失败通常是资源冲突或 webhook 异常
sidecar 启动失败:pilot-agent 无法连接 istiod检查 istiod Service、DNS 与证书挂载
istioctl analyze 报 IST0132 等证书告警按提示更新 Gateway 证书 Secret
访问不通但 kubectl exec 到容器内 curl 正常问题在流量劫持:先看监听器与 iptables 规则
命令说明复制
istioctl analyze -A && istioctl proxy-status每日巡检两条命令,覆盖配置与同步
istioctl version --remote定期核对控制面与数据面版本是否漂移
istioctl manifest generate > istio.yaml 纳入 Git 管理安装参数可追溯、可回滚
变更流程:改 CR → analyze → 观察 proxy-status → 验证业务避免直接上线未校验的路由规则
istioctl x describe pod 作为排查起点一次看清注入、路由与 mTLS 状态
istioctl dashboard kiali / grafana / jaeger可视化拓扑与链路追踪,快速定位异常服务
sidecar 资源限制与 request 要单独评估代理占用的 CPU 内存常被忽略,影响容量规划
生产禁用 demo profiledemo 包含大量示例组件,不适合承载业务
保留 istioctl 版本与集群版本一致版本偏差过大会导致命令与 API 不兼容
大范围变更前先 dry-run 生成清单比对istioctl manifest generate 是安全的预演方式

运维常用组合

日常巡检istioctl analyze -A → istioctl proxy-status → istioctl version --remote
单服务不通排查istioctl x describe pod <pod> → istioctl pc endpoint <pod> → istioctl pc route <pod>
抓 Envoy 细节istioctl pc log <pod> --level debug → 复现 → kubectl logs <pod> -c istio-proxy
金丝雀升级install --set revision=canary → tag set prod --revision canary → rollout restart → proxy-status
清单化安装istioctl manifest generate -f cfg.yaml > istio.yaml → 纳入 Git 后 kubectl apply
可视化排障istioctl dashboard kiali → istioctl dashboard grafana → istioctl dashboard jaeger

常见问题排查

1. analyze 报 IST0102

命名空间未开注入:加 istio-injection=enabled 或 istio.io/rev 标签后重建 Pod

2. 出现 503 UF

先 istioctl pc endpoint <pod> 看是否有就绪端点,再核对端口与 mTLS 模式是否一致

3. 出现 503 NR

路由没命中:检查 VirtualService 的 hosts、gateways 与端口号是否与访问方式匹配

4. proxy-status 显示 STALE

配置未推送:看 istiod 日志与推送错误,排查资源冲突或 webhook 异常

5. 升级后部分 Pod 不生效

修订模式下需重建 Pod 才能换边车,确认命名空间标签指向新 revision

6. 怀疑 mTLS 问题

用 istioctl x describe pod 看实际生效模式,PeerAuthentication 的 STRICT 与 PERMISSIVE 冲突最常见

共 118 条 istioctl 命令 · 示例 Pod 名为占位符,请替换为实际工作负载

关于istioctl命令速查

在线 istioctl 命令速查手册,按安装版本与 Profile、配置分析与巡检、Proxy-Config 深入排查、运行时调试与日志级别、流量策略与生效验证、注入与 Sidecar 管理、升级修订与回滚、多集群与 Workload 配置、常见故障定位、常用巡检与最佳实践等 10 类场景整理 120+ 条常用命令,每条附中文说明与可直接复制的写法,支持关键词搜索、分类折叠和一键复制,打开网页即可查阅。涵盖 istioctl version --remote、install --set profile 与 -f IstioOperator、profile list/dump/diff、manifest generate、revision 与 tag set、x uninstall --purge、analyze -A 与 -n 与 -f 与 --use-kube=false 与 --suppress、IST0101 与 IST0102 告警、proxy-status 的 SYNCED/STALE/NOT SENT、proxy-config 的 cluster/listener/route/endpoint/bootstrap/secret/ecds 与 pc all 导出、--fqdn 与 --cluster 与 --port 过滤、proxy-config log --level debug 与 warning、pilot-agent request GET /stats 与 /config_dump 与 /logging 与 /clusters 与 /server_info、istioctl dashboard envoy 与 controlz 与 kiali 与 grafana 与 jaeger、x describe pod 与 svc、x authz check、kube-inject 与 istio-injection 与 istio.io/rev 标签、sidecar.istio.io/inject 注解、rollout restart、x precheck 与 upgrade 与修订金丝雀升级与回滚、create-remote-secret 与 x workload entry configure、503 UF 与 503 NR 与 mTLS 冲突与证书过期与 push error 等定位思路。适用于 Istio 服务网格部署运维、流量治理与灰度、Sidecar 注入排查、配置推送异常与 503 故障定位、版本升级与多集群管理,以及运维与 DevOps 面试复习。

核心能力

  • 涵盖 istioctl version --remote、install --set profile 与 -f IstioOperator、profile list/dump/diff、manifest generate、revision 与 tag set、x uninstall --purge、analyze -A 与 -n 与 -f 与 --use-kube=false 与 --suppress、IST0101 与 IST0102 告警、proxy-status 的 SYNCED/STALE/NOT SENT、proxy-config 的 cluster/listener/route/endpoint/bootstrap/secret/ecds 与 pc all 导出、--fqdn 与 --cluster 与 --port 过滤、proxy-config log --level debug 与 warning、pilot-agent request GET /stats 与 /config_dump 与 /logging 与 /clusters 与 /server_info、istioctl dashboard envoy 与 controlz 与 kiali 与 grafana 与 jaeger、x describe pod 与 svc、x authz check、kube-inject 与 istio-injection 与 istio.io/rev 标签、sidecar.istio.io/inject 注解、rollout restart、x precheck 与 upgrade 与修订金丝雀升级与回滚、create-remote-secret 与 x workload entry configure、503 UF 与 503 NR 与 mTLS 冲突与证书过期与 push error 等定位思路

适用场景

适用于 Istio 服务网格部署运维、流量治理与灰度、Sidecar 注入排查、配置推送异常与 503 故障定位、版本升级与多集群管理,以及运维与 DevOps 面试复习。istioctl命令速查全程在浏览器中完成,无需安装插件,可放心用于日常办公与排障。

常见问题

istioctl命令速查是免费的吗?需要注册或安装吗?
istioctl命令速查完全免费,无需注册、无需下载安装任何软件,用浏览器打开网页即可直接使用,也不限制使用次数。
istioctl命令速查支持哪些功能?
涵盖 istioctl version --remote、install --set profile 与 -f IstioOperator、profile list/dump/diff、manifest generate、revision 与 tag set、x uninstall --purge、analyze -A 与 -n 与 -f 与 --use-kube=false 与 --suppress、IST0101 与 IST0102 告警、proxy-status 的 SYNCED/STALE/NOT SENT、proxy-config 的 cluster/listener/route/endpoint/bootstrap/secret/ecds 与 pc all 导出、--fqdn 与 --cluster 与 --port 过滤、proxy-config log --level debug 与 warning、pilot-agent request GET /stats 与 /config_dump 与 /logging 与 /clusters 与 /server_info、istioctl dashboard envoy 与 controlz 与 kiali 与 grafana 与 jaeger、x describe pod 与 svc、x authz check、kube-inject 与 istio-injection 与 istio.io/rev 标签、sidecar.istio.io/inject 注解、rollout restart、x precheck 与 upgrade 与修订金丝雀升级与回滚、create-remote-secret 与 x workload entry configure、503 UF 与 503 NR 与 mTLS 冲突与证书过期与 push error 等定位思路。
istioctl命令速查适合哪些场景使用?
适用于 Istio 服务网格部署运维、流量治理与灰度、Sidecar 注入排查、配置推送异常与 503 故障定位、版本升级与多集群管理,以及运维与 DevOps 面试复习。