Ingress

apiVersion: networking.k8s.io/v1

import "k8s.io/api/networking/v1"

Ingress

Ingress 是允许入站连接到达后端定义的端点的规则集合。 Ingress 可以配置为向服务提供外部可访问的 URL、负载均衡流量、终止 SSL、提供基于名称的虚拟主机等。

---

• apiVersion: networking.k8s.io/v1

• kind: Ingress

• metadata (ObjectMeta)

  标准的对象元数据。更多信息： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

• spec (IngressSpec)

  spec 是 Ingress 的预期状态。更多信息： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

• status (IngressStatus)

  status 是 Ingress 的当前状态。更多信息： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

IngressSpec

IngressSpec 描述用户希望存在的 Ingress。

---

• defaultBackend (IngressBackend)

  defaultBackend 是负责处理与任何规则都不匹配的请求的后端。 如果未指定 rules，则必须指定 defaultBackend。 如果未设置 defaultBackend，则不符合任何 rules 的请求的处理将由 Ingress 控制器决定。

• ingressClassName (string)

  ingressClassName 是 IngressClass 集群资源的名称。关联的 Ingress 类定义了将实际实现 Ingress 资源的控制器。 这一字段将取代不再推荐使用的 kubernetes.io/ingress.class 注解。 为了向后兼容，当设置了该注解时，注解必须优先于此字段。如果字段和注解具有不同的值，控制器可能会发出警告。 此 API 的实现应忽略未指定类的 Ingress 资源。IngressClass 资源可被标记为 default，用来设置此字段的默认值。 有关更多信息，请参阅 IngressClass 文档。

• rules ([]IngressRule)

  Atomic: 将在合并期间被替换

  用于配置 Ingress 的主机规则列表。如果未指定或没有规则匹配，则所有流量都将发送到默认后端。

  IngressRule 表示将指定主机下的路径映射到相关后端服务的规则。 传入请求首先评估主机匹配，然后路由到与匹配的 IngressRuleValue 关联的后端。

  • rules.host (string)

    host 是 RFC 3986 定义的网络主机的完全限定域名。请注意以下与 RFC 3986 中定义的 URI 的 “host” 部分的偏差：

    1. 不允许 IP。当前 IngressRuleValue 只能应用于父 Ingress Spec 中的 IP。

    2. 由于不允许使用端口，因此不理会 “:” 分隔符。 当前 Ingress 的端口隐式为：

       • :80 用于 http
       • :443 用于 https

    这两种情况在未来都可能发生变化。入站请求在通过 IngressRuleValue 处理之前先进行 host 匹配。 如果主机未指定，Ingress 将根据指定的 IngressRuleValue 规则路由所有流量。

    host 可以是 “精确“ 的，设置为一个不含终止句点的网络主机域名（例如 “foo.bar.com” ）， 也可以是一个 “通配符”，设置为以单个通配符标签为前缀的域名（例如 “.foo.com”）。 通配符 “” 必须单独显示为第一个 DNS 标签，并且仅与单个标签匹配。 你不能单独使用通配符作为标签（例如，Host=“*”）。请求将按以下方式与主机字段匹配：

    1. 如果 host 是精确匹配的，则如果 http Host 标头等于 host 值，则请求与此规则匹配。
    2. 如果 host 是用通配符给出的，那么如果 HTTP Host 标头与通配符规则的后缀（删除第一个标签）相同， 则请求与此规则匹配。

  • rules.http (HTTPIngressRuleValue)

    HTTPIngressRuleValue 是指向后端的 http 选择算符列表。例如 http://<host>/<path>?<searchpart> -> 后端， 其中 url 的部分对应于 RFC 3986，此资源将用于匹配最后一个 “/” 之后和第一个 “?” 之前的所有内容或 “#”。

    • rules.http.paths ([]HTTPIngressPath)，必需

      Atomic: 将在合并期间被替换

      将请求映射到后端的路径集合。

      HTTPIngressPath 将路径与后端关联。与路径匹配的传入 URL 将转发到后端。

      • rules.http.paths.backend (IngressBackend)，必需

        backend 定义将流量转发到的引用服务端点。

      • rules.http.paths.pathType (string)，必需

        pathType 决定如何解释 path 匹配。pathType 可以是以下值之一：

        • Exact：与 URL 路径完全匹配。

        • Prefix：根据按 “/” 拆分的 URL 路径前缀进行匹配。

          匹配是按路径元素逐个元素完成。路径元素引用的是路径中由“/”分隔符拆分的标签列表。 如果每个 p 都是请求路径 p 的元素前缀，则请求与路径 p 匹配。 请注意，如果路径的最后一个元素是请求路径中的最后一个元素的子字符串，则匹配不成功 （例如 /foo/bar 匹配 /foo/bar/baz，但不匹配 /foo/barbaz）。

        • ImplementationSpecific：路径匹配的解释取决于 IngressClass。 实现可以将其视为单独的路径类型，也可以将其视为前缀或确切的路径类型。 实现需要支持所有路径类型。

      • rules.http.paths.path (string)

        path 要与传入请求的路径进行匹配。 目前，它可以包含 RFC 3986 定义的 URL 的常规 “路径” 部分所不允许的字符。 路径必须以 “/” 开头，并且在 pathType 值为 “Exact” 或 “Prefix” 时必须存在。

