端点切片 [discovery.k8s.io/v1] - 网络 API | API 参考 | OpenShift Container Platform 4.17

规范
API端点

描述

EndpointSlice 代表实现服务的端点的一个子集。对于给定的服务，可能存在多个 EndpointSlice 对象，通过标签选择，这些对象必须组合起来才能产生完整的端点集。

类型

对象

必需

addressType
endpoints

规范

属性类型描述

属性	类型	描述
`addressType`	`字符串`	addressType 指定此 EndpointSlice 承载的地址类型。此切片中的所有地址必须具有相同的类型。此字段在创建后不可变。目前支持以下地址类型：* IPv4：表示 IPv4 地址。* IPv6：表示 IPv6 地址。* FQDN：表示完全限定域名。可能的枚举值：- `"FQDN"` 代表 FQDN。- `"IPv4"` 代表 IPv4 地址。- `"IPv6"` 代表 IPv6 地址。
`apiVersion`	`字符串`	APIVersion 定义此对象表示的版本化模式。服务器应将识别的模式转换为最新的内部值，并可能拒绝无法识别的值。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
`endpoints`	`数组`	endpoints 是此切片中唯一端点的列表。每个切片最多可包含 1000 个端点。
`endpoints[]`	`对象`	Endpoint 代表实现服务的单个逻辑“后端”。
`kind`	`字符串`	Kind 是一个字符串值，表示此对象表示的 REST 资源。服务器可以从客户端提交请求的端点推断出这一点。无法更新。使用驼峰命名法。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
`metadata`	`ObjectMeta`	标准对象的元数据。
`ports`	`数组`	ports 指定此切片中每个端点公开的网络端口列表。每个端口必须具有唯一名称。当 ports 为空时，表示没有定义端口。当端口定义了 nil 端口值时，表示“所有端口”。每个切片最多可包含 100 个端口。
`ports[]`	`对象`	EndpointPort 代表 EndpointSlice 使用的端口

addressType

字符串

addressType 指定此 EndpointSlice 承载的地址类型。此切片中的所有地址必须具有相同的类型。此字段在创建后不可变。目前支持以下地址类型：* IPv4：表示 IPv4 地址。* IPv6：表示 IPv6 地址。* FQDN：表示完全限定域名。

可能的枚举值：- "FQDN" 代表 FQDN。- "IPv4" 代表 IPv4 地址。- "IPv6" 代表 IPv6 地址。

apiVersion

字符串

APIVersion 定义此对象表示的版本化模式。服务器应将识别的模式转换为最新的内部值，并可能拒绝无法识别的值。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

endpoints

数组

endpoints 是此切片中唯一端点的列表。每个切片最多可包含 1000 个端点。

endpoints[]

对象

Endpoint 代表实现服务的单个逻辑“后端”。

kind

字符串

Kind 是一个字符串值，表示此对象表示的 REST 资源。服务器可以从客户端提交请求的端点推断出这一点。无法更新。使用驼峰命名法。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

metadata

ObjectMeta

标准对象的元数据。

ports

数组

ports 指定此切片中每个端点公开的网络端口列表。每个端口必须具有唯一名称。当 ports 为空时，表示没有定义端口。当端口定义了 nil 端口值时，表示“所有端口”。每个切片最多可包含 100 个端口。

ports[]

对象

EndpointPort 代表 EndpointSlice 使用的端口

.endpoints

描述: endpoints 是此切片中唯一端点的列表。每个切片最多可包含 1000 个端点。
类型: 数组

.endpoints[]

描述

Endpoint 代表实现服务的单个逻辑“后端”。

类型

对象

必需

addresses

属性类型描述

属性	类型	描述
`addresses`	`数组 (字符串)`	此端点的地址。此字段的内容根据相应的 EndpointSlice addressType 字段进行解释。使用者必须在其自身功能的上下文中处理不同类型的地址。这必须包含至少一个地址，但最多不超过 100 个。这些都被假定为可互换的，客户端可以选择只使用第一个元素。参考：https://issue.k8s.io/106267
`conditions`	`对象`	EndpointConditions 表示端点的当前状态。
`deprecatedTopology`	`对象 (字符串)`	deprecatedTopology 包含 v1beta1 API 部分的拓扑信息。此字段已弃用，将在删除 v1beta1 API 时删除（不早于 kubernetes v1.24）。虽然此字段可以保存值，但不能通过 v1 API 写入，任何尝试写入它的操作都将被静默忽略。拓扑信息可以在 zone 和 nodeName 字段中找到。
`hints`	`对象`	EndpointHints 提供描述如何使用端点的提示。
`hostname`	`字符串`	此端点的主机名。使用者可以使用此字段来区分端点（例如在 DNS 名称中）。使用相同主机名的多个端点应被视为可互换的（例如，DNS 中的多个 A 值）。必须是小写字母，并通过 DNS 标签 (RFC 1123) 验证。
`nodeName`	`字符串`	nodeName 表示托管此端点的节点的名称。这可以用来确定本地于节点的端点。
`targetRef`	`ObjectReference`	targetRef 是对表示此端点的 Kubernetes 对象的引用。
`zone`	`字符串`	zone 是此端点所在的区域的名称。

