此版本仍在开发中，尚未被视为稳定版本。如需最新的稳定版本，请使用 Spring Cloud Kubernetes 3.1.4！spring-doc.cadn.net.cn

适用于 Kubernetes 的 DiscoveryClient

该项目提供了 Discovery Client for Kubernetes 的实现。此客户端允许您按名称查询 Kubernetes 终端节点（请参阅服务）。服务通常由 Kubernetes API 服务器作为端点的集合公开，这些端点代表http和httpsaddresses 的地址，并且客户端可以从作为 Pod 运行的 Spring Boot 应用程序访问。spring-doc.cadn.net.cn

DiscoveryClient 还可以找到ExternalName（请参阅 ExternalName 服务）。目前，仅当满足以下属性时，外部名称支持类型的服务才可用spring.cloud.kubernetes.discovery.include-external-name-services设置为true（它是false默认情况下）。spring-doc.cadn.net.cn

我们支持 3 种类型的发现客户端：spring-doc.cadn.net.cn

1.spring-doc.cadn.net.cn

Fabric8 Kubernetes 客户端spring-doc.cadn.net.cn

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-kubernetes-fabric8</artifactId>
</dependency>

2.spring-doc.cadn.net.cn

Kubernetes Java 客户端spring-doc.cadn.net.cn

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-kubernetes-client</artifactId>
</dependency>

3.spring-doc.cadn.net.cn

基于 HTTPDiscoveryClientspring-doc.cadn.net.cn

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-kubernetes-discoveryclient</artifactId>
</dependency>

spring-cloud-starter-kubernetes-discoveryclient旨在与 Spring Cloud Kubernetes DiscoveryServer 一起使用。

要启用加载DiscoveryClient加@EnableDiscoveryClient添加到相应的 Configuration 或 Application 类中，如下例所示：spring-doc.cadn.net.cn

@SpringBootApplication
@EnableDiscoveryClient
public class Application {
  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }
}

然后，您只需通过自动装配客户端即可将其注入代码中，如下例所示：spring-doc.cadn.net.cn

@Autowired
private DiscoveryClient discoveryClient;

您应该问自己的第一个问题是DiscoveryClient应该发现服务。在 kubernetes 世界中，这意味着什么命名空间。这里有 3 个选项：spring-doc.cadn.net.cn

selective namespaces.例如：spring-doc.cadn.net.cn

spring.cloud.kubernetes.discovery.namespaces[0]=ns1
spring.cloud.kubernetes.discovery.namespaces[1]=ns2

这样的配置使发现客户端仅搜索两个命名空间中的服务ns1和ns2.spring-doc.cadn.net.cn

all-namespaces.spring-doc.cadn.net.cn

spring.cloud.kubernetes.discovery.all-namespaces=true

虽然存在这样的选项，但这可能会给 kube-api 和你的应用程序带来负担。很少需要这样的设置。spring-doc.cadn.net.cn

one namespace.如果未指定上述任何一项，则这是默认设置。它适用于 Namespace Resolution 中概述的规则。spring-doc.cadn.net.cn

以上选项的工作方式与为 fabric8 和 k8s 客户端编写的完全一样。对于基于 HTTP 的客户端，您需要在服务器上启用这些选项。这可以通过将它们设置为deployment.yaml用于使用 env 变量在集群中部署镜像。

例如：spring-doc.cadn.net.cn

      containers:
        - name: discovery-server
          image: springcloud/spring-cloud-kubernetes-discoveryserver:3.0.5-SNAPSHOT
          env:
            - name: SPRING_CLOUD_KUBERNETES_DISCOVERY_NAMESPACES_0
              value: "namespace-a"

配置命名空间后，下一个要回答的问题是要发现哪些服务。将其视为要应用的过滤器。默认情况下，根本不应用筛选，并且会发现所有服务。如果需要缩小发现客户端可以查找的范围，则有两个选项：spring-doc.cadn.net.cn

仅接受与特定服务标签匹配的服务。此属性由以下项指定：spring.cloud.kubernetes.discovery.service-labels.它接受一个Map并且只有那些具有此类标签的服务（如metadata.labels）将被考虑在内。spring-doc.cadn.net.cn
另一种选择是使用 SpEL 表达式。这由spring.cloud.kubernetes.discovery.filter属性，其值取决于您选择的客户端。如果使用 fabric8 客户端，则必须针对io.fabric8.kubernetes.api.model.Service类。一个这样的例子可能是：spring-doc.cadn.net.cn

spring.cloud.kubernetes.discovery.filter='#root.metadata.namespace matches "^.+A$"'

它告诉 Discovery Client 只获取具有metadata.namespace以大写结尾A.spring-doc.cadn.net.cn

如果您的发现客户端基于 k8s-native 客户端，则 SPEL 表达式必须基于io.kubernetes.client.openapi.models.V1Service类。上面显示的相同过滤器在这里也有效。spring-doc.cadn.net.cn