• tls ([]IngressTLS)

  Atomic: 将在合并期间被替换

  TLS 配置。目前，Ingress 仅支持一个 TLS 端口 443。 如果此列表的多个成员指定了不同的主机，如果实现 Ingress 的 Ingress 控制器支持 SNI， 则它们将根据通过 SNI TLS 扩展指定的主机名在同一端口上多路复用。

  IngressTLS 描述与 Ingress 相关的传输层安全性。

  • tls.hosts ([]string)

    Atomic: 将在合并期间被替换

    hosts 是 TLS 证书中包含的主机列表。 此列表中的值必须与 tlsSecret 中使用的名称匹配。 默认为实现此 Ingress 的负载均衡控制器的通配符主机设置（如果未指定）。

  • tls.secretName (string)

    secretName 是用于终止端口 443 上 TLS 通信的 Secret 的名称。 字段是可选的，以允许仅基于 SNI 主机名的 TLS 路由。 如果侦听器中的 SNI 主机与入口规则使用的 “Host” 标头字段冲突，则 SNI 主机用于终止，Host 标头的值用于路由。

IngressBackend

IngressBackend 描述给定服务和端口的所有端点。

---

• resource (TypedLocalObjectReference)

  resource 是对 Ingress 对象所在命名空间中另一个 Kubernetes 资源的引用。 如果指定了 resource，则不得指定 service.name 和 service.port。 此字段是一个与 service 互斥的设置。

• service (IngressServiceBackend)

  service 引用一个 Service 作为后端。此字段是一个与 resource 互斥的设置。

  IngressServiceBackend 引用一个 Kubernetes Service 作为后端。

  • service.name (string)，必需

  name 是引用的服务。服务必须与 Ingress 对象位于同一命名空间中。

  • service.port (ServiceBackendPort)

    所引用的服务的端口。IngressServiceBackend 需要端口名或端口号。

    ServiceBackendPort 是被引用的服务的端口。

    • service.port.name (string)

      name 是服务上的端口名称。此字段是一个与 number 互斥的设置。

    • service.port.number (int32)

      number 是服务上的数字形式端口号（例如 80）。此字段是一个与 name 互斥的设置。

IngressStatus

IngressStatus 描述 Ingress 的当前状态。

---