addresses

数组 (字符串)

此端点的地址。此字段的内容根据相应的 EndpointSlice addressType 字段进行解释。使用者必须在其自身功能的上下文中处理不同类型的地址。这必须包含至少一个地址，但最多不超过 100 个。这些都被假定为可互换的，客户端可以选择只使用第一个元素。参考：https://issue.k8s.io/106267

conditions

对象

EndpointConditions 表示端点的当前状态。

deprecatedTopology

对象 (字符串)

deprecatedTopology 包含 v1beta1 API 部分的拓扑信息。此字段已弃用，将在删除 v1beta1 API 时删除（不早于 kubernetes v1.24）。虽然此字段可以保存值，但不能通过 v1 API 写入，任何尝试写入它的操作都将被静默忽略。拓扑信息可以在 zone 和 nodeName 字段中找到。

hints

对象

EndpointHints 提供描述如何使用端点的提示。

hostname

字符串

此端点的主机名。使用者可以使用此字段来区分端点（例如在 DNS 名称中）。使用相同主机名的多个端点应被视为可互换的（例如，DNS 中的多个 A 值）。必须是小写字母，并通过 DNS 标签 (RFC 1123) 验证。

nodeName

字符串

nodeName 表示托管此端点的节点的名称。这可以用来确定本地于节点的端点。

targetRef

ObjectReference

targetRef 是对表示此端点的 Kubernetes 对象的引用。

zone

字符串

zone 是此端点所在的区域的名称。

.endpoints[].conditions

描述: EndpointConditions 表示端点的当前状态。
类型: 对象

属性类型描述

属性	类型	描述
`ready`	`布尔值`	ready 表示此端点已准备好接收流量，具体取决于管理端点的系统。nil 值表示未知状态。在大多数情况下，使用者应将此未知状态解释为已准备就绪。出于兼容性原因，对于终止的端点，ready 绝不应为“true”，除非显式覆盖正常的就绪行为，例如当关联的服务已设置 publishNotReadyAddresses 标志时。
`serving`	`布尔值`	serving 与 ready 相同，不同之处在于它无论端点的终止状态如何都会设置。对于正在终止的已准备就绪的端点，此状态应设置为 true。如果为 nil，使用者应参考 ready 状态。
`terminating`	`布尔值`	terminating 表示此端点正在终止。nil 值表示未知状态。使用者应将此未知状态解释为端点未终止。

ready

布尔值

ready 表示此端点已准备好接收流量，具体取决于管理端点的系统。nil 值表示未知状态。在大多数情况下，使用者应将此未知状态解释为已准备就绪。出于兼容性原因，对于终止的端点，ready 绝不应为“true”，除非显式覆盖正常的就绪行为，例如当关联的服务已设置 publishNotReadyAddresses 标志时。

serving

布尔值

serving 与 ready 相同，不同之处在于它无论端点的终止状态如何都会设置。对于正在终止的已准备就绪的端点，此状态应设置为 true。如果为 nil，使用者应参考 ready 状态。

terminating

布尔值

terminating 表示此端点正在终止。nil 值表示未知状态。使用者应将此未知状态解释为端点未终止。

.endpoints[].hints

描述: EndpointHints 提供描述如何使用端点的提示。
类型: 对象

属性类型描述

属性	类型	描述
`forZones`	`数组`	forZones 指示此端点应由哪个区域使用以启用拓扑感知路由。
`forZones[]`	`对象`	ForZone 提供有关哪些区域应使用此端点的信息。

forZones

数组

forZones 指示此端点应由哪个区域使用以启用拓扑感知路由。

forZones[]

对象

ForZone 提供有关哪些区域应使用此端点的信息。