如果您的发现客户端是基于 http 的客户端，则 SeEL 表达式必须基于相同的io.kubernetes.client.openapi.models.V1Service类，唯一的区别是这需要在部署 YAML 中设置为 env 变量：spring-doc.cadn.net.cn

      containers:
        - name: discovery-server
          image: springcloud/spring-cloud-kubernetes-discoveryserver:3.0.5-SNAPSHOT
          env:
            - name: SPRING_CLOUD_KUBERNETES_DISCOVERY_FILTER
              value: '#root.metadata.namespace matches "^.+A$"'

现在是时候考虑 discovery client 应该返回什么了。通常，有两种方法DiscoveryClient具有：getServices和getInstances.spring-doc.cadn.net.cn

getServices将返回metadata.name.spring-doc.cadn.net.cn

此方法将返回唯一的服务名称，即使不同命名空间（您为搜索选择）之间存在重复项。

getInstances返回List<ServiceInstance>.除了通常的字段外，ServiceInstancehas，我们还添加了一些数据，例如 namespace 或 pod 元数据（有关这些的更多解释将在文档中提供）。以下是我们目前返回的数据：spring-doc.cadn.net.cn

instanceId- 服务实例的唯一 IDspring-doc.cadn.net.cn
serviceId- 服务的名称（与调用getServices)spring-doc.cadn.net.cn
host- 实例的 IP（如果是ExternalName服务类型）spring-doc.cadn.net.cn
port- 实例的端口号。这需要更多的解释，因为选择端口号有其规则：spring-doc.cadn.net.cn
1. service 未定义端口，则返回 0（零）。spring-doc.cadn.net.cn
2. service 定义了一个端口，该端口将被返回。spring-doc.cadn.net.cn
3. 如果服务具有标签primary-port-name，我们将使用具有标签值中指定的名称的端口号。spring-doc.cadn.net.cn
4. 如果上述标签不存在，那么我们将使用spring.cloud.kubernetes.discovery.primary-port-name以查找端口号。spring-doc.cadn.net.cn
5. 如果以上都未指定，我们将使用名为https或http以计算端口号。spring-doc.cadn.net.cn
6. 作为最后的手段，我们将选择端口列表中的第一个端口。最后一个选项可能会导致非确定性行为。spring-doc.cadn.net.cn
uri服务实例的spring-doc.cadn.net.cn
scheme也http或https（取决于secure结果）spring-doc.cadn.net.cn
metadata的服务范围：spring-doc.cadn.net.cn
1. labels（如果通过spring.cloud.kubernetes.discovery.metadata.add-labels=true).标签键可以 “前缀” 为spring.cloud.kubernetes.discovery.metadata.labels-prefix如果已设置。spring-doc.cadn.net.cn
2. annotations（如果通过spring.cloud.kubernetes.discovery.metadata.add-annotations=true).注解键可以 “前缀” 为spring.cloud.kubernetes.discovery.metadata.annotations-prefix如果已设置。spring-doc.cadn.net.cn
3. ports（如果通过spring.cloud.kubernetes.discovery.metadata.add-ports=true).端口键可以 “prefixed” with the valuespring.cloud.kubernetes.discovery.metadata.ports-prefix如果已设置。spring-doc.cadn.net.cn
4. k8s_namespace替换为 instance 所在的命名空间的值。spring-doc.cadn.net.cn
5. type，它保存 Service 类型，例如ClusterIP或ExternalNamespring-doc.cadn.net.cn
secure如果发现的端口应被视为安全端口。我们将使用上面概述的相同规则来查找端口名称和编号，然后：spring-doc.cadn.net.cn
1. 如果此服务具有名为secured替换为以下任一值：["true", "on", "yes", "1"]，然后将找到的端口视为安全端口。spring-doc.cadn.net.cn
2. 如果未找到此类标签，请搜索名为secured并应用相同的上述规则。spring-doc.cadn.net.cn
3. 如果此端口号是spring.cloud.kubernetes.discovery.known-secure-ports（默认情况下，此值保持不变[443, 8443]），请将端口号视为安全端口号。spring-doc.cadn.net.cn
4. 最后的手段是查看端口名称是否匹配https;如果确实，则将此端口视为安全端口。spring-doc.cadn.net.cn
namespace- 找到的实例的命名空间。spring-doc.cadn.net.cn
pod-metadata服务实例（Pod）的标签和注解，采用Map<String, Map<String, String>>.此支持需要通过以下方式启用spring.cloud.kubernetes.discovery.metadata.add-pod-labels=true和/或spring.cloud.kubernetes.discovery.metadata.add-pod-annotaations=truespring-doc.cadn.net.cn

要发现未被 kubernetes api 服务器标记为 “ready” 的服务端点地址，您可以在application.properties（默认值：false）：spring-doc.cadn.net.cn

spring.cloud.kubernetes.discovery.include-not-ready-addresses=true

