5. Kubernetes PropertySource 实现
配置 Spring Boot 应用程序最常用的方法是创建一个 application.properties、application.yaml、application-profile.properties 或 application-profile.yaml 文件，其中包含键值对，用于为您的应用程序或 Spring Boot Starters提供自定义值。您可以通过指定系统属性或环境变量来覆盖这些属性。
5.1. 使用 ConfigMap PropertySource
Kubernetes 提供了一个名为 ConfigMap 的资源，用于将参数外部化以传递给您的应用程序，这些参数可以以键值对的形式、嵌入的 application.properties 或 application.yaml 文件形式提供。Spring Cloud Kubernetes Config 项目在应用程序启动时使 Kubernetes ConfigMap 实例可用，并在检测到所监视的 ConfigMap 实例发生更改时触发 bean 或 Spring 上下文的热重载。
默认行为是基于一个 Kubernetes ConfigMap 创建一个 Fabric8ConfigMapPropertySource，该 Kubernetes ConfigMap 的 metadata.name 值为以下之一：您的 Spring 应用程序名称（由其 spring.application.name 属性定义）或在 bootstrap.properties 文件中通过以下键定义的自定义名称：spring.cloud.kubernetes.config.name。
然而，更高级的配置也是可能的，您可以在其中使用多个 ConfigMap 实例。spring.cloud.kubernetes.config.sources 列表使这种可能性成为现实。例如，您可以定义以下 ConfigMap 实例：
spring:
application:
name: cloud-k8s-app
cloud:
kubernetes:
config:
name: default-name
namespace: default-namespace
sources:
# Spring Cloud Kubernetes looks up a ConfigMap named c1 in namespace default-namespace
- name: c1
# Spring Cloud Kubernetes looks up a ConfigMap named default-name in whatever namespace n2
- namespace: n2
# Spring Cloud Kubernetes looks up a ConfigMap named c3 in namespace n3
- namespace: n3
name: c3在前面的示例中，如果未设置spring.cloud.kubernetes.config.namespace，则会根据应用程序运行的命名空间查找名为ConfigMap的c1。请参阅命名空间解析，以更好地理解应用程序的命名空间是如何解析的。
任何找到的匹配项 ConfigMap 都按如下方式处理：
-
应用单独的配置属性。
-
将
yaml应用于任何名为application.yaml的属性的内容。 -
将任意名为
application.properties的属性的内容作为属性文件应用。
上述流程的唯一例外情况是，当 ConfigMap 包含一个单一键，且该键指示文件为 YAML 或属性文件时。在此情况下，该键的名称不一定要是 application.yaml 或 application.properties（可以是任意值），且该属性的值将被正确处理。此特性便于以下用例：ConfigMap 是通过类似如下方式创建的：
kubectl create configmap game-config --from-file=/path/to/app-config.yaml假设我们有一个名为 demo 的 Spring Boot 应用程序，它使用以下属性来读取其线程池配置。
-
pool.size.core -
pool.size.maximum
这可以外部化为配置映射（config map）的 yaml 格式，如下所示：
kind: ConfigMap
apiVersion: v1
metadata:
name: demo
data:
pool.size.core: 1
pool.size.max: 16单个属性在大多数情况下都能正常工作。然而，有时嵌入式 yaml 会更方便。此时，我们使用一个名为 application.yaml 的单一属性来嵌入我们的 yaml，如下所示：
kind: ConfigMap
apiVersion: v1
metadata:
name: demo
data:
application.yaml: |-
pool:
size:
core: 1
max:16以下示例也适用：
kind: ConfigMap
apiVersion: v1
metadata:
name: demo
data:
custom-name.yaml: |-
pool:
size:
core: 1
max:16您还可以根据激活的配置文件以不同方式配置 Spring Boot 应用程序，这些配置文件在读取 ConfigMap 时会合并在一起。您可以通过使用 application.properties 或 application.yaml 属性来为不同配置文件提供不同的属性值，并为每个配置文件指定特定的值，每个值分别置于其各自的文档中（由 --- 序列指示），如下所示：
kind: ConfigMap
apiVersion: v1
metadata:
name: demo
data:
application.yml: |-
greeting:
message: Say Hello to the World
farewell:
message: Say Goodbye
---
spring:
profiles: development
greeting:
message: Say Hello to the Developers
farewell:
message: Say Goodbye to the Developers
---
spring:
profiles: production
greeting:
message: Say Hello to the Ops在前面的情况中，通过 development 配置文件加载到您的 Spring 应用程序中的配置如下：
greeting:
message: Say Hello to the Developers
farewell:
message: Say Goodbye to the Developers然而，如果 production 配置文件处于激活状态，则配置变为：
greeting:
message: Say Hello to the Ops
farewell:
message: Say Goodbye如果两个配置文件均处于激活状态，则在 ConfigMap 中最后出现的属性将覆盖任何先前的值。
另一种选择是为每个配置文件创建不同的配置映射（config map），Spring Boot 将根据激活的配置文件自动获取它。
kind: ConfigMap
apiVersion: v1
metadata:
name: demo
data:
application.yml: |-
greeting:
message: Say Hello to the World
farewell:
message: Say Goodbyekind: ConfigMap
apiVersion: v1
metadata:
name: demo-development
data:
application.yml: |-
spring:
profiles: development
greeting:
message: Say Hello to the Developers
farewell:
message: Say Goodbye to the Developerskind: ConfigMap
apiVersion: v1
metadata:
name: demo-production
data:
application.yml: |-
spring:
profiles: production
greeting:
message: Say Hello to the Ops
farewell:
message: Say Goodbye要告诉 Spring Boot 在启动时启用哪些 profile，您可以传递 SPRING_PROFILES_ACTIVE 环境变量。为此，您可以在容器规范的 PodSpec 中定义该环境变量，并通过该环境变量启动您的 Spring Boot 应用程序。部署资源文件示例如下：
apiVersion: apps/v1
kind: Deployment
metadata:
name: deployment-name
labels:
app: deployment-name
spec:
replicas: 1
selector:
matchLabels:
app: deployment-name
template:
metadata:
labels:
app: deployment-name
spec:
containers:
- name: container-name
image: your-image
env:
- name: SPRING_PROFILES_ACTIVE
value: "development"您可能会遇到这样的情况：存在多个配置映射，它们具有相同的属性名称。例如：
kind: ConfigMap
apiVersion: v1
metadata:
name: config-map-one
data:
application.yml: |-
greeting:
message: Say Hello from one和
kind: ConfigMap
apiVersion: v1
metadata:
name: config-map-two
data:
application.yml: |-
greeting:
message: Say Hello from two根据您在 bootstrap.yaml|properties 中放置这些项的顺序，您可能会得到一个意外的结果（最后一个配置映射会覆盖之前的）。例如：
spring:
application:
name: cloud-k8s-app
cloud:
kubernetes:
config:
namespace: default-namespace
sources:
- name: config-map-two
- name: config-map-one将导致属性 greetings.message 的值为 Say Hello from one。
可以通过指定 useNameAsPrefix 来更改此默认配置。例如：
spring:
application:
name: with-prefix
cloud:
kubernetes:
config:
useNameAsPrefix: true
namespace: default-namespace
sources:
- name: config-map-one
useNameAsPrefix: false
- name: config-map-two这种配置将生成两个属性：
-
greetings.message等于Say Hello from one。 -
config-map-two.greetings.messageequal toSay Hello from two
注意，spring.cloud.kubernetes.config.useNameAsPrefix的优先级比spring.cloud.kubernetes.config.sources.useNameAsPrefix低。这允许为所有源设置默认策略，同时只覆盖其中几个。
如果使用配置映射名称不是选项，您可以指定一个不同的策略，称为explicitPrefix。由于这是一个您选择的显式前缀，它只能在sources级提供。同时，它的优先级比useNameAsPrefix高。假设我们有一个带有以下条目的第三个配置映射：
kind: ConfigMap
apiVersion: v1
metadata:
name: config-map-three
data:
application.yml: |-
greeting:
message: Say Hello from three一种如下的配置:
spring:
application:
name: with-prefix
cloud:
kubernetes:
config:
useNameAsPrefix: true
namespace: default-namespace
sources:
- name: config-map-one
useNameAsPrefix: false
- name: config-map-two
explicitPrefix: two
- name: config-map-three将会生成三个属性:
-
greetings.message等于Say Hello from one。 -
two.greetings.message等于Say Hello from two。 -
config-map-three.greetings.message等于Say Hello from three。
默认情况下，除了读取在sources配置中指定的配置映射外，Spring 还会尝试从“基于 profile 的”源读取所有属性。最简单的方式来解释这一点是通过一个示例。假设您的应用程序启用了名为 "dev" 的 profile，且您有一个如下所示的配置：
spring:
application:
name: spring-k8s
cloud:
kubernetes:
config:
namespace: default-namespace
sources:
- name: config-map-one除了阅读代码config-map-one，Spring还会尝试读取代码1>；在这种特定的顺序中。每个活动配置文件都会生成这样一个与配置文件相关的映射。
即使你的应用程序不受此 config 映射的影响，如果需要也可以将其禁用：
spring:
application:
name: spring-k8s
cloud:
kubernetes:
config:
includeProfileSpecificSources: false
namespace: default-namespace
sources:
- name: config-map-one
includeProfileSpecificSources: false注意，就像之前一样，在两个级别都可以指定此属性：对于所有配置映射或 单独的映射；后者优先级更高。
| 您应该检查安全配置部分。要从 pod 内部访问 config 映射，您需要具有正确的 Kubernetes 服务帐户、角色和角色绑定。 |
另一种使用ConfigMap实例的方法是通过运行Spring Cloud Kubernetes应用程序并将它们挂载到Pod中，让Spring Cloud Kubernetes从文件系统中读取它们。此行为由spring.cloud.kubernetes.config.paths属性控制。您可以将其与之前描述的机制一起或单独使用。
您可以通过使用,分隔符在spring.cloud.kubernetes.config.paths中指定多个（精确）文件路径。
| 您必须提供每个属性文件的完整精确路径，因为不会递归解析目录。 |
如果使用 spring.cloud.kubernetes.config.paths 或 spring.cloud.kubernetes.secrets.path，自动重新加载功能将无法工作。您需要向 /actuator/refresh 端点发送 POST 请求，或者重启/重新部署应用程序。 |
在某些情况下，您的应用程序可能会无法加载Kubernetes API的一些ConfigMaps。如果希望您的应用程序在这些情况下失败启动过程，则可以设置spring.cloud.kubernetes.config.fail-fast=true，使应用程序启动失败，抛出异常。
你可以通过设置 spring.cloud.kubernetes.config.fail-fast=true 属性来使应用程序在出现故障时重试加载 ConfigMap 个属性源。首先，您需要
设置 spring.cloud.kubernetes.config.fail-fast=true。然后，您需要将 spring-retry
和 spring-boot-starter-aop 添加到您的类路径中。您可以设置
spring.cloud.kubernetes.config.retry.* 属性来配置重试属性，例如
最大尝试次数、退避选项（如初始间隔、乘数、最大间隔）。
如果因为某些原因已经在类路径上拥有spring-retry和spring-boot-starter-aop，但想要启用快速失败，却不希望启用重试；可以对ConfigMapPropertySources进行禁用重试，通过设置spring.cloud.kubernetes.config.retry.enabled=false。 |
| 姓名 | 类型 | 默认 | 描述 |
|---|---|---|---|
|
|
|
启用配置映射 0 |
|
|
|
设置要查找的 |
|
|
Client 命名空间 |
设置要在其中查找的 Kubernetes 命名空间 |
|
|
|
设置为零个实例挂载的路径 |
|
|
|
启用或禁用通过API消费 |
|
|
|
设置在配置类上，以编程方式控制是否在从注册表加载时使应用程序启动失败。如果未设置，则默认值为抛出异常，除非有其他特殊规则。 |
|
|
|
启用或禁用配置重试。 |
|
|
|
初始重试间隔（毫秒数）。 |
|
|
|
当前最大尝试次数。 |
|
|
|
最大回退间隔。 |
|
|
|
乘数用于下一个间隔。 |
5.2. 密钥 PropertySource
Kubernetes 具有 Secrets（密钥）的概念，用于存储敏感数据，例如密码、OAuth Tokens等。本项目提供了与 Secrets 的集成，以便让 Spring Boot 应用程序能够访问这些密钥。您可以通过设置 spring.cloud.kubernetes.secrets.enabled 属性来显式启用或禁用此功能。
启用后，Fabric8SecretsPropertySource 会从以下来源查找 Kubernetes 中的 Secrets：
-
递归读取密钥挂载
-
以应用程序命名（如
spring.application.name所定义） -
匹配某些标签
注意：
默认情况下，出于安全考虑，通过 API 消费密钥（上述第 2 和第 3 点）未启用。对密钥的 'list' 权限允许客户端在指定命名空间中查看密钥值。此外，我们建议通过挂载卷的方式让容器共享密钥。
如果您启用了通过 API 消费密钥，我们建议您通过授权策略（如 RBAC）来限制对密钥的访问。有关通过 API 消费密钥时的风险和最佳实践的更多信息，请参阅 本文档。
如果找到密钥，其数据将可供应用程序使用。
假设我们有一个名为 demo 的 Spring Boot 应用程序，它使用属性来读取数据库配置。我们可以使用以下命令创建一个 Kubernetes 密钥：
kubectl create secret generic db-secret --from-literal=username=user --from-literal=password=p455w0rd前面的命令将创建以下密钥（您可以通过使用 kubectl get secrets db-secret -o yaml 查看）：
apiVersion: v1
data:
password: cDQ1NXcwcmQ=
username: dXNlcg==
kind: Secret
metadata:
creationTimestamp: 2017-07-04T09:15:57Z
name: db-secret
namespace: default
resourceVersion: "357496"
selfLink: /api/v1/namespaces/default/secrets/db-secret
uid: 63c89263-6099-11e7-b3da-76d6186905a8
type: Opaque注意，数据包含由 create 命令提供的字面量的 Base64 编码版本。
您的应用随后可以使用此密钥——例如，通过将密钥的值导出为环境变量：
apiVersion: v1
kind: Deployment
metadata:
name: ${project.artifactId}
spec:
template:
spec:
containers:
- env:
- name: DB_USERNAME
valueFrom:
secretKeyRef:
name: db-secret
key: username
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: db-secret
key: password您可以以多种方式选择要使用的密钥：
-
通过列出秘密映射的目录：
-Dspring.cloud.kubernetes.secrets.paths=/etc/secrets/db-secret,etc/secrets/postgresql如果您已将所有密钥映射到一个共同的根路径，您可以按如下方式设置它们：
-Dspring.cloud.kubernetes.secrets.paths=/etc/secrets -
通过设置命名的密钥：
-Dspring.cloud.kubernetes.secrets.name=db-secret -
通过定义一个标签列表：<br />
-Dspring.cloud.kubernetes.secrets.labels.broker=activemq -Dspring.cloud.kubernetes.secrets.labels.db=postgresql
就像对于ConfigMap一样，还可以使用多个Secret实例进行更高级的配置。该spring.cloud.kubernetes.secrets.sources列表使其成为可能。
例如，您可以定义以下Secret实例：
spring:
application:
name: cloud-k8s-app
cloud:
kubernetes:
secrets:
name: default-name
namespace: default-namespace
sources:
# Spring Cloud Kubernetes looks up a Secret named s1 in namespace default-namespace
- name: s1
# Spring Cloud Kubernetes looks up a Secret named default-name in namespace n2
- namespace: n2
# Spring Cloud Kubernetes looks up a Secret named s3 in namespace n3
- namespace: n3
name: s3在前面的例子中，如果没有设置spring.cloud.kubernetes.secrets.namespace，
则名为Secret的s1将从应用程序运行的命名空间中查找。
请参阅命名空间解析以更好地了解应用程序命名空间如何解析。
与ConfigMaps相似;如果希望在无法加载Secrets属性源时使应用程序无法启动,可以设置spring.cloud.kubernetes.secrets.fail-fast=true。
也可以在 0 属性源上启用重试，如 2 。
与 3 属性源一样，首先需要设置 4 。
然后需要将 5 和 6 添加到您的类路径中。
对 7 属性源的重试行为可以通过设置 8 配置属性来配置。
如果因为某些原因已经在类路径上拥有spring-retry和spring-boot-starter-aop，但想要启用快速失败，却不希望启用重试；可以对SecretsPropertySources进行禁用重试，通过设置spring.cloud.kubernetes.secrets.retry.enabled=false。 |
| 姓名 | 类型 | 默认 | 描述 |
|---|---|---|---|
|
|
|
禁用凭据 |
|
|
|
设置要查找的秘密的名称 |
|
|
Client 命名空间 |
设置要在其中查找的 Kubernetes 命名空间 |
|
|
|
设置用于查找机密的标签 |
|
|
|
设置密钥挂载的路径（示例 1） |
|
|
|
启用或通过 API（示例 2 和 3）禁用秘密消费 |
|
|
|
设置在配置类上，以编程方式控制是否在从注册表加载时使应用程序启动失败。如果未设置，则默认值为抛出异常，除非有其他特殊规则。 |
|
|
|
启用或禁用Secrets重试。 |
|
|
|
初始重试间隔（毫秒数）。 |
|
|
|
当前最大尝试次数。 |
|
|
|
最大回退间隔。 |
|
|
|
乘数用于下一个间隔。 |
备注：
-
The
spring.cloud.kubernetes.secrets.labels属性的行为与 基于 Map 的绑定 一致。 -
The
spring.cloud.kubernetes.secrets.pathsproperty behaves as defined by Collection-based binding. -
通过 API 访问凭据可能会因安全原因受到限制。推荐的方法是将凭据挂载到 Pod。
您可以在下面找到使用密钥（尽管尚未更新以使用新项目 0）的应用程序示例：spring-boot-camel-config
5.3. 命名空间解析
查找应用命名空间是基于最佳努力原则进行的。我们会按顺序迭代执行一些步骤来查找它。最简单且最常见的方法是在适当的配置中指定它，例如：
spring:
application:
name: app
cloud:
kubernetes:
secrets:
name: secret
namespace: default
sources:
# Spring Cloud Kubernetes looks up a Secret named 'a' in namespace 'default'
- name: a
# Spring Cloud Kubernetes looks up a Secret named 'secret' in namespace 'b'
- namespace: b
# Spring Cloud Kubernetes looks up a Secret named 'd' in namespace 'c'
- namespace: c
name: d请记住，配置映射（config maps）也可以执行相同的操作。如果未指定此类命名空间，则将按以下顺序读取它：
-
来自属性
spring.cloud.kubernetes.client.namespace -
从文件中存储的字符串，该文件由
spring.cloud.kubernetes.client.serviceAccountNamespacePath属性指定 -
从位于
/var/run/secrets/kubernetes.io/serviceaccount/namespace文件中的字符串（Kubernetes 默认命名空间路径） -
从指定的客户端方法调用（例如 fabric8 的：
KubernetesClient::getNamespace），如果客户端提供了此类方法。反过来，这可以通过环境属性进行配置。例如，fabric8 客户端可通过 "KUBERNETES_NAMESPACE" 属性进行配置；请参阅客户端文档以获取确切详情。
未能从上述步骤中找到命名空间将导致抛出异常。
5.4. 配置映射和机密的顺序
如果出于某种原因，您同时启用了配置映射（configmaps）和密钥（secrets），且两者中存在相同的属性，则来自 ConfigMap 的值具有更高的优先级。也就是说：它将覆盖密钥中找到的任何值。
5.5. PropertySource 重载
此功能已在2020.0版本中被弃用。请参阅Spring Cloud Kubernetes Configuration Watcher控制器，了解实现相同功能的替代方法。 |
某些应用程序可能需要检测外部属性源的变化，并更新其内部状态以反映新的配置。Spring Cloud Kubernetes 的重新加载功能能够在相关 ConfigMap 或 Secret 发生变化时触发应用程序的重新加载。
此功能默认是禁用的。您可以使用 0 配置属性来启用它（例如，在 1 文件中）。
以下重载级别受支持（通过设置 spring.cloud.kubernetes.reload.strategy 属性）：
-
refresh（默认值）：仅重新加载使用@ConfigurationProperties或@RefreshScope注解的配置 Bean。
此重新加载级别利用了 Spring Cloud Context 的刷新功能。 -
restart_context: 整个 SpringApplicationContext被优雅地重新启动。Bean 将根据新配置被重新创建。
为了使重启上下文功能正常工作，您必须启用并暴露重启监控端点。
management:
endpoint:
restart:
enabled: true
endpoints:
web:
exposure:
include: restart
-
shutdown: SpringApplicationContext已关闭，以触发容器的重启。当使用此级别时，请确保所有非守护线程的生命周期均绑定至ApplicationContext，并配置一个复制控制器或副本集，以便在重启后重新启动 Pod。
假设重载功能已启用，默认设置为（refresh）模式，当配置映射发生更改时，以下 Bean 将被刷新：
@Configuration
@ConfigurationProperties(prefix = "bean")
public class MyConfig {
private String message = "a message that can be changed live";
// getter and setters
}
为了看到更改实际生效，您可以创建另一个bean，定期打印消息，如下所示
@Component
public class MyBean {
@Autowired
private MyConfig config;
@Scheduled(fixedDelay = 5000)
public void hello() {
System.out.println("The message is: " + config.getMessage());
}
}
您可以通过使用 ConfigMap 来更改应用程序打印的消息，如下所示：
apiVersion: v1
kind: ConfigMap
metadata:
name: reload-example
data:
application.properties: |-
bean.message=Hello World!在与 Pod 关联的 bean.message 中对属性 ConfigMap 所做的任何更改都会反映在输出中。更 general speaking, 与 prefix 字段中定义的值前缀匹配的属性相关的更改通过@ConfigurationProperties注解被检测并反映在应用程序中。 将 ConfigMap 与 Pod 相关联 本章较早部分进行了说明。
完整的示例可在 spring-cloud-kubernetes-reload-example 中查看。
重新加载功能支持两种操作模式：
* 事件（默认）：通过使用 Kubernetes API（WebSocket）来监视 ConfigMap 或 Secret 中的更改。
任何事件都会导致配置检查，如果发生更改，则会重新加载。要监听 ConfigMap 更改，需要服务帐户上的 code>0 角色。如果要监视 Secrets，则需要更高级别的 Role（例如 1 ）（默认情况下，不监控 Secrets）
* 轮询：定期从 ConfigMaps 和 Secrets 中重新创建配置，以查看是否已更改。
可以使用 code>2 属性配置轮询周期，并默认为 15 秒。它需要与监视属性源相同的角色。这意味着，例如，在文件上装载的 Secret 源上使用轮询不需要特殊特权。
| 姓名 | 类型 | 默认 | 描述 |
|---|---|---|---|
|
|
|
启用对属性源和配置重新加载的监控 |
|
|
|
允许监控配置映射中的更改 |
|
|
|
允许监控密钥的变化 |
|
|
|
触发重新加载时所使用的策略（ |
|
|
|
指定如何监听属性源（ |
|
|
|
使用 |
说明：
* 在 ConfigMaps 或 Secrets 中不应使用下一级属性。在运行时更改这些属性可能会导致意外结果。
* 删除属性或整个 ConfigMap 不会恢复使用refresh级别时 Bean 的原始状态。