.endpoints[].hints.forZones

描述: forZones 指示此端点应由哪个区域使用以启用拓扑感知路由。
类型: 数组

.endpoints[].hints.forZones[]

描述

ForZone 提供有关哪些区域应使用此端点的信息。

类型

对象

必需

name

属性类型描述

属性	类型	描述
`name`	`字符串`	name 表示区域的名称。

name

字符串

name 表示区域的名称。

.ports

描述: ports 指定此切片中每个端点公开的网络端口列表。每个端口必须具有唯一名称。当 ports 为空时，表示没有定义端口。当端口定义了 nil 端口值时，表示“所有端口”。每个切片最多可包含 100 个端口。
类型: 数组

.ports[]

描述: EndpointPort 代表 EndpointSlice 使用的端口
类型: 对象

属性类型描述

属性	类型	描述
`appProtocol`	`字符串`	此端口的应用程序协议。这用作实现的提示，以便为其理解的协议提供更丰富的行为。此字段遵循标准 Kubernetes 标签语法。有效值为： * 未加前缀的协议名称 - 保留用于 IANA 标准服务名称（根据 RFC-6335 和 https://www.iana.org/assignments/service-names）。 * Kubernetes 定义的前缀名称：* 'kubernetes.io/h2c' - 如 https://www.rfc-editor.org/rfc/rfc9113.html#name-starting-http-2-with-prior- 中所述的明文优先的 HTTP/2。* 'kubernetes.io/ws' - 如 https://www.rfc-editor.org/rfc/rfc6455 中所述的明文 WebSocket。* 'kubernetes.io/wss' - 如 https://www.rfc-editor.org/rfc/rfc6455 中所述的 TLS 上的 WebSocket。 * 其他协议应使用实现定义的前缀名称，例如 mycompany.com/my-custom-protocol。
`name`	`字符串`	name 表示此端口的名称。EndpointSlice 中的所有端口必须具有唯一的名称。如果 EndpointSlice 来自 Kubernetes 服务，则这对应于 Service.ports[].name。名称必须为空字符串或通过 DNS_LABEL 验证：* 长度不得超过 63 个字符。* 必须由小写字母数字字符或 '-' 组成。* 必须以字母数字字符开头和结尾。默认为空字符串。
`port`	`整数`	port 表示端点的端口号。如果未指定此项，则端口不受限制，必须在特定使用者的上下文中进行解释。
`protocol`	`字符串`	protocol 表示此端口的 IP 协议。必须是 UDP、TCP 或 SCTP。默认为 TCP。可能的枚举值：- `"SCTP"` 表示 SCTP 协议。- `"TCP"` 表示 TCP 协议。- `"UDP"` 表示 UDP 协议。

appProtocol

字符串

此端口的应用程序协议。这用作实现的提示，以便为其理解的协议提供更丰富的行为。此字段遵循标准 Kubernetes 标签语法。有效值为：

* 未加前缀的协议名称 - 保留用于 IANA 标准服务名称（根据 RFC-6335 和 https://www.iana.org/assignments/service-names）。

* Kubernetes 定义的前缀名称：* 'kubernetes.io/h2c' - 如 https://www.rfc-editor.org/rfc/rfc9113.html#name-starting-http-2-with-prior- 中所述的明文优先的 HTTP/2。* 'kubernetes.io/ws' - 如 https://www.rfc-editor.org/rfc/rfc6455 中所述的明文 WebSocket。* 'kubernetes.io/wss' - 如 https://www.rfc-editor.org/rfc/rfc6455 中所述的 TLS 上的 WebSocket。

* 其他协议应使用实现定义的前缀名称，例如 mycompany.com/my-custom-protocol。

name

字符串

name 表示此端口的名称。EndpointSlice 中的所有端口必须具有唯一的名称。如果 EndpointSlice 来自 Kubernetes 服务，则这对应于 Service.ports[].name。名称必须为空字符串或通过 DNS_LABEL 验证：* 长度不得超过 63 个字符。* 必须由小写字母数字字符或 '-' 组成。* 必须以字母数字字符开头和结尾。默认为空字符串。

port

整数

port 表示端点的端口号。如果未指定此项，则端口不受限制，必须在特定使用者的上下文中进行解释。

protocol

字符串

protocol 表示此端口的 IP 协议。必须是 UDP、TCP 或 SCTP。默认为 TCP。

