Distributed Configuration with Consul

Consul 提供一个 Key/Value Store 用于存储配置和其他元数据。Spring Cloud Consul Config 是一种替代品，即 Config Server and Client。配置在特殊的“bootstrap”阶段加载到 Spring Environment 中。默认情况下，配置存储在 /config 文件夹中。根据应用程序的名称和活动配置文件创建多个 PropertySource 实例，这模拟了 Spring Cloud Config 解析属性的顺序。例如，名称为“testApp”且具有“dev”配置文件的应用程序将创建以下属性源：

Consul provides a Key/Value Store for storing configuration and other metadata. Spring Cloud Consul Config is an alternative to the Config Server and Client. Configuration is loaded into the Spring Environment during the special "bootstrap" phase. Configuration is stored in the /config folder by default. Multiple PropertySource instances are created based on the application’s name and the active profiles that mimics the Spring Cloud Config order of resolving properties. For example, an application with the name "testApp" and with the "dev" profile will have the following property sources created:

config/testApp,dev/
config/testApp/
config/application,dev/
config/application/

最具体的属性源位于顶部，最不具体的属性源位于底部。 config/application 文件夹中的属性适用于使用 consul 进行配置的所有应用程序。 config/testApp 文件夹中的属性仅适用于名为“testApp”的服务实例。

The most specific property source is at the top, with the least specific at the bottom. Properties in the config/application folder are applicable to all applications using consul for configuration. Properties in the config/testApp folder are only available to the instances of the service named "testApp".

配置当前在应用程序启动后读取。向 /refresh 发送 HTTP POST 将导致重新加载配置。Config Watch 还将自动检测更改并重新加载应用程序上下文。

Configuration is currently read on startup of the application. Sending a HTTP POST to /refresh will cause the configuration to be reloaded. Config Watch will also automatically detect changes and reload the application context.

How to activate

如需通过Consul配置开始，请使用组为`org.springframework.cloud`且工件ID为`spring-cloud-starter-consul-config`的starter。请参阅 Spring Cloud Project page了解有关使用当前Spring Cloud Release Train设置构建系统的详细信息。

To get started with Consul Configuration use the starter with group org.springframework.cloud and artifact id spring-cloud-starter-consul-config. See the Spring Cloud Project page for details on setting up your build system with the current Spring Cloud Release Train.

Spring Boot Config Data Import

Spring Boot 2.4 引入了一种通过 spring.config.import 属性导入配置数据的新方法。这是从 Consul 获取配置的默认方式。

Spring Boot 2.4 introduced a new way to import configuration data via the spring.config.import property. This is now the default way to get configuration from Consul.

要选择连接到 Consul，请在 application.properties 中设置以下内容：

To optionally connect to Consul set the following in application.properties:

application.properties

spring.config.import=optional:consul:

这将连接到“http://localhost:8500”默认位置的 Consul Agent。删除 optional: 前缀将导致如果无法连接到 Consul，则 Consul Config 失败。要更改 Consul Config 的连接属性，请设置 spring.cloud.consul.host 和 spring.cloud.consul.port 或将主机/端口对添加到 spring.config.import 语句中，例如 spring.config.import=optional:consul:myhost:8500。导入属性中的位置优先于主机和端口属性。

This will connect to the Consul Agent at the default location of "http://localhost:8500". Removing the optional: prefix will cause Consul Config to fail if it is unable to connect to Consul. To change the connection properties of Consul Config either set spring.cloud.consul.host and spring.cloud.consul.port or add the host/port pair to the spring.config.import statement such as, spring.config.import=optional:consul:myhost:8500. The location in the import property has precedence over the host and port propertie.

Consul Config 将尝试根据 spring.cloud.consul.config.name（默认为 spring.application.name 属性的值）和 spring.cloud.consul.config.default-context（默认为 application）从四个自动上下文加载值。如果您想指定上下文而不是使用计算出的上下文，则可以将该信息添加到 spring.config.import 语句中。

Consul Config will try to load values from four automatic contexts based on spring.cloud.consul.config.name (which defaults to the value of the spring.application.name property) and spring.cloud.consul.config.default-context (which defaults to application). If you want to specify the contexts rather than using the computed ones, you can add that information to the spring.config.import statement.

application.properties

spring.config.import=optional:consul:myhost:8500/contextone;/context/two

这样会仅从 /contextone 和 /context/two 加载配置（可选）。

This will optionally load configuration only from /contextone and /context/two.

对于通过 spring.config.import 导入 Spring Boot 配置数据的方法，需要一个 bootstrap 文件（属性或 yaml）。

A bootstrap file (properties or yaml) is not needed for the Spring Boot Config Data method of import via spring.config.import.

Customizing

консу尔配置可借助以下属性进行自定义：

Consul Config may be customized using the following properties:

spring:
  cloud:
    consul:
      config:
        enabled: true
        prefix: configuration
        defaultContext: apps
        profileSeparator: '::'

如果你已经设置了 spring.cloud.bootstrap.enabled=true 或 spring.config.use-legacy-processing=true，或者包含了 spring-cloud-starter-bootstrap，那么上述值需要放在 bootstrap.yml 中，而不是 application.yml。

