企业官网建设流程全解析

Istio Ambient 模式如何用 istioctl waypoint apply 创建 Waypoint 并验证就绪

【免费下载链接】istioConnect, secure, control, and observe services.项目地址: https://gitcode.com/GitHub_Trending/is/istio

在已经启用 Ambient 模式的 Istio 集群中，为某个命名空间引入 Waypoint 代理是管理流量（授权策略、遥测、L7 路由等）的第一步。本文基于 istio 仓库中的命令实现与集成测试，给出用istioctl waypoint apply创建 Waypoint 并确认其就绪（Programmed）的完整操作路径。命令实现见 istioctl/pkg/waypoint/waypoint.go，可参照的完整操作序列在集成测试 tests/integration/ambient/waypoint_test.go 中。

准备条件

• 集群已以 Ambient 方式安装 Istio（包含 Istiod、CNI 和 ztunnel chart）。仓库的 ambient profile manifests/helm-profiles/ambient.yaml 展示了该模式的关键配置：pilot.env.PILOT_ENABLE_AMBIENT: "true"、cni.ambient.enabled: true，并通过ISTIO_META_ENABLE_HBONE: "true"开启 HBONE 隧道。
• 集群支持 Kubernetes Gateway API：集成测试在创建 Waypoint 前会检查该条件，不满足时跳过，提示requires gateway API (k8s 1.31+)（见 tests/integration/ambient/main_test.go 中的skipIfGatewayAPIUnsupported）。
• istioctl与kubectl的 kubeconfig 均指向目标集群。

创建 Waypoint

1. 先将命名空间标记为 ambient

istioctl waypoint apply在会登记命名空间时检查该标签，缺失时会打印警告并直接给出补救命令。按警告提示手动执行即可：

kubectl label namespace default istio.io/dataplane-mode=ambient

default替换为你要创建 Waypoint 的命名空间。若你是按 workload 粒度处理 ambient 转发而不打算在命名空间级别开启，可以跳过此步，apply 时收到警告但不报错。

2. 应用并等待就绪

最小主路径（以 default 命名空间为例，Waypoint 名称使用默认值istio-waypoint）：

istioctl waypoint apply --namespace default --wait

成功时命令输出两行（仓库源码中的实际格式）：

✅ waypoint default/istio-waypoint applied ✅ waypoint default/istio-waypoint is ready!

--wait（可简写-w）会让命令轮询 Gateway 的Programmedcondition，直到其为True才返回“ready”；等待超时由--waypoint-timeout控制，默认 90 秒。不想等待时直接执行istioctl waypoint apply，它只负责将配置以 server-side apply（field manageristioctl）的方式写入集群。

在应用前，可以先用 generate 子命令预览将要创建的 Gateway 资源，便于确认名称、namespace 与 listener：

istioctl waypoint generate --namespace default

3. 常用可选参数

以下参数来自 istioctl/pkg/waypoint/waypoint.go 的 flag 定义：

• --name：指定 Waypoint 名称，默认istio-waypoint；none是保留值，不能用作名称。
• --for：指定 Waypoint 的流量类型。集成测试 tests/integration/ambient/main_test.go 中创建 service 类型 Waypoint 的注释即为--for service，用于让 service 粒度（server-first 协议）的流量正确处理；其余合法取值以 flag 帮助输出的列表为准。
• --revision（-r）：将 Waypoint 打标到指定 Istio 修订版本，用于多版本共存场景。
• --enroll-namespace：创建 Waypoint 后自动给命名空间打上istio.io/use-waypoint: <name>标签，让该命名空间默认使用这个 Waypoint。如果命名空间已有登记的 Waypoint，命令会提示考虑加--overwrite而不是直接失败；--overwrite表示覆盖该命名空间现有使用的 Waypoint。
• --waypoint-timeout：调整--wait/waypoint status的超时，这一能力在 releasenotes/notes/56454.yaml 中有对应发布说明。

验证就绪

创建完成后有两种核对方式。

istioctl waypoint list列出命名空间内所有istio-waypointGatewayClass 的 Gateway，并显示PROGRAMMED列；跨命名空间加-A：

istioctl waypoint list --namespace default istioctl waypoint list -A

PROGRAMMED列的取值来自 Gateway 的Programmedcondition：显示True即代表该 Waypoint 已被 Istiod 编程、处于可用状态。

istioctl waypoint status输出更详细的 condition 信息（STATUS、TYPE、REASON、MESSAGE列），默认也带等待逻辑（--wait默认为 true），可用--all-namespaces查看全部命名空间：

istioctl waypoint status --namespace default

若 Waypoint 长时间未就绪，结合 status 输出的 REASON/MESSAGE 判断具体原因。

排错与限制

• 命名空间未标记 ambient：apply 输出警告⚠️ Warning: namespace is not enrolled in ambient. Consider running 'kubectl label namespace <ns> istio.io/dataplane-mode=ambient'。按提示补上标签即可。
• 缺少 Gateway CRD：apply 会失败并提示missing Kubernetes Gateway CRDs need to be installed before applying a waypoint，说明集群尚未安装 Kubernetes Gateway API 的 CRD，需要先补齐 CRD 再重试。
• 等待超时：超时后报错timed out while waiting for waypoint（含 Waypoint 的 namespace/name），可用--waypoint-timeout放宽超时，并用istioctl waypoint status查看具体 condition 消息。
• 清理：删除单个 Waypoint 用istioctl waypoint delete waypoint-name --namespace default；--all删除该命名空间全部 Waypoint；--revision <rev>删除指定修订的 Waypoint。集成测试中正是按名称逐个删除后确认 Pod 不再就绪来验证清理结果。

参考路径

• 命令实现与输出文案：istioctl/pkg/waypoint/waypoint.go
• 创建/等待/列表/删除的完整调用序列：tests/integration/ambient/waypoint_test.go
• ambient 安装 profile：manifests/helm-profiles/ambient.yaml

【免费下载链接】istioConnect, secure, control, and observe services.项目地址: https://gitcode.com/GitHub_Trending/is/istio