可能的枚举值：- "SCTP" 表示 SCTP 协议。- "TCP" 表示 TCP 协议。- "UDP" 表示 UDP 协议。

API 端点

以下 API 端点可用

/apis/discovery.k8s.io/v1/endpointslices
- GET：列出或监听 EndpointSlice 对象
/apis/discovery.k8s.io/v1/watch/endpointslices
- GET：监听 EndpointSlice 列表的单个更改。已弃用：请改用列表操作中的“watch”参数。
/apis/discovery.k8s.io/v1/namespaces/{namespace}/endpointslices
- DELETE：删除 EndpointSlice 集合
- GET：列出或监听 EndpointSlice 对象
- POST：创建 EndpointSlice
/apis/discovery.k8s.io/v1/watch/namespaces/{namespace}/endpointslices
- GET：监听 EndpointSlice 列表的单个更改。已弃用：请改用列表操作中的“watch”参数。
/apis/discovery.k8s.io/v1/namespaces/{namespace}/endpointslices/{name}
- DELETE：删除 EndpointSlice
- GET：读取指定的 EndpointSlice
- PATCH：部分更新指定的 EndpointSlice
- PUT：替换指定的 EndpointSlice
/apis/discovery.k8s.io/v1/watch/namespaces/{namespace}/endpointslices/{name}
- GET：监听 EndpointSlice 对象的更改。已弃用：请改用列表操作中的“watch”参数，并使用“fieldSelector”参数过滤为单个项目。

/apis/discovery.k8s.io/v1/endpointslices

HTTP 方法: GET
描述: 列出或监听 EndpointSlice 对象

表 1. HTTP 响应
HTTP 代码	响应体
200 - OK	`EndpointSliceList` 模式
401 - 未授权	空

/apis/discovery.k8s.io/v1/watch/endpointslices

HTTP 方法: GET
描述: 监听 EndpointSlice 列表的单个更改。已弃用：请改用列表操作中的“watch”参数。

表 2. HTTP 响应
HTTP 代码	响应体
200 - OK	`WatchEvent` 模式
401 - 未授权	空

/apis/discovery.k8s.io/v1/namespaces/{namespace}/endpointslices

HTTP 方法: DELETE
描述: 删除 EndpointSlice 集合

表 3. 查询参数
参数	类型	描述
`dryRun`	`字符串`	如果存在，则表示不应持久化修改。无效或无法识别的 dryRun 指令将导致错误响应，并且不会进一步处理请求。有效值为：- All：将处理所有 dry run 阶段

表 4. HTTP 响应
HTTP 代码	响应体
200 - OK	`Status` 模式
401 - 未授权	空

HTTP 方法: GET
描述: 列出或监听 EndpointSlice 对象

表 5. HTTP 响应
HTTP 代码	响应体
200 - OK	`EndpointSliceList` 模式
401 - 未授权	空

HTTP 方法: POST
描述: 创建 EndpointSlice

表 6. 查询参数
参数	类型	描述
`dryRun`	`字符串`	如果存在，则表示不应持久化修改。无效或无法识别的 dryRun 指令将导致错误响应，并且不会进一步处理请求。有效值为：- All：将处理所有 dry run 阶段
`fieldValidation`	`字符串`	fieldValidation 指示服务器如何处理请求 (POST/PUT/PATCH) 中包含未知或重复字段的对象。有效值为：- Ignore：这将忽略从对象中静默删除的任何未知字段，并将忽略解码器遇到的最后一个重复字段以外的所有重复字段。这是 v1.23 之前的默认行为。- Warn：对于从对象中删除的每个未知字段和遇到的每个重复字段，这将通过标准警告响应标头发送警告。如果没有任何其他错误，请求仍将成功，并且只会保留任何重复字段中的最后一个。这是 v1.23+ 中的默认值 - Strict：如果任何未知字段将从对象中删除，或者如果存在任何重复字段，这将使请求失败并返回 BadRequest 错误。服务器返回的错误将包含遇到的所有未知和重复字段。

表 7. 请求体参数
参数	类型	描述
`body`	`EndpointSlice` 模式

表 8. HTTP 响应
HTTP 代码	响应体
200 - OK	`EndpointSlice` 模式
201 - 已创建	`EndpointSlice` 模式
202 - 已接受	`EndpointSlice` 模式
401 - 未授权	空

/apis/discovery.k8s.io/v1/watch/namespaces/{namespace}/endpointslices