If you have set spring.cloud.bootstrap.enabled=true or spring.config.use-legacy-processing=true, or included spring-cloud-starter-bootstrap, then the above values will need to be placed in bootstrap.yml instead of application.yml.

enabled setting this value to "false" disables Consul Config
prefix sets the base folder for configuration values
defaultContext sets the folder name used by all applications
profileSeparator sets the value of the separator used to separate the profile name in property sources with profiles

Config Watch

Consul Config Watch 利用了 consul 能够 watch a key prefix的能力。Config Watch 发出一个阻止 Consul HTTP API 调用，以确定是否已经为当前应用程序更改了任何相关配置数据。如果存在新的配置数据，则会发布刷新事件。这相当于调用 `/refresh`执行器端点。

The Consul Config Watch takes advantage of the ability of consul to watch a key prefix. The Config Watch makes a blocking Consul HTTP API call to determine if any relevant configuration data has changed for the current application. If there is new configuration data a Refresh Event is published. This is equivalent to calling the /refresh actuator endpoint.

若要更改配置监听调用的频率，请更改 spring.cloud.consul.config.watch.delay。默认值为 1000（毫秒）。延迟是在上一次调用结束与下次调用开始之间的时间量。

To change the frequency of when the Config Watch is called change spring.cloud.consul.config.watch.delay. The default value is 1000, which is in milliseconds. The delay is the amount of time after the end of the previous invocation and the start of the next.

若要禁用配置监听，请设置 spring.cloud.consul.config.watch.enabled=false。

To disable the Config Watch set spring.cloud.consul.config.watch.enabled=false.

监听使用 Spring TaskScheduler 安排对 консу尔的调用。默认情况下，它是一个“线程池任务计划程序”，poolSize 为 1。若要更改 TaskScheduler，请创建一个名为 ConsulConfigAutoConfiguration.CONFIG_WATCH_TASK_SCHEDULER_NAME 常量的类型为 TaskScheduler 的 bean。

The watch uses a Spring TaskScheduler to schedule the call to consul. By default it is a ThreadPoolTaskScheduler with a poolSize of 1. To change the TaskScheduler, create a bean of type TaskScheduler named with the ConsulConfigAutoConfiguration.CONFIG_WATCH_TASK_SCHEDULER_NAME constant.

YAML or Properties with Config

与将属性存储为各个键/值对相比，以 YAML 或属性格式存储属性 blob 可能更方便。将 spring.cloud.consul.config.format 属性设置为 YAML 或 PROPERTIES。例如，要使用 YAML：

It may be more convenient to store a blob of properties in YAML or Properties format as opposed to individual key/value pairs. Set the spring.cloud.consul.config.format property to YAML or PROPERTIES. For example to use YAML:

spring:
  cloud:
    consul:
      config:
        format: YAML

必须在 консу尔中相应的 data 密钥中设置 YAML。使用上述默认值，秘钥将如下所示：

YAML must be set in the appropriate data key in consul. Using the defaults above the keys would look like:

config/testApp,dev/data
config/testApp/data
config/application,dev/data
config/application/data

您可以在上面列出任何一个秘钥中存储 YAML 文档。

You could store a YAML document in any of the keys listed above.

您可以使用 spring.cloud.consul.config.data-key 更改数据秘钥。

You can change the data key using spring.cloud.consul.config.data-key.

git2consul with Config

git2consul 是一个 Consul 社区项目，它将 git 存储库中的文件加载到 Consul 中各个单独的秘钥中。默认情况下，秘钥名称为文件名称。YAML 和属性文件受支持，它们的文件扩展名分别为 .yml 和 .properties。将 spring.cloud.consul.config.format 属性设置为 FILES。例如：

git2consul is a Consul community project that loads files from a git repository to individual keys into Consul. By default the names of the keys are names of the files. YAML and Properties files are supported with file extensions of .yml and .properties respectively. Set the spring.cloud.consul.config.format property to FILES. For example:

bootstrap.yml

spring:
  cloud:
    consul:
      config:
        format: FILES

假设在 /config 中有以下秘钥、development 配置和应用程序名称 foo：

Given the following keys in /config, the development profile and an application name of foo:

.gitignore
application.yml
bar.properties
foo-development.properties
foo-production.yml
foo.properties
master.ref

将创建以下属性源：

the following property sources would be created:

config/foo-development.properties
config/foo.properties
config/application.yml

每个秘钥的值都必须是已正确格式化的 YAML 或属性文件。

The value of each key needs to be a properly formatted YAML or Properties file.

Fail Fast

在某些情况下（例如本地开发或某些测试场景），如果 консу尔不可用于配置，则不出现故障可能很方便。设置 spring.cloud.consul.config.fail-fast=false 将使配置模块记录一条警告，而不是抛出异常。这将允许应用程序正常继续启动。

It may be convenient in certain circumstances (like local development or certain test scenarios) to not fail if consul isn’t available for configuration. Setting spring.cloud.consul.config.fail-fast=false will cause the configuration module to log a warning rather than throw an exception. This will allow the application to continue startup normally.