Kubernetes NodePort 报 provided port is not in the valid range

创建 NodePort Service 时指定 nodePort: 40000，API 返回：

spec.ports[0].nodePort: Invalid value: 40000:
provided port is not in the valid range.
The range of valid ports is 30000-32767

这是控制平面的端口分配校验失败。即使节点防火墙已经放行 40000，或者 Pod 正在监听 40000，也不能让一个超出集群分配范围的 NodePort 被接受。

本文针对 Kubernetes v1 Service 的 NodePort 配置。默认分配范围为 30000-32767，但管理员可以调整，因此实际错误中给出的范围比默认值更能说明当前集群的条件。

三个端口字段承担不同作用

port 是 Service 提供的端口，targetPort 是后端 Pod 的目标端口，nodePort 是通过节点地址向外提供服务的端口。NodePort 分配范围约束的是第三个字段，不要求三个值相同。

例如应用在 Pod 内监听 40000，完全可以让 targetPort 保持 40000，同时由集群分配另一个合法的节点端口。不要为了让三项看起来一致，就修改应用监听或把范围错误当成应用故障。

如果原清单来自模板，核对渲染后的 spec.ports[].nodePort，以及 kubectl 当前连接的集群。测试集群接受过的端口，不表示生产集群使用相同范围。

不要求固定节点端口时，交给集群分配

下面是完整示例，后端 Pod 需要具有 app: demo-api 标签并监听 TCP 40000。清单中没有 nodePort，由控制平面在现有范围内分配：

apiVersion: v1
kind: Service
metadata:
  name: demo-api
spec:
  type: NodePort
  selector:
    app: demo-api
  ports:
    - name: api
      protocol: TCP
      port: 8080
      targetPort: 40000

保存为 service.yaml，在支持服务端 dry-run 的环境中先校验：

kubectl apply --dry-run=server -f service.yaml

确认上下文、命名空间与服务暴露需求后，再按正常部署流程应用。dry-run 不预留端口，正式创建时仍可能遇到并发分配或策略变化。

读取保存后的实际端口：

kubectl get service demo-api -o yaml

外部调用方使用节点地址与返回的 nodePort，不能继续按原来的 40000 请求。Service 保存成功后，还需要核对就绪后端、节点访问策略和实际外部请求；合法分配并不保证防火墙已经允许访问。

必须固定端口时，选现有范围内未占用的值

如果外部系统必须固定 NodePort，应先确认平台允许的范围和分配规则，再在清单中明确填写一个可用值。默认范围内的 30080 可以作为说明，但它并不是所有集群都保留给你的端口：

      nodePort: 30080

把这一行合入对应的 ports 项，保留其他字段。API 会校验范围和冲突；已有 Service 使用这个值时，不能通过重试或删除别人的 Service 抢占。

NodePort 可能扩大外部可达面。变更前记录原 Service 和外部负载均衡、防火墙、客户端配置，按照既有访问控制要求开通必要范围，不把所有高位端口一并放行。

两段范围不能靠重复参数叠加

控制平面的 --service-node-port-range 接受一段 N1-N2 范围，包含两端。它不是按应用分别累加的范围列表；不要写成逗号分隔的两段，也不要通过重复添加参数期待同时保留默认段和新段。

修改这个参数属于集群级变更，还必须避开节点临时端口范围，并评估现有 Service、所有 API Server 和托管平台的限制。它不适合作为修复单个清单错误的第一步。普通应用部署优先使用现有范围；确有固定外部端口约束时，由平台维护者确定入口映射或集群配置方案。

回退应同时恢复已验收的 Service 清单和外部引用。若刚创建的测试 Service 已有客户端使用，不要直接删除它；删除重建可能改变地址或分配端口。此前若已修改控制平面范围，恢复参数前也应核查新范围内已经创建的 Service，不能只改回一行配置便认定影响消除。