• loadBalancer (LoadBalancerStatus)

  loadBalancer 包含负载均衡器的当前状态。

  LoadBalancerStatus 表示负载均衡器的状态。

  • loadBalancer.ingress ([]LoadBalancerIngress)

    ingress 是一个包含负载均衡器入口点的列表。用于服务的流量应发送到这些入口点。

    LoadBalancerIngress 表示负载均衡器入口点的状态：用于服务的流量应发送到入口点。

    • loadBalancer.ingress.hostname (string)

      hostname 是为基于 DNS 的负载平衡器（通常为 AWS 负载平衡器）入口点所设置的主机名。

    • loadBalancer.ingress.ip (string)

      ip 是为基于 IP 的负载平衡器（通常为 GCE 或 OpenStack 负载平衡器）入口点设置的 IP。

    • loadBalancer.ingress.ports ([]PortStatus)

      Atomic: 将在合并期间被替换

      ports 是服务端口的记录列表。如果使用了此字段，服务中定义的每个端口中都应该有一个条目与之对应。

      • loadBalancer.ingress.ports.port (int32)，必需

        port 在此是所记录状态对应的服务端口的端口号。

      • loadBalancer.ingress.ports.protocol (string)，必需

        protocol 是服务端口的协议，其状态记录在此。支持的值为：“TCP”、“UDP”、“SCTP”。

      • loadBalancer.ingress.ports.error (string)

        error 用来记录服务端口的问题。错误的格式应符合以下规则：

        • 应在此文件中指定内置错误码，并且错误码应使用驼峰法命名。
        • 特定于云驱动的错误码名称必须符合 foo.example.com/CamelCase 格式。

IngressList

IngressList 是 Ingress 的集合。

---

• items ([]Ingress)，必需

  items 是 Ingress 的列表。

• apiVersion (string)

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

• kind (string)

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

• metadata (ListMeta)

  标准的对象元数据。更多信息： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

操作

---

get 读取指定的 Ingress

HTTP 请求

GET /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses/{name}

参数

• name (路径参数)：string，必需

  Ingress 的名称。

• namespace (路径参数)：string，必需

  namespace

• pretty (查询参数): string

  pretty

响应

200 (Ingress): OK

401: Unauthorized

get 读取指定 Ingress 状态

HTTP 请求

GET /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses/{name}/status

参数

• name (路径参数)：string，必需

  Ingress 的名称。

• namespace (路径参数)：string，必需

  namespace

• pretty (查询参数): string

  pretty

响应

200 (Ingress): OK

401: Unauthorized

list 列出或监测 Ingress 类型对象

HTTP 请求

GET /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses

参数

• namespace (路径参数)：string，必需

  namespace

• allowWatchBookmarks (查询参数): boolean

  allowWatchBookmarks

• continue (查询参数): string

  continue

• fieldSelector (查询参数): string

  fieldSelector

• labelSelector (查询参数): string

  labelSelector

• limit (查询参数): integer

  limit

• pretty (查询参数): string

  pretty

• resourceVersion (查询参数): string

  resourceVersion

• resourceVersionMatch (查询参数): string

  resourceVersionMatch

• timeoutSeconds (查询参数): integer

  timeoutSeconds

• watch (查询参数): boolean

  watch

响应

200 (IngressList): OK

401: Unauthorized

list 列出或监测 Ingress 类型对象

HTTP 请求

GET /apis/networking.k8s.io/v1/ingresses

参数

• allowWatchBookmarks (查询参数): boolean

  allowWatchBookmarks

• continue (查询参数): string

  continue

• fieldSelector (查询参数): string

  fieldSelector

• labelSelector (查询参数): string

  labelSelector

• limit (查询参数): integer

  limit

• pretty (查询参数): string

  pretty

• resourceVersion (查询参数): string

  resourceVersion

• resourceVersionMatch (in query): string -->

• resourceVersionMatch (查询参数): string

  resourceVersionMatch

• timeoutSeconds (查询参数): integer

  timeoutSeconds

• watch (查询参数): boolean

  watch

响应

200 (IngressList): OK

401: Unauthorized

create 创建一个 Ingress

HTTP 请求

POST /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses

参数

• namespace (路径参数): string，必需

  namespace