这在发现用于监控目的的服务时可能很有用，并且可以检查/health未就绪服务实例的终端节点。如果要获取ServiceInstance要还包括ExternalName键入 services，您需要通过以下方式启用该支持：spring.cloud.kubernetes.discovery.include-external-name-services=true.因此，在调用DiscoveryClient::getInstances这些也会被退回。您可以区分ExternalName和任何其他类型的ServiceInstance::getMetadata并查找名为type.这将是返回的服务类型：ExternalName/ClusterIP等。如果出于任何原因，您需要禁用DiscoveryClient中，您可以在application.properties:

spring.main.cloud-platform=NONE

请注意，对 discovery client 的支持是自动的，具体取决于您运行应用程序的位置。因此，可能不需要上述设置。spring-doc.cadn.net.cn

一些 Spring Cloud 组件使用DiscoveryClient以获取有关本地服务实例的信息。为要正常工作，您需要将 Kubernetes 服务名称与spring.application.name财产。spring-doc.cadn.net.cn

spring.application.name只要在 Kubernetes 中为应用程序注册的名称，则没有影响

Spring Cloud Kubernetes 还可以查看 Kubernetes 服务目录的更改，并更新DiscoveryClient相应地实施。要启用此功能，您需要添加@EnableScheduling在应用程序中的 Configuration 类上。“watch” 是指我们将在每个spring.cloud.kubernetes.discovery.catalog-services-watch-delay毫秒（默认情况下为30000).对于 http 发现服务器，这必须是在部署 yaml 中设置的环境变量：spring-doc.cadn.net.cn

      containers:
        - name: discovery-server
          image: springcloud/spring-cloud-kubernetes-discoveryserver:3.0.5-SNAPSHOT
          env:
            - name: SPRING_CLOUD_KUBERNETES_DISCOVERY_CATALOGSERVICESWATCHDELAY
              value: 3000

heartbeat 事件将包含目标引用（及其所有端点地址的命名空间（有关将退回的内容的确切详细信息，您可以查看内部KubernetesCatalogWatch).这是一个实现细节，以及 heartbeat 事件的侦听器不应依赖细节。相反，他们应该通过equals方法。我们将注意返回符合 equals 协定的正确实现。将在以下任一位置查询端点： -all-namespaces（通过spring.cloud.kubernetes.discovery.all-namespaces=true)spring-doc.cadn.net.cn

selective namespaces（通过spring.cloud.kubernetes.discovery.namespaces），例如：spring-doc.cadn.net.cn
one namespace通过 Namespace Resolution 如果未采用上述两条路径。spring-doc.cadn.net.cn

如果出于任何原因想要禁用 catalog watcher，则需要将spring.cloud.kubernetes.discovery.catalog-services-watch.enabled=false.对于 http 发现服务器，这需要是在部署中设置的环境变量，例如：

SPRING_CLOUD_KUBERNETES_DISCOVERY_CATALOGSERVICESWATCH_ENABLED=FALSE

catalog watch 的功能适用于我们支持的所有 3 个发现客户端，但在使用 http 客户端时需要注意一些注意事项。spring-doc.cadn.net.cn

首先是此功能默认处于禁用状态，需要在两个地方启用：spring-doc.cadn.net.cn

在 Discovery Server 中，通过部署清单中的环境变量，例如：spring-doc.cadn.net.cn

containers:
        - name: discovery-server
          image: springcloud/spring-cloud-kubernetes-discoveryserver:3.0.5-SNAPSHOT
          env:
            - name: SPRING_CLOUD_KUBERNETES_HTTP_DISCOVERY_CATALOG_WATCHER_ENABLED
              value: "TRUE"

在 Discovery Client 中，通过application.properties例如：spring-doc.cadn.net.cn
```
spring.cloud.kubernetes.http.discovery.catalog.watcher.enabled=true
```

第二点是，这只从 version 开始支持3.0.6和向上。spring-doc.cadn.net.cn
由于 http 发现有两个组件：服务器和客户端，我们强烈建议在它们之间对齐版本，否则可能无法工作。spring-doc.cadn.net.cn
如果您决定禁用 catalog watcher，则需要在 server 和 client 中禁用它。spring-doc.cadn.net.cn

默认情况下，我们使用Endpoints（见 kubernetes.io/docs/concepts/services-networking/service/#endpoints）API 来了解服务的当前状态。不过还有另一种方法，通过EndpointSlices (kubernetes.io/docs/concepts/services-networking/endpoint-slices/）。可以通过以下属性启用此类支持：spring.cloud.kubernetes.discovery.use-endpoint-slices=true（默认情况下为false).当然，您的集群也必须支持它。事实上，如果您启用了此属性，但您的集群不支持它，我们将无法启动应用程序。如果您决定启用此类支持，则还需要适当的 Role/ClusterRole 设置。例如：spring-doc.cadn.net.cn

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: default
  name: namespace-reader
rules:
  - apiGroups: ["discovery.k8s.io"]
    resources: ["endpointslices"]
    verbs: ["get", "list", "watch"]