HTTP 方法: GET
描述: 监听 EndpointSlice 列表的单个更改。已弃用：请改用列表操作中的“watch”参数。

表 9. HTTP 响应
HTTP 代码	响应体
200 - OK	`WatchEvent` 模式
401 - 未授权	空

/apis/discovery.k8s.io/v1/namespaces/{namespace}/endpointslices/{name}

表 10. 全局路径参数
参数	类型	描述
`name`	`字符串`	EndpointSlice 的名称

HTTP 方法: DELETE
描述: 删除 EndpointSlice

表 11. 查询参数
参数	类型	描述
`dryRun`	`字符串`	如果存在，则表示不应持久化修改。无效或无法识别的 dryRun 指令将导致错误响应，并且不会进一步处理请求。有效值为：- All：将处理所有 dry run 阶段

表 12. HTTP 响应
HTTP 代码	响应体
200 - OK	`Status` 模式
202 - 已接受	`Status` 模式
401 - 未授权	空

HTTP 方法: GET
描述: 读取指定的 EndpointSlice

表 13. HTTP 响应
HTTP 代码	响应体
200 - OK	`EndpointSlice` 模式
401 - 未授权	空

HTTP 方法: PATCH
描述: 部分更新指定的 EndpointSlice

表 14. 查询参数
参数	类型	描述
`dryRun`	`字符串`	如果存在，则表示不应持久化修改。无效或无法识别的 dryRun 指令将导致错误响应，并且不会进一步处理请求。有效值为：- All：将处理所有 dry run 阶段
`fieldValidation`	`字符串`	fieldValidation 指示服务器如何处理请求 (POST/PUT/PATCH) 中包含未知或重复字段的对象。有效值为：- Ignore：这将忽略从对象中静默删除的任何未知字段，并将忽略解码器遇到的最后一个重复字段以外的所有重复字段。这是 v1.23 之前的默认行为。- Warn：对于从对象中删除的每个未知字段和遇到的每个重复字段，这将通过标准警告响应标头发送警告。如果没有任何其他错误，请求仍将成功，并且只会保留任何重复字段中的最后一个。这是 v1.23+ 中的默认值 - Strict：如果任何未知字段将从对象中删除，或者如果存在任何重复字段，这将使请求失败并返回 BadRequest 错误。服务器返回的错误将包含遇到的所有未知和重复字段。

表 15. HTTP 响应
HTTP 代码	响应体
200 - OK	`EndpointSlice` 模式
201 - 已创建	`EndpointSlice` 模式
401 - 未授权	空

HTTP 方法: PUT
描述: 替换指定的 EndpointSlice

表 16. 查询参数
参数	类型	描述
`dryRun`	`字符串`	如果存在，则表示不应持久化修改。无效或无法识别的 dryRun 指令将导致错误响应，并且不会进一步处理请求。有效值为：- All：将处理所有 dry run 阶段
`fieldValidation`	`字符串`	fieldValidation 指示服务器如何处理请求 (POST/PUT/PATCH) 中包含未知或重复字段的对象。有效值为：- Ignore：这将忽略从对象中静默删除的任何未知字段，并将忽略解码器遇到的最后一个重复字段以外的所有重复字段。这是 v1.23 之前的默认行为。- Warn：对于从对象中删除的每个未知字段和遇到的每个重复字段，这将通过标准警告响应标头发送警告。如果没有任何其他错误，请求仍将成功，并且只会保留任何重复字段中的最后一个。这是 v1.23+ 中的默认值 - Strict：如果任何未知字段将从对象中删除，或者如果存在任何重复字段，这将使请求失败并返回 BadRequest 错误。服务器返回的错误将包含遇到的所有未知和重复字段。

表 17. 请求体参数
参数	类型	描述
`body`	`EndpointSlice` 模式

表 18. HTTP 响应
HTTP 代码	响应体
200 - OK	`EndpointSlice` 模式
201 - 已创建	`EndpointSlice` 模式
401 - 未授权	空

/apis/discovery.k8s.io/v1/watch/namespaces/{namespace}/endpointslices/{name}

表 19. 全局路径参数
参数	类型	描述
`name`	`字符串`	EndpointSlice 的名称

HTTP 方法: GET
描述: 监听 EndpointSlice 对象的更改。已弃用：请改用列表操作中的“watch”参数，并使用“fieldSelector”参数过滤为单个项目。

表 20. HTTP 响应
HTTP 代码	响应体
200 - OK	`WatchEvent` 模式
401 - 未授权	空