• body: Ingress，必需

• dryRun (查询参数): string

  dryRun

• fieldManager (查询参数): string

  fieldManager

• fieldValidation (查询参数): string

  fieldValidation

• pretty (查询参数): string

  pretty

响应

200 (Ingress): OK

201 (Ingress): Created

202 (Ingress): Accepted

401: Unauthorized

update 替换指定的 Ingress

HTTP 请求

PUT /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses/{name}

参数

• name (路径参数): string，必需

  Ingress 的名称。

• namespace (路径参数): string，必需

  namespace

• body: Ingress，必需

• dryRun (查询参数): string

  dryRun

• fieldManager (查询参数): string

  fieldManager

• fieldValidation (查询参数): string

  fieldValidation

• pretty (查询参数): string

  pretty

响应

200 (Ingress): OK

201 (Ingress): Created

401: Unauthorized

update 替换指定 Ingress 的状态

HTTP 请求

PUT /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses/{name}/status

参数

• name (路径参数)：string，必需

  Ingress 的名称。

• namespace (路径参数)：string，必需

  namespace

• body: Ingress，必需

• dryRun (查询参数): string

  dryRun

• fieldManager (查询参数): string

  fieldManager

• fieldValidation (查询参数): string

  fieldValidation

• pretty (查询参数): string

  pretty

响应

200 (Ingress): OK

201 (Ingress): Created

401: Unauthorized

patch 部分更新指定的 Ingress

HTTP 请求

PATCH /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses/{name}

参数

• name (路径参数)：string，必需

  Ingress 的名称。

• namespace (路径参数)：string，必需

  namespace

• body: Patch，必需

• dryRun (查询参数): string

  dryRun

• fieldManager (查询参数): string

  fieldManager

• fieldValidation (查询参数): string

  fieldValidation

• force (查询参数): boolean

  force

• pretty (查询参数): string

  pretty

响应

200 (Ingress): OK

201 (Ingress): Created

401: Unauthorized

patch 部分更新指定 Ingress 的状态

HTTP 请求

PATCH /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses/{name}/status

参数

• name (路径参数)：string，必需

  Ingress 的名称。

• namespace (路径参数)：string，必需

  namespace

• body: Patch，必需

• dryRun (查询参数): string

  dryRun

• fieldManager (查询参数): string

  fieldManager

• fieldValidation (查询参数): string

  fieldValidation

• force (查询参数): boolean

  force

• pretty (查询参数): string

  pretty

响应

200 (Ingress): OK

201 (Ingress): Created

401: Unauthorized

delete 删除一个 Ingress

HTTP 请求

DELETE /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses/{name}

参数

• name (路径参数)：string，必需

  Ingress 的名称。

• namespace (路径参数)：string，必需

  namespace

• body: DeleteOptions

• dryRun (查询参数): string

  dryRun

• gracePeriodSeconds (查询参数): integer

  gracePeriodSeconds

• pretty (查询参数): string

  pretty

• propagationPolicy (查询参数): string

  propagationPolicy

响应

200 (Status): OK

202 (Status): Accepted

401: Unauthorized

deletecollection 删除 Ingress 的集合

HTTP 请求

DELETE /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses

参数

• namespace (路径参数)：string，必需

  namespace

• body: DeleteOptions

• continue (查询参数): string

  continue

• dryRun (查询参数): string

  dryRun

• fieldSelector (查询参数): string

  fieldSelector

• gracePeriodSeconds (查询参数): integer

  gracePeriodSeconds

• labelSelector (查询参数): string

  labelSelector

• limit (查询参数): integer

  limit

• pretty (查询参数): string

  pretty

• propagationPolicy (查询参数): string

  propagationPolicy

• resourceVersion (查询参数): string

  resourceVersion

• resourceVersionMatch (查询参数): string

  resourceVersionMatch

• timeoutSeconds (查询参数): integer

  timeoutSeconds

响应

200 (Status): OK

401: Unauthorized