spring-cloud-static/spring-cloud-config/1.4.7.RELEASE/spring-cloud-config.xml

<?xml version="1.0" encoding="UTF-8"?>
<?asciidoc-toc?>
<?asciidoc-numbered?>
<book xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info>
<title>Spring Cloud Config</title>
<date>2019-05-22</date>
</info>
<preface>
<title></title>
<simpara><emphasis role="strong">1.4.7.RELEASE</emphasis></simpara>
<simpara>Spring Cloud Config provides server and client-side support for externalized configuration in a distributed system. With the Config Server you have a central place to manage external properties for applications across all environments. The concepts on both client and server map identically to the Spring <literal>Environment</literal> and <literal>PropertySource</literal> abstractions, so they fit very well with Spring applications, but can be used with any application running in any language. As an application moves through the deployment pipeline from dev to test and into production you can manage the configuration between those environments and be certain that applications have everything they need to run when they migrate. The default implementation of the server storage backend uses git so it easily supports labelled versions of configuration environments, as well as being accessible to a wide range of tooling for managing the content.  It is easy to add alternative implementations and plug them in with Spring configuration.</simpara>
</preface>
<chapter xml:id="_quick_start">
<title>Quick Start</title>
<simpara>Start the server:</simpara>
<screen>$ cd spring-cloud-config-server
$ ../mvnw spring-boot:run</screen>
<simpara>The server is a Spring Boot application so you can run it from your
IDE instead if you prefer (the main class is
<literal>ConfigServerApplication</literal>). Then try out a client:</simpara>
<screen>$ curl localhost:8888/foo/development
{"name":"foo","label":"master","propertySources":[
  {"name":"https://github.com/scratches/config-repo/foo-development.properties","source":{"bar":"spam"}},
  {"name":"https://github.com/scratches/config-repo/foo.properties","source":{"foo":"bar"}}
]}</screen>
<simpara>The default strategy for locating property sources is to clone a git
repository (at <literal>spring.cloud.config.server.git.uri</literal>) and use it to
initialize a mini <literal>SpringApplication</literal>. The mini-application&#8217;s
<literal>Environment</literal> is used to enumerate property sources and publish them
via a JSON endpoint.</simpara>
<simpara>The HTTP service has resources in the form:</simpara>
<screen>/{application}/{profile}[/{label}]
/{application}-{profile}.yml
/{label}/{application}-{profile}.yml
/{application}-{profile}.properties
/{label}/{application}-{profile}.properties</screen>
<simpara>where the "application" is injected as the <literal>spring.config.name</literal> in the
<literal>SpringApplication</literal> (i.e. what is normally "application" in a regular
Spring Boot app), "profile" is an active profile (or comma-separated
list of properties), and "label" is an optional git label (defaults to
"master".)</simpara>
<simpara>Spring Cloud Config Server pulls configuration for remote clients
from a git repository (which must be provided):</simpara>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo</programlisting>
<section xml:id="_client_side_usage">
<title>Client Side Usage</title>
<simpara>To use these features in an application, just build it as a Spring
Boot application that depends on spring-cloud-config-client (e.g. see
the test cases for the config-client, or the sample app). The most
convenient way to add the dependency is via a Spring Boot starter
<literal>org.springframework.cloud:spring-cloud-starter-config</literal>. There is also a
parent pom and BOM (<literal>spring-cloud-starter-parent</literal>) for Maven users and a
Spring IO version management properties file for Gradle and Spring CLI
users. Example Maven configuration:</simpara>
<formalpara>
<title>pom.xml</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">   &lt;parent&gt;
       &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
       &lt;artifactId&gt;spring-boot-starter-parent&lt;/artifactId&gt;
       &lt;version&gt;1.5.10.RELEASE&lt;/version&gt;
       &lt;relativePath /&gt; &lt;!-- lookup parent from repository --&gt;
   &lt;/parent&gt;

&lt;dependencyManagement&gt;
	&lt;dependencies&gt;
		&lt;dependency&gt;
			&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
			&lt;artifactId&gt;spring-cloud-dependencies&lt;/artifactId&gt;
			&lt;version&gt;Edgware.SR2&lt;/version&gt;
			&lt;type&gt;pom&lt;/type&gt;
			&lt;scope&gt;import&lt;/scope&gt;
		&lt;/dependency&gt;
	&lt;/dependencies&gt;
&lt;/dependencyManagement&gt;

&lt;dependencies&gt;
	&lt;dependency&gt;
		&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
		&lt;artifactId&gt;spring-cloud-starter-config&lt;/artifactId&gt;
	&lt;/dependency&gt;
	&lt;dependency&gt;
		&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
		&lt;artifactId&gt;spring-boot-starter-test&lt;/artifactId&gt;
		&lt;scope&gt;test&lt;/scope&gt;
	&lt;/dependency&gt;
&lt;/dependencies&gt;

&lt;build&gt;
	&lt;plugins&gt;
           &lt;plugin&gt;
               &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
               &lt;artifactId&gt;spring-boot-maven-plugin&lt;/artifactId&gt;
           &lt;/plugin&gt;
	&lt;/plugins&gt;
&lt;/build&gt;

   &lt;!-- repositories also needed for snapshots and milestones --&gt;</programlisting>
</para>
</formalpara>
<simpara>Then you can create a standard Spring Boot application, like this simple HTTP server:</simpara>
<screen>@SpringBootApplication
@RestController
public class Application {

    @RequestMapping("/")
    public String home() {
        return "Hello World!";
    }

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

}</screen>
<simpara>When it runs it will pick up the external configuration from the
default local config server on port 8888 if it is running. To modify
the startup behaviour you can change the location of the config server
using <literal>bootstrap.properties</literal> (like <literal>application.properties</literal> but for
the bootstrap phase of an application context), e.g.</simpara>
<screen>spring.cloud.config.uri: http://myconfigserver.com</screen>
<simpara>The bootstrap properties will show up in the <literal>/env</literal> endpoint as a
high-priority property source, e.g.</simpara>
<screen>$ curl localhost:8080/env
{
  "profiles":[],
  "configService:https://github.com/spring-cloud-samples/config-repo/bar.properties":{"foo":"bar"},
  "servletContextInitParams":{},
  "systemProperties":{...},
  ...
}</screen>
<simpara>(a property source called "configService:&lt;URL of remote
repository&gt;/&lt;file name&gt;" contains the property "foo" with value
"bar" and is highest priority).</simpara>
<note>
<simpara>the URL in the property source name is the git repository not
the config server URL.</simpara>
</note>
</section>
</chapter>
<chapter xml:id="_spring_cloud_config_server">
<title>Spring Cloud Config Server</title>
<simpara>The Server provides an HTTP, resource-based API for external
configuration (name-value pairs, or equivalent YAML content).  The
server is easily embeddable in a Spring Boot application using the
<literal>@EnableConfigServer</literal> annotation. So this app is a config server:</simpara>
<formalpara>
<title>ConfigServer.java</title>
<para>
<programlisting language="java" linenumbering="unnumbered">@SpringBootApplication
@EnableConfigServer
public class ConfigServer {
  public static void main(String[] args) {
    SpringApplication.run(ConfigServer.class, args);
  }
}</programlisting>
</para>
</formalpara>
<simpara>Like all Spring Boot apps it runs on port 8080 by default, but you
can switch it to the conventional port 8888 in various ways. The
easiest, which also sets a default configuration repository,
is by launching it with <literal>spring.config.name=configserver</literal> (there
is a <literal>configserver.yml</literal> in the Config Server jar). Another is
to use your own <literal>application.properties</literal>, e.g.</simpara>
<formalpara>
<title>application.properties</title>
<para>
<programlisting language="properties" linenumbering="unnumbered">server.port: 8888
spring.cloud.config.server.git.uri: file://${user.home}/config-repo</programlisting>
</para>
</formalpara>
<simpara>where <literal>${user.home}/config-repo</literal> is a git repository containing
YAML and properties files.</simpara>
<note>
<simpara>in Windows you need an extra "/" in the file URL if it is
absolute with a drive prefix, e.g. <literal><link xl:href="file:///${user.home}/config-repo">file:///${user.home}/config-repo</link></literal>.</simpara>
</note>
<tip>
<simpara>Here&#8217;s a recipe for creating the git repository in the example
above:</simpara>
<screen>$ cd $HOME
$ mkdir config-repo
$ cd config-repo
$ git init .
$ echo info.foo: bar &gt; application.properties
$ git add -A .
$ git commit -m "Add application.properties"</screen>
</tip>
<warning>
<simpara>using the local filesystem for your git repository is
intended for testing only. Use a server to host your
configuration repositories in production.</simpara>
</warning>
<warning>
<simpara>the initial clone of your configuration repository will
be quick and efficient if you only keep text files in it. If you start
to store binary files, especially large ones, you may experience
delays on the first request for configuration and/or out of memory
errors in the server.</simpara>
</warning>
<section xml:id="_environment_repository">
<title>Environment Repository</title>
<simpara>Where do you want to store the configuration data for the Config
Server? The strategy that governs this behaviour is the
<literal>EnvironmentRepository</literal>, serving <literal>Environment</literal> objects. This
<literal>Environment</literal> is a shallow copy of the domain from the Spring
<literal>Environment</literal> (including <literal>propertySources</literal> as the main feature). The
<literal>Environment</literal> resources are parametrized by three variables:</simpara>
<itemizedlist>
<listitem>
<simpara><literal>{application}</literal> maps to "spring.application.name" on the client side;</simpara>
</listitem>
<listitem>
<simpara><literal>{profile}</literal> maps to "spring.profiles.active" on the client (comma separated list); and</simpara>
</listitem>
<listitem>
<simpara><literal>{label}</literal> which is a server side feature labelling a "versioned" set of config files.</simpara>
</listitem>
</itemizedlist>
<simpara>Repository implementations generally behave just like a Spring Boot
application loading configuration files from a "spring.config.name"
equal to the <literal>{application}</literal> parameter, and "spring.profiles.active"
equal to the <literal>{profiles}</literal> parameter. Precedence rules for profiles are
also the same as in a regular Boot application: active profiles take
precedence over defaults, and if there are multiple profiles the last
one wins (like adding entries to a <literal>Map</literal>).</simpara>
<simpara>Example: a client application has this bootstrap configuration:</simpara>
<formalpara>
<title>bootstrap.yml</title>
<para>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  application:
    name: foo
  profiles:
    active: dev,mysql</programlisting>
</para>
</formalpara>
<simpara>(as usual with a Spring Boot application, these properties could also
be set as environment variables or command line arguments).</simpara>
<simpara>If the repository is file-based, the server will create an
<literal>Environment</literal> from <literal>application.yml</literal> (shared between all clients), and
<literal>foo.yml</literal> (with <literal>foo.yml</literal> taking precedence). If the YAML files have
documents inside them that point to Spring profiles, those are applied
with higher precedence (in order of the profiles listed), and if
there are profile-specific YAML (or properties) files these are also
applied with higher precedence than the defaults. Higher precedence
translates to a <literal>PropertySource</literal> listed earlier in the
<literal>Environment</literal>. (These are the same rules as apply in a standalone
Spring Boot application.)</simpara>
<section xml:id="_git_backend">
<title>Git Backend</title>
<simpara>The default implementation of <literal>EnvironmentRepository</literal> uses a Git
backend, which is very convenient for managing upgrades and physical
environments, and also for auditing changes. To change the location of
the repository you can set the "spring.cloud.config.server.git.uri"
configuration property in the Config Server (e.g. in
<literal>application.yml</literal>). If you set it with a <literal>file:</literal> prefix it should work
from a local repository so you can get started quickly and easily
without a server, but in that case the server operates directly on the
local repository without cloning it (it doesn&#8217;t matter if it&#8217;s not
bare because the Config Server never makes changes to the "remote"
repository). To scale the Config Server up and make it highly
available, you would need to have all instances of the server pointing
to the same repository, so only a shared file system would work. Even
in that case it is better to use the <literal>ssh:</literal> protocol for a shared
filesystem repository, so that the server can clone it and use a local
working copy as a cache.</simpara>
<simpara>This repository implementation maps the <literal>{label}</literal> parameter of the
HTTP resource to a git label (commit id, branch name or tag). If the
git branch or tag name contains a slash ("/") then the label in the
HTTP URL should be specified with the special string "(_)" instead (to
avoid ambiguity with other URL paths).  For example, if the label is
<literal>foo/bar</literal>, replacing the slash would result in a label that looks like
<literal>foo(_)bar</literal>.  The inclusion of the special string "(_)" can also be
applied to the <literal>{application}</literal> parameter. Be careful with the brackets
in the URL if you are using a command line client like curl (e.g.
escape them from the shell with quotes '').</simpara>
<section xml:id="_placeholders_in_git_uri">
<title>Placeholders in Git URI</title>
<simpara>Spring Cloud Config Server supports a git repository URL with
placeholders for the <literal>{application}</literal> and <literal>{profile}</literal> (and <literal>{label}</literal> if
you need it, but remember that the label is applied as a git label
anyway). So you can easily support a "one repo per application" policy
using (for example):</simpara>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/myorg/{application}</programlisting>
<simpara>or a "one repo per profile" policy using a similar pattern but with
<literal>{profile}</literal>.</simpara>
<simpara>Additionally, using the special string "(_)" within your
<literal>{application}</literal> parameters can enable support for multiple
organizations (for example):</simpara>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/{application}</programlisting>
<simpara>where <literal>{application}</literal> is provided at request time in the format
"organization(_)application".</simpara>
</section>
<section xml:id="_pattern_matching_and_multiple_repositories">
<title>Pattern Matching and Multiple Repositories</title>
<simpara>There is also support for more complex requirements with pattern
matching on the application and profile name. The pattern format is a
comma-separated list of <literal>{application}/{profile}</literal> names with wildcards
(where a pattern beginning with a wildcard may need to be
quoted). Example:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          repos:
            simple: https://github.com/simple/config-repo
            special:
              pattern: special*/dev*,*special*/dev*
              uri: https://github.com/special/config-repo
            local:
              pattern: local*
              uri: file:/home/configsvc/config-repo</programlisting>
<simpara>If <literal>{application}/{profile}</literal> does not match any of the patterns, it
will use the default uri defined under
"spring.cloud.config.server.git.uri". In the above example, for the
"simple" repository, the pattern is <literal>simple/*</literal> (i.e. it only matches
one application named "simple" in all profiles). The "local"
repository matches all application names beginning with "local" in all
profiles (the <literal>/*</literal> suffix is added automatically to any pattern that
doesn&#8217;t have a profile matcher).</simpara>
<note>
<simpara>the "one-liner" short cut used in the "simple" example above can
only be used if the only property to be set is the URI. If you need to
set anything else (credentials, pattern, etc.) you need to use the full
form.</simpara>
</note>
<simpara>The <literal>pattern</literal> property in the repo is actually an array, so you can
use a YAML array (or <literal>[0]</literal>, <literal>[1]</literal>, etc. suffixes in properties files)
to bind to multiple patterns. You may need to do this if you are going
to run apps with multiple profiles. Example:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          repos:
            development:
              pattern:
                - '*/development'
                - '*/staging'
              uri: https://github.com/development/config-repo
            staging:
              pattern:
                - '*/qa'
                - '*/production'
              uri: https://github.com/staging/config-repo</programlisting>
<note>
<simpara>Spring Cloud will guess that a pattern containing a profile that
doesn&#8217;t end in <literal>*</literal> implies that you actually want to match a list of
profiles starting with this pattern (so <literal>*/staging</literal> is a shortcut for
<literal>["*/staging", "*/staging,*"]</literal>). This is common where you need to run
apps in the "development" profile locally but also the "cloud" profile
remotely, for instance.</simpara>
</note>
<simpara>Every repository can also optionally store config files in
sub-directories, and patterns to search for those directories can be
specified as <literal>searchPaths</literal>. For example at the top level:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          searchPaths: foo,bar*</programlisting>
<simpara>In this example the server searches for config files in the top level
and in the "foo/" sub-directory and also any sub-directory whose name
begins with "bar".</simpara>
<simpara>By default the server clones remote repositories when configuration
is first requested. The server can be configured to clone the repositories
at startup. For example at the top level:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
      server:
        git:
          uri: https://git/common/config-repo.git
          repos:
            team-a:
                pattern: team-a-*
                cloneOnStart: true
                uri: https://git/team-a/config-repo.git
            team-b:
                pattern: team-b-*
                cloneOnStart: false
                uri: https://git/team-b/config-repo.git
            team-c:
                pattern: team-c-*
                uri: https://git/team-a/config-repo.git</programlisting>
<simpara>In this example the server clones team-a&#8217;s config-repo on startup before it
accepts any requests. All other repositories will not be cloned until
configuration from the repository is requested.</simpara>
<note>
<simpara>Setting a repository to be cloned when the Config Server starts up can
help to identify a misconfigured configuration source (e.g., an invalid
repository URI) quickly, while the Config Server is starting up. With
<literal>cloneOnStart</literal> not enabled for a configuration source, the Config Server may
start successfully with a misconfigured or invalid configuration source and
not detect an error until an application requests configuration from that
configuration source.</simpara>
</note>
</section>
<section xml:id="_authentication">
<title>Authentication</title>
<simpara>To use HTTP basic authentication on the remote repository add the
"username" and "password" properties separately (not in the URL),
e.g.</simpara>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          username: trolley
          password: strongpassword</programlisting>
<simpara>If you don&#8217;t use HTTPS and user credentials, SSH should also work out
of the box when you store keys in the default directories (<literal>~/.ssh</literal>)
and the uri points to an SSH location,
e.g. "<link xl:href="mailto:git@github.com">git@github.com</link>:configuration/cloud-configuration". It is important that an entry for the Git server be present in the <literal>~/.ssh/known_hosts</literal> file and that it is in <literal>ssh-rsa</literal> format. Other formats (like <literal>ecdsa-sha2-nistp256</literal>) are not supported. To avoid surprises, you should ensure that only one entry is present in the <literal>known_hosts</literal> file for the Git server and that it is matching with the URL you provided to the config server. If you used a hostname in the URL, you want to have exactly that in the <literal>known_hosts</literal> file, not the IP.
The repository is accessed using JGit, so any documentation you find on
that should be applicable. HTTPS proxy settings can be set in
<literal>~/.git/config</literal> or in the same way as for any other JVM process via
system properties (<literal>-Dhttps.proxyHost</literal> and <literal>-Dhttps.proxyPort</literal>).</simpara>
<tip>
<simpara>If you don&#8217;t know where your <literal>~/.git</literal> directory is use <literal>git config
--global</literal> to manipulate the settings (e.g. <literal>git config --global
http.sslVerify false</literal>).</simpara>
</tip>
</section>
<section xml:id="_authentication_with_aws_codecommit">
<title>Authentication with AWS CodeCommit</title>
<simpara><link xl:href="https://docs.aws.amazon.com/codecommit/latest/userguide/welcome.html">AWS CodeCommit</link> authentication can also be
done. AWS CodeCommit uses an authentication helper when using Git from the command line. This helper is not
used with the JGit library, so a JGit CredentialProvider for AWS CodeCommit will be created if the Git
URI matches the AWS CodeCommit pattern. AWS CodeCommit URIs always look like
<link xl:href="https://git-codecommit.${AWS_REGION}.amazonaws.com/${repopath}">https://git-codecommit.${AWS_REGION}.amazonaws.com/${repopath}</link>.</simpara>
<simpara>If you provide a username and password with an AWS CodeCommit URI, then these must be
the <link xl:href="https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSGettingStartedGuide/AWSCredentials.html">AWS accessKeyId and secretAccessKey</link>
to be used to access the repository. If you do not specify a username and password,
then the accessKeyId and secretAccessKey will be retrieved using the
<link xl:href="https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html">AWS Default Credential Provider Chain</link>.</simpara>
<simpara>If your Git URI matches the CodeCommit URI pattern (above) then you must provide
valid AWS credentials in the username and password, or in one of the locations supported
by the default credential provider chain. AWS EC2 instances may use
<link xl:href="https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html">IAM Roles for EC2 Instances</link>.</simpara>
<simpara>Note: The aws-java-sdk-core jar is an optional dependency. If the aws-java-sdk-core jar is not on your
classpath, then the AWS Code Commit credential provider will not be created regardless of the git server URI.</simpara>
</section>
<section xml:id="_git_ssh_configuration_using_properties">
<title>Git SSH configuration using properties</title>
<simpara>By default, the JGit library used by Spring Cloud Config Server uses SSH configuration files such as <literal>~/.ssh/known_hosts</literal> and <literal>/etc/ssh/ssh_config</literal> when connecting to Git repositories using an SSH URI.
In cloud environments such as Cloud Foundry, the local filesystem may be ephemeral or not easily accessible. For cases such as these, SSH configuration can be set using
Java properties. In order to activate property based SSH configuration, the property <literal>spring.cloud.config.server.git.ignoreLocalSshSettings</literal> must be set to <literal>true</literal>.
Example:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">  spring:
    cloud:
      config:
        server:
          git:
            uri: git@gitserver.com:team/repo1.git
            ignoreLocalSshSettings: true
            hostKey: someHostKey
            hostKeyAlgorithm: ssh-rsa
            privateKey: |
                         -----BEGIN RSA PRIVATE KEY-----
                         MIIEpgIBAAKCAQEAx4UbaDzY5xjW6hc9jwN0mX33XpTDVW9WqHp5AKaRbtAC3DqX
                         IXFMPgw3K45jxRb93f8tv9vL3rD9CUG1Gv4FM+o7ds7FRES5RTjv2RT/JVNJCoqF
                         ol8+ngLqRZCyBtQN7zYByWMRirPGoDUqdPYrj2yq+ObBBNhg5N+hOwKjjpzdj2Ud
                         1l7R+wxIqmJo1IYyy16xS8WsjyQuyC0lL456qkd5BDZ0Ag8j2X9H9D5220Ln7s9i
                         oezTipXipS7p7Jekf3Ywx6abJwOmB0rX79dV4qiNcGgzATnG1PkXxqt76VhcGa0W
                         DDVHEEYGbSQ6hIGSh0I7BQun0aLRZojfE3gqHQIDAQABAoIBAQCZmGrk8BK6tXCd
                         fY6yTiKxFzwb38IQP0ojIUWNrq0+9Xt+NsypviLHkXfXXCKKU4zUHeIGVRq5MN9b
                         BO56/RrcQHHOoJdUWuOV2qMqJvPUtC0CpGkD+valhfD75MxoXU7s3FK7yjxy3rsG
                         EmfA6tHV8/4a5umo5TqSd2YTm5B19AhRqiuUVI1wTB41DjULUGiMYrnYrhzQlVvj
                         5MjnKTlYu3V8PoYDfv1GmxPPh6vlpafXEeEYN8VB97e5x3DGHjZ5UrurAmTLTdO8
                         +AahyoKsIY612TkkQthJlt7FJAwnCGMgY6podzzvzICLFmmTXYiZ/28I4BX/mOSe
                         pZVnfRixAoGBAO6Uiwt40/PKs53mCEWngslSCsh9oGAaLTf/XdvMns5VmuyyAyKG
                         ti8Ol5wqBMi4GIUzjbgUvSUt+IowIrG3f5tN85wpjQ1UGVcpTnl5Qo9xaS1PFScQ
                         xrtWZ9eNj2TsIAMp/svJsyGG3OibxfnuAIpSXNQiJPwRlW3irzpGgVx/AoGBANYW
                         dnhshUcEHMJi3aXwR12OTDnaLoanVGLwLnkqLSYUZA7ZegpKq90UAuBdcEfgdpyi
                         PhKpeaeIiAaNnFo8m9aoTKr+7I6/uMTlwrVnfrsVTZv3orxjwQV20YIBCVRKD1uX
                         VhE0ozPZxwwKSPAFocpyWpGHGreGF1AIYBE9UBtjAoGBAI8bfPgJpyFyMiGBjO6z
                         FwlJc/xlFqDusrcHL7abW5qq0L4v3R+FrJw3ZYufzLTVcKfdj6GelwJJO+8wBm+R
                         gTKYJItEhT48duLIfTDyIpHGVm9+I1MGhh5zKuCqIhxIYr9jHloBB7kRm0rPvYY4
                         VAykcNgyDvtAVODP+4m6JvhjAoGBALbtTqErKN47V0+JJpapLnF0KxGrqeGIjIRV
                         cYA6V4WYGr7NeIfesecfOC356PyhgPfpcVyEztwlvwTKb3RzIT1TZN8fH4YBr6Ee
                         KTbTjefRFhVUjQqnucAvfGi29f+9oE3Ei9f7wA+H35ocF6JvTYUsHNMIO/3gZ38N
                         CPjyCMa9AoGBAMhsITNe3QcbsXAbdUR00dDsIFVROzyFJ2m40i4KCRM35bC/BIBs
                         q0TY3we+ERB40U8Z2BvU61QuwaunJ2+uGadHo58VSVdggqAo0BSkH58innKKt96J
                         69pcVH/4rmLbXdcmNYGm6iu+MlPQk4BUZknHSmVHIFdJ0EPupVaQ8RHT
                         -----END RSA PRIVATE KEY-----</programlisting>
<table frame="all" rowsep="1" colsep="1">
<title>SSH Configuration properties</title>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Property Name</entry>
<entry align="left" valign="top">Remarks</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara><emphasis role="strong">ignoreLocalSshSettings</emphasis></simpara></entry>
<entry align="left" valign="top"><simpara>If true, use property based SSH config instead of file based. Must be set at as <literal>spring.cloud.config.server.git.ignoreLocalSshSettings</literal>, <emphasis role="strong">not</emphasis> inside a repository definition.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara><emphasis role="strong">privateKey</emphasis></simpara></entry>
<entry align="left" valign="top"><simpara>Valid SSH private key. Must be set if <literal>ignoreLocalSshSettings</literal> is true and Git URI is SSH format</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara><emphasis role="strong">hostKey</emphasis></simpara></entry>
<entry align="left" valign="top"><simpara>Valid SSH host key. Must be set if <literal>hostKeyAlgorithm</literal> is also set</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara><emphasis role="strong">hostKeyAlgorithm</emphasis></simpara></entry>
<entry align="left" valign="top"><simpara>One of <literal>ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384 ,ecdsa-sha2-nistp521</literal>. Must be set if <literal>hostKey</literal> is also set</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara><emphasis role="strong">proxyHost</emphasis></simpara></entry>
<entry align="left" valign="top"><simpara>Hostname for the ssh proxy connection. Is optional and used only when <literal>ignoreLocalSshSettings</literal> is true</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara><emphasis role="strong">proxyPort</emphasis></simpara></entry>
<entry align="left" valign="top"><simpara>Port for the ssh proxy connection. Must be set if <literal>proxyHost</literal> is also set</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara><emphasis role="strong">strictHostKeyChecking</emphasis></simpara></entry>
<entry align="left" valign="top"><simpara><literal>true</literal> or <literal>false</literal>. If false, ignore errors with host key</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara><emphasis role="strong">knownHostsFile</emphasis></simpara></entry>
<entry align="left" valign="top"><simpara>Location of custom .known_hosts file</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara><emphasis role="strong">preferredAuthentications</emphasis></simpara></entry>
<entry align="left" valign="top"><simpara>Override server authentication method order. This should allow evade login prompts if server has keyboard-interactive authentication before <literal>publickey</literal> method.</simpara></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="_placeholders_in_git_search_paths">
<title>Placeholders in Git Search Paths</title>
<simpara>Spring Cloud Config Server also supports a search path with
placeholders for the <literal>{application}</literal> and <literal>{profile}</literal> (and <literal>{label}</literal> if
you need it). Example:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          searchPaths: '{application}'</programlisting>
<simpara>searches the repository for files in the same name as the directory
(as well as the top level). Wildcards are also valid in a search
path with placeholders (any matching directory is included in the
search).</simpara>
</section>
<section xml:id="_force_pull_in_git_repositories">
<title>Force pull in Git Repositories</title>
<simpara>As mentioned before Spring Cloud Config Server makes a clone of the
remote git repository and if somehow the local copy gets dirty (e.g.
folder content changes by OS process) so Spring Cloud Config Server
cannot update the local copy from remote repository.</simpara>
<simpara>To solve this there is a <literal>force-pull</literal> property that will make Spring Cloud
Config Server force pull from remote repository if the local copy is dirty.
Example:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          force-pull: true</programlisting>
<simpara>If you have a multiple repositories configuration you can configure the
<literal>force-pull</literal> property per repository. Example:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
      server:
        git:
          uri: https://git/common/config-repo.git
          force-pull: true
          repos:
            team-a:
                pattern: team-a-*
                uri: https://git/team-a/config-repo.git
                force-pull: true
            team-b:
                pattern: team-b-*
                uri: https://git/team-b/config-repo.git
                force-pull: true
            team-c:
                pattern: team-c-*
                uri: https://git/team-a/config-repo.git</programlisting>
<note>
<simpara>The default value for <literal>force-pull</literal> property is <literal>false</literal>.</simpara>
</note>
</section>
<section xml:id="_deleting_untracked_branches_in_git_repositories">
<title>Deleting untracked branches in Git Repositories</title>
<simpara>As Spring Cloud Config Server has a clone of the remote git repository
after check-outing branch to local repo (e.g fetching properties by label) it will keep this branch
forever or till the next server restart (which creates new local repo).
So there could be a case when remote branch is deleted but local copy of it is still available for fetching.
And if Spring Cloud Config Server client service starts with <literal>--spring.cloud.config.label=deletedRemoteBranch,master</literal>
it will fetch properties from <literal>deletedRemoteBranch</literal> local branch, but not from <literal>master</literal>.</simpara>
<simpara>In order to keep local repository branches clean and up to remote - <literal>deleteUntrackedBranches</literal> property could be set.
It will make Spring Cloud Config Server <emphasis role="strong">force</emphasis> delete untracked branches from local repository.
Example:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          deleteUntrackedBranches: true</programlisting>
<note>
<simpara>The default value for <literal>deleteUntrackedBranches</literal> property is <literal>false</literal>.</simpara>
</note>
</section>
</section>
<section xml:id="_version_control_backend_filesystem_use">
<title>Version Control Backend Filesystem Use</title>
<warning>
<simpara>With VCS based backends (git, svn) files are checked out or cloned to the local filesystem. By default they are put in the system temporary directory with a prefix of <literal>config-repo-</literal>. On linux, for example it could be <literal>/tmp/config-repo-&lt;randomid&gt;</literal>. Some operating systems <link xl:href="https://serverfault.com/questions/377348/when-does-tmp-get-cleared/377349#377349">routinely clean out</link> temporary directories. This can lead to unexpected behaviour such as missing properties. To avoid this problem, change the directory Config Server uses, by setting <literal>spring.cloud.config.server.git.basedir</literal> or <literal>spring.cloud.config.server.svn.basedir</literal> to a directory that does not reside in the system temp structure.</simpara>
</warning>
</section>
<section xml:id="_file_system_backend">
<title>File System Backend</title>
<simpara>There is also a "native" profile in the Config Server that doesn&#8217;t use
Git, but just loads the config files from the local classpath or file
system (any static URL you want to point to with
"spring.cloud.config.server.native.searchLocations"). To use the
native profile just launch the Config Server with
"spring.profiles.active=native".</simpara>
<note>
<simpara>Remember to use the <literal>file:</literal> prefix for file resources (the
default without a prefix is usually the classpath). Just as with any
Spring Boot configuration you can embed <literal>${}</literal>-style environment
placeholders, but remember that absolute paths in Windows require an
extra "/", e.g. <literal><link xl:href="file:///${user.home}/config-repo">file:///${user.home}/config-repo</link></literal></simpara>
</note>
<warning>
<simpara>The default value of the <literal>searchLocations</literal> is identical to a
local Spring Boot application (so <literal>[classpath:/, classpath:/config,
file:./, file:./config]</literal>). This does not expose the
<literal>application.properties</literal> from the server to all clients because any
property sources present in the server are removed before being sent
to the client.</simpara>
</warning>
<tip>
<simpara>A filesystem backend is great for getting started quickly and
for testing. To use it in production you need to be sure that the
file system is reliable, and shared across all instances of the
Config Server.</simpara>
</tip>
<simpara>The search locations can contain placeholders for <literal>{application}</literal>,
<literal>{profile}</literal> and <literal>{label}</literal>. In this way you can segregate the
directories in the path, and choose a strategy that makes sense for
you (e.g. sub-directory per application, or sub-directory per
profile).</simpara>
<simpara>If you don&#8217;t use placeholders in the search locations, this repository
also appends the <literal>{label}</literal> parameter of the HTTP resource to a suffix
on the search path, so properties files are loaded from each search
location <emphasis role="strong">and</emphasis> a subdirectory with the same name as the label (the
labelled properties take precedence in the Spring Environment). Thus
the default behaviour with no placeholders is the same as adding a
search location ending with <literal>/{label}/</literal>. For example <literal>file:/tmp/config</literal>
is the same as <literal>file:/tmp/config,file:/tmp/config/{label}</literal>. This behavior can be
disabled by setting <literal>spring.cloud.config.server.native.addLabelLocations=false</literal>.</simpara>
</section>
<section xml:id="_vault_backend">
<title>Vault Backend</title>
<simpara>Spring Cloud Config Server also supports <link xl:href="https://www.vaultproject.io">Vault</link> as a backend.</simpara>
<sidebar>
<simpara>Vault is a tool for securely accessing secrets. A secret is anything
that you want to tightly control access to, such as API keys, passwords,
certificates, and more. Vault provides a unified interface to any secret,
while providing tight access control and recording a detailed audit log.</simpara>
</sidebar>
<simpara>For more information on Vault see the <link xl:href="https://www.vaultproject.io/intro/index.html">Vault quickstart guide</link>.</simpara>
<simpara>To enable the config server to use a Vault backend you can run your config server
with the <literal>vault</literal> profile.  For example in your config server&#8217;s <literal>application.properties</literal>
you can add <literal>spring.profiles.active=vault</literal>.</simpara>
<simpara>By default the config server will assume your Vault server is running at
<literal><link xl:href="http://127.0.0.1:8200">http://127.0.0.1:8200</link></literal>.  It also will assume that the name of backend
is <literal>secret</literal> and the key is <literal>application</literal>.  All of these defaults can be
configured in your config server&#8217;s <literal>application.properties</literal>.  Below is a
table of configurable Vault properties.  All properties are prefixed with
<literal>spring.cloud.config.server.vault</literal>.</simpara>
<informaltable frame="all" rowsep="1" colsep="1">
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Name</entry>
<entry align="left" valign="top">Default Value</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>host</simpara></entry>
<entry align="left" valign="top"><simpara>127.0.0.1</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>port</simpara></entry>
<entry align="left" valign="top"><simpara>8200</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>scheme</simpara></entry>
<entry align="left" valign="top"><simpara>http</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>backend</simpara></entry>
<entry align="left" valign="top"><simpara>secret</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>defaultKey</simpara></entry>
<entry align="left" valign="top"><simpara>application</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>profileSeparator</simpara></entry>
<entry align="left" valign="top"><simpara>,</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<simpara>All configurable properties can be found in
<literal>org.springframework.cloud.config.server.environment.VaultEnvironmentRepository</literal>.</simpara>
<simpara>With your config server running you can make HTTP requests to the server to retrieve
values from the Vault backend.  To do this you will need a token for your Vault server.</simpara>
<simpara>First place some data in you Vault.  For example</simpara>
<programlisting language="sh" linenumbering="unnumbered">$ vault write secret/application foo=bar baz=bam
$ vault write secret/myapp foo=myappsbar</programlisting>
<simpara>Now make the HTTP request to your config server to retrieve the values.</simpara>
<simpara><literal>$ curl -X "GET" "http://localhost:8888/myapp/default" -H "X-Config-Token: yourtoken"</literal></simpara>
<simpara>You should see a response similar to this after making the above request.</simpara>
<programlisting language="json" linenumbering="unnumbered">{
   "name":"myapp",
   "profiles":[
      "default"
   ],
   "label":null,
   "version":null,
   "state":null,
   "propertySources":[
      {
         "name":"vault:myapp",
         "source":{
            "foo":"myappsbar"
         }
      },
      {
         "name":"vault:application",
         "source":{
            "baz":"bam",
            "foo":"bar"
         }
      }
   ]
}</programlisting>
<section xml:id="_multiple_properties_sources">
<title>Multiple Properties Sources</title>
<simpara>When using Vault you can provide your applications with multiple properties sources.
For example, assume you have written data to the following paths in Vault.</simpara>
<programlisting language="sh" linenumbering="unnumbered">secret/myApp,dev
secret/myApp
secret/application,dev
secret/application</programlisting>
<simpara>Properties written to <literal>secret/application</literal> are available to
<link linkend="_vault_server">all applications using the Config Server</link>.  An
application with the name <literal>myApp</literal> would have any properties
written to <literal>secret/myApp</literal> and <literal>secret/application</literal> available to it.
When <literal>myApp</literal> has the <literal>dev</literal> profile enabled then properties written to
all of the above paths would be available to it, with properties in
the first path in the list taking priority over the others.</simpara>
</section>
</section>
<section xml:id="_sharing_configuration_with_all_applications">
<title>Sharing Configuration With All Applications</title>
<section xml:id="_file_based_repositories">
<title>File Based Repositories</title>
<simpara>With file-based (i.e. git, svn and native) repositories, resources
with file names in <literal>application*</literal> are shared between all client
applications (so <literal>application.properties</literal>, <literal>application.yml</literal>,
<literal>application-*.properties</literal> etc.). You can use resources with these
file names to configure global defaults and have them overridden by
application-specific files as necessary.</simpara>
<simpara>The #_property_overrides[property overrides] feature can also be used
for setting global defaults, and with placeholders applications are
allowed to override them locally.</simpara>
<tip>
<simpara>With the "native" profile (local file system backend) it is
recommended that you use an explicit search location that isn&#8217;t part
of the server&#8217;s own configuration. Otherwise the <literal>application*</literal>
resources in the default search locations are removed because they are
part of the server.</simpara>
</tip>
</section>
<section xml:id="_vault_server">
<title>Vault Server</title>
<simpara>When using Vault as a backend you can share configuration with
all applications by placing configuration in
<literal>secret/application</literal>.  For example, if you run this Vault command</simpara>
<programlisting language="sh" linenumbering="unnumbered">$ vault write secret/application foo=bar baz=bam</programlisting>
<simpara>All applications using the config server will have the properties
<literal>foo</literal> and <literal>baz</literal> available to them.</simpara>
</section>
</section>
<section xml:id="_jdbc_backend">
<title>JDBC Backend</title>
<simpara>Spring Cloud Config Server supports JDBC (relation database) as a
backend for configuration properties. You can enable this feature by
adding <literal>spring-jdbc</literal> to the classpath, and using the "jdbc" profile,
or by adding a bean of type <literal>JdbcEnvironmentRepository</literal>. Spring Boot
will configure a data source if you include the right dependencies on
the classpath (see the user guide for more details on that).</simpara>
<simpara>The database needs to have a table called "PROPERTIES" with columns
"APPLICATION", "PROFILE", "LABEL" (with the usual <literal>Environment</literal>
meaning), plus "KEY" and "VALUE" for the key and value pairs in
<literal>Properties</literal> style. All fields are of type String in Java, so you can
make them <literal>VARCHAR</literal> of whatever length you need. Property values
behave in the same way as they would if they came from Spring Boot
properties files named <literal>{application}-{profile}.properties</literal>, including
all the encryption and decryption, which will be applied as
post-processing steps (i.e. not in the repository implementation
directly).</simpara>
</section>
<section xml:id="_composite_environment_repositories">
<title>Composite Environment Repositories</title>
<simpara>In some scenarios you may wish to pull configuration data from multiple
environment repositories.  To do this you can just enable
multiple profiles in your config server&#8217;s application properties or YAML file.
If, for example, you want to pull configuration data from a Git repository
as well as a SVN repository you would set the following properties for your
configuration server.</simpara>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  profiles:
    active: git, svn
  cloud:
    config:
      server:
        svn:
          uri: file:///path/to/svn/repo
          order: 2
        git:
          uri: file:///path/to/git/repo
          order: 1</programlisting>
<simpara>In addition to each repo specifying a URI, you can also specify an <literal>order</literal> property.
The <literal>order</literal> property allows you to specify the priority order for all your repositories.
The lower the numerical value of the <literal>order</literal> property the higher priority it will have.
The priority order of a repository will help resolve any potential conflicts between
repositories that contain values for the same properties.</simpara>
<note>
<simpara>Any type of failure when retrieving values from an environment repositoy
will result in a failure for the entire composite environment.</simpara>
</note>
<note>
<simpara>When using a composite environment it is important that all repos contain
the same label(s).  If you have an environment similar to the one above and you request
configuration data with the label <literal>master</literal> but the SVN
repo does not contain a branch called <literal>master</literal> the entire request will fail.</simpara>
</note>
<section xml:id="_custom_composite_environment_repositories">
<title>Custom Composite Environment Repositories</title>
<simpara>It is also possible to provide your own <literal>EnvironmentRepository</literal> bean
to be included as part of a composite environment in addition to
using one of the environment repositories from Spring Cloud.  To do this your bean
must implement the <literal>EnvironmentRepository</literal> interface.  If you would like to control
the priority of you custom <literal>EnvironmentRepository</literal> within the composite
environment you should also implement the <literal>Ordered</literal> interface and override the
<literal>getOrdered</literal> method.  If you do not implement the <literal>Ordered</literal> interface then your
<literal>EnvironmentRepository</literal> will be given the lowest priority.</simpara>
</section>
</section>
<section xml:id="_property_overrides">
<title>Property Overrides</title>
<simpara>The Config Server has an "overrides" feature that allows the operator
to provide configuration properties to all applications that cannot be
accidentally changed by the application using the normal Spring Boot
hooks. To declare overrides just add a map of name-value pairs to
<literal>spring.cloud.config.server.overrides</literal>. For example</simpara>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
      server:
        overrides:
          foo: bar</programlisting>
<simpara>will cause all applications that are config clients to read <literal>foo=bar</literal>
independent of their own configuration. (Of course an application can
use the data in the Config Server in any way it likes, so overrides
are not enforceable, but they do provide useful default behaviour if
they are Spring Cloud Config clients.)</simpara>
<tip>
<simpara>Normal, Spring environment placeholders with "${}" can be escaped
(and resolved on the client) by using backslash ("\") to escape the
"$" or the "{", e.g. <literal>\${app.foo:bar}</literal> resolves to "bar" unless the
app provides its own "app.foo". Note that in YAML you don&#8217;t need to
escape the backslash itself, but in properties files you do, when you
configure the overrides on the server.</simpara>
</tip>
<simpara>You can change the priority of all overrides in the client to be more
like default values, allowing applications to supply their own values
in environment variables or System properties, by setting the flag
<literal>spring.cloud.config.overrideNone=true</literal> (default is false) in the
remote repository.</simpara>
</section>
</section>
<section xml:id="_health_indicator">
<title>Health Indicator</title>
<simpara>Config Server comes with a Health Indicator that checks if the configured
<literal>EnvironmentRepository</literal> is working.  By default it asks the <literal>EnvironmentRepository</literal>
for an application named <literal>app</literal>, the <literal>default</literal> profile and the default
label provided by the <literal>EnvironmentRepository</literal> implementation.</simpara>
<simpara>You can configure the Health Indicator to check more applications
along with custom profiles and custom labels, e.g.</simpara>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
      server:
        health:
          repositories:
            myservice:
              label: mylabel
            myservice-dev:
              name: myservice
              profiles: development</programlisting>
<simpara>You can disable the Health Indicator by setting <literal>spring.cloud.config.server.health.enabled=false</literal>.</simpara>
</section>
<section xml:id="_security">
<title>Security</title>
<simpara>You are free to secure your Config Server in any way that makes sense
to you (from physical network security to OAuth2 bearer
tokens), and Spring Security and Spring Boot make it easy to do pretty
much anything.</simpara>
<simpara>To use the default Spring Boot configured HTTP Basic security, just
include Spring Security on the classpath (e.g. through
<literal>spring-boot-starter-security</literal>). The default is a username of "user"
and a randomly generated password, which isn&#8217;t going to be very useful
in practice, so we recommend you configure the password (via
<literal>security.user.password</literal>) and encrypt it (see below for instructions
on how to do that).</simpara>
</section>
<section xml:id="_encryption_and_decryption">
<title>Encryption and Decryption</title>
<important>
<simpara><emphasis role="strong">Prerequisites:</emphasis> to use the encryption and decryption features
you need the full-strength JCE installed in your JVM (it&#8217;s not there by default).
You can download the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files"
from Oracle, and follow instructions for installation (essentially replace the 2 policy files
in the JRE lib/security directory with the ones that you downloaded).</simpara>
</important>
<simpara>If the remote property sources contain encrypted content (values
starting with <literal>{cipher}</literal>) they will be decrypted before sending to
clients over HTTP. The main advantage of this set up is that the
property values don&#8217;t have to be in plain text when they are "at rest"
(e.g. in a git repository). If a value cannot be decrypted it is
removed from the property source and an additional property is added
with the same key, but prefixed with "invalid." and a value that means
"not applicable" (usually "&lt;n/a&gt;"). This is largely to prevent cipher
text being used as a password and accidentally leaking.</simpara>
<simpara>If you are setting up a remote config repository for config client
applications it might contain an <literal>application.yml</literal> like this, for
instance:</simpara>
<formalpara>
<title>application.yml</title>
<para>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  datasource:
    username: dbuser
    password: '{cipher}FKSAJDFGYOS8F7GLHAKERGFHLSAJ'</programlisting>
</para>
</formalpara>
<simpara>Encrypted values in a .properties file must not be wrapped in quotes, otherwise the value will not be decrypted:</simpara>
<formalpara>
<title>application.properties</title>
<para>
<screen>spring.datasource.username: dbuser
spring.datasource.password: {cipher}FKSAJDFGYOS8F7GLHAKERGFHLSAJ</screen>
</para>
</formalpara>
<simpara>You can safely push this plain text to a shared git repository and the
secret password is protected.</simpara>
<simpara>The server also exposes <literal>/encrypt</literal> and <literal>/decrypt</literal> endpoints (on the
assumption that these will be secured and only accessed by authorized
agents). If you are editing a remote config file you can use the Config Server
to encrypt values by POSTing to the <literal>/encrypt</literal> endpoint, e.g.</simpara>
<screen>$ curl localhost:8888/encrypt -d mysecret
682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda</screen>
<note>
<simpara>If the value you are encrypting has characters in it that need to be URL encoded you should use
the <literal>--data-urlencode</literal> option to <literal>curl</literal> to make sure they are encoded properly.</simpara>
</note>
<tip>
<simpara>Be sure not to include any of the curl command statistics in the encrypted value.
Outputting the value to a file can help avoid this problem.</simpara>
</tip>
<simpara>The inverse operation is also available via <literal>/decrypt</literal> (provided the server is
configured with a symmetric key or a full key pair):</simpara>
<screen>$ curl localhost:8888/decrypt -d 682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
mysecret</screen>
<tip>
<simpara>If you are testing like this with curl, then use
<literal>--data-urlencode</literal> (instead of <literal>-d</literal>) or set an explicit <literal>Content-Type:
text/plain</literal> to make sure curl encodes the data correctly when there
are special characters ('+' is particularly tricky).</simpara>
</tip>
<simpara>Take the encrypted value and add the <literal>{cipher}</literal> prefix before you put
it in the YAML or properties file, and before you commit and push it
to a remote, potentially insecure store.</simpara>
<simpara>The <literal>/encrypt</literal> and <literal>/decrypt</literal> endpoints also both accept paths of the
form <literal>/*/{name}/{profiles}</literal> which can be used to control cryptography
per application (name) and profile when clients call into the main
Environment resource.</simpara>
<note>
<simpara>to control the cryptography in this granular way you must also
provide a <literal>@Bean</literal> of type <literal>TextEncryptorLocator</literal> that creates a
different encryptor per name and profiles. The one that is provided
by default does not do this (so all encryptions use the same key).</simpara>
</note>
<simpara>The <literal>spring</literal> command line client (with Spring Cloud CLI extensions
installed) can also be used to encrypt and decrypt, e.g.</simpara>
<screen>$ spring encrypt mysecret --key foo
682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
$ spring decrypt --key foo 682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
mysecret</screen>
<simpara>To use a key in a file (e.g. an RSA public key for encryption) prepend
the key value with "@" and provide the file path, e.g.</simpara>
<screen>$ spring encrypt mysecret --key @${HOME}/.ssh/id_rsa.pub
AQAjPgt3eFZQXwt8tsHAVv/QHiY5sI2dRcR+...</screen>
<simpara>The key argument is mandatory (despite having a <literal>--</literal> prefix).</simpara>
</section>
<section xml:id="_key_management">
<title>Key Management</title>
<simpara>The Config Server can use a symmetric (shared) key or an asymmetric
one (RSA key pair). The asymmetric choice is superior in terms of
security, but it is often more convenient to use a symmetric key since
it is just a single property value to configure in the <literal>bootstrap.properties</literal>.</simpara>
<simpara>To configure a symmetric key you just need to set <literal>encrypt.key</literal> to a
secret String (or use an enviroment variable <literal>ENCRYPT_KEY</literal> to keep it
out of plain text configuration files).</simpara>
<note>
<simpara>You cannot configure an asymmetric key using <literal>encrypt.key</literal>.</simpara>
</note>
<simpara>To configure an asymmetric key use a keystore (e.g. as
created by the <literal>keytool</literal> utility that comes with the JDK). The
keystore properties are <literal>encrypt.keyStore.*</literal> with <literal>*</literal> equal to</simpara>
<itemizedlist>
<listitem>
<simpara><literal>location</literal> (a <literal>Resource</literal> location),</simpara>
</listitem>
<listitem>
<simpara><literal>password</literal> (to unlock the keystore) and</simpara>
</listitem>
<listitem>
<simpara><literal>alias</literal> (to identify which key in the store is to be
used).</simpara>
</listitem>
</itemizedlist>
<simpara>The encryption is done with the public key, and a private key is
needed for decryption. Thus in principle you can configure only the
public key in the server if you only want to do encryption (and are
prepared to decrypt the values yourself locally with the private
key). In practice you might not want to do that because it spreads the
key management process around all the clients, instead of
concentrating it in the server. On the other hand it&#8217;s a useful option
if your config server really is relatively insecure and only a
handful of clients need the encrypted properties.</simpara>
</section>
<section xml:id="_creating_a_key_store_for_testing">
<title>Creating a Key Store for Testing</title>
<simpara>To create a keystore for testing you can do something like this:</simpara>
<screen>$ keytool -genkeypair -alias mytestkey -keyalg RSA \
  -dname "CN=Web Server,OU=Unit,O=Organization,L=City,S=State,C=US" \
  -keypass changeme -keystore server.jks -storepass letmein</screen>
<simpara>Put the <literal>server.jks</literal> file in the classpath (for instance) and then in
your <literal>bootstrap.yml</literal> for the Config Server:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">encrypt:
  keyStore:
    location: classpath:/server.jks
    password: letmein
    alias: mytestkey
    secret: changeme</programlisting>
</section>
<section xml:id="_using_multiple_keys_and_key_rotation">
<title>Using Multiple Keys and Key Rotation</title>
<simpara>In addition to the <literal>{cipher}</literal> prefix in encrypted property values, the
Config Server looks for <literal>{name:value}</literal> prefixes (zero or many) before
the start of the (Base64 encoded) cipher text. The keys are passed to
a <literal>TextEncryptorLocator</literal> which can do whatever logic it needs to
locate a <literal>TextEncryptor</literal> for the cipher. If you have configured a
keystore (<literal>encrypt.keystore.location</literal>) the default locator will look
for keys in the store with aliases as supplied by the "key" prefix,
i.e. with a cipher text like this:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">foo:
  bar: `{cipher}{key:testkey}...`</programlisting>
<simpara>the locator will look for a key named "testkey". A secret can also be
supplied via a <literal>{secret:&#8230;&#8203;}</literal> value in the prefix, but if it is not
the default is to use the keystore password (which is what you get
when you build a keytore and don&#8217;t specify a secret). If you <emphasis role="strong">do</emphasis>
supply a secret it is recommended that you also encrypt the secrets
using a custom <literal>SecretLocator</literal>.</simpara>
<simpara>Key rotation is hardly ever necessary on cryptographic grounds if the
keys are only being used to encrypt a few bytes of configuration data
(i.e. they are not being used elsewhere), but occasionally you might
need to change the keys if there is a security breach for instance. In
that case all the clients would need to change their source config
files (e.g. in git) and use a new <literal>{key:&#8230;&#8203;}</literal> prefix in all the
ciphers, checking beforehand of course that the key alias is available
in the Config Server keystore.</simpara>
<tip>
<simpara>the <literal>{name:value}</literal> prefixes can also be added to plaintext posted
to the <literal>/encrypt</literal> endpoint, if you want to let the Config Server
handle all encryption as well as decryption.</simpara>
</tip>
</section>
<section xml:id="_serving_encrypted_properties">
<title>Serving Encrypted Properties</title>
<simpara>Sometimes you want the clients to decrypt the configuration locally,
instead of doing it in the server. In that case you can still have
/encrypt and /decrypt endpoints (if you provide the <literal>encrypt.*</literal>
configuration to locate a key), but you need to explicitly switch off
the decryption of outgoing properties by placing
<literal>spring.cloud.config.server.encrypt.enabled=false</literal> in <literal>bootstrap.[yml|properties]</literal>.
If you don&#8217;t care about the endpoints, then it should work if you configure neither the
key nor the enabled flag.</simpara>
</section>
</chapter>
<chapter xml:id="_serving_alternative_formats">
<title>Serving Alternative Formats</title>
<simpara>The default JSON format from the environment endpoints is perfect for
consumption by Spring applications because it maps directly onto the
<literal>Environment</literal> abstraction. If you prefer you can consume the same data
as YAML or Java properties by adding a suffix to the resource path
(".yml", ".yaml" or ".properties"). This can be useful for consumption
by applications that do not care about the structure of the JSON
endpoints, or the extra metadata they provide, for example an
application that is not using Spring might benefit from the simplicity
of this approach.</simpara>
<simpara>The YAML and properties representations have an additional flag
(provided as a boolean query parameter <literal>resolvePlaceholders</literal>) to
signal that placeholders in the source documents, in the standard
Spring <literal>${&#8230;&#8203;}</literal> form, should be resolved in the output where possible
before rendering. This is a useful feature for consumers that don&#8217;t
know about the Spring placeholder conventions.</simpara>
<note>
<simpara>there are limitations in using the YAML or properties formats,
mainly in relation to the loss of metadata. The JSON is structured as
an ordered list of property sources, for example, with names that
correlate with the source. The YAML and properties forms are coalesced
into a single map, even if the origin of the values has multiple
sources, and the names of the original source files are lost. The YAML
representation is not necessarily a faithful representation of the
YAML source in a backing repository either: it is constructed from a
list of flat property sources, and assumptions have to be made about
the form of the keys.</simpara>
</note>
</chapter>
<chapter xml:id="_serving_plain_text">
<title>Serving Plain Text</title>
<simpara>Instead of using the <literal>Environment</literal> abstraction (or one of the
alternative representations of it in YAML or properties format) your
applications might need generic plain text configuration files,
tailored to their environment. The Config Server provides these
through an additional endpoint at <literal>/{name}/{profile}/{label}/{path}</literal>
where "name", "profile" and "label" have the same meaning as the
regular environment endpoint, but "path" is a file name
(e.g. <literal>log.xml</literal>). The source files for this endpoint are located in
the same way as for the environment endpoints: the same search path is
used as for properties or YAML files, but instead of aggregating all
matching resources, only the first one to match is returned.</simpara>
<simpara>After a resource is located, placeholders in the normal format
(<literal>${&#8230;&#8203;}</literal>) are resolved using the effective <literal>Environment</literal> for the
application name, profile and label supplied. In this way the resource
endpoint is tightly integrated with the environment
endpoints. Example, if you have this layout for a GIT (or SVN)
repository:</simpara>
<screen>application.yml
nginx.conf</screen>
<simpara>where <literal>nginx.conf</literal> looks like this:</simpara>
<screen>server {
    listen              80;
    server_name         ${nginx.server.name};
}</screen>
<simpara>and <literal>application.yml</literal> like this:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">nginx:
  server:
    name: example.com
---
spring:
  profiles: development
nginx:
  server:
    name: develop.com</programlisting>
<simpara>then the <literal>/foo/default/master/nginx.conf</literal> resource looks like this:</simpara>
<screen>server {
    listen              80;
    server_name         example.com;
}</screen>
<simpara>and <literal>/foo/development/master/nginx.conf</literal> like this:</simpara>
<screen>server {
    listen              80;
    server_name         develop.com;
}</screen>
<note>
<simpara>Just like the source files for environment configuration, the
"profile" is used to resolve the file name, so if you want a
profile-specific file then <literal>/*/development/*/logback.xml</literal> will be
resolved by a file called <literal>logback-development.xml</literal> (in preference
to <literal>logback.xml</literal>).</simpara>
</note>
<note>
<simpara>If you do not want to supply the <literal>label</literal> and let the server use the default label, you can supply a <literal>useDefaultLabel</literal> request parameter. So, the above example for the <literal>default</literal> profile could look like <literal>/foo/default/nginx.conf?useDefaultLabel</literal>.</simpara>
</note>
</chapter>
<chapter xml:id="_embedding_the_config_server">
<title>Embedding the Config Server</title>
<simpara>The Config Server runs best as a standalone application, but if you
need to you can embed it in another application. Just use the
<literal>@EnableConfigServer</literal> annotation. An optional property that can be
useful in this case is <literal>spring.cloud.config.server.bootstrap</literal> which is
a flag to indicate that the server should configure itself from its
own remote repository. The flag is off by default because it can delay
startup, but when embedded in another application it makes sense to
initialize the same way as any other application.</simpara>
<note>
<simpara>It should be obvious, but remember that if you use the bootstrap
flag the config server will need to have its name and repository URI
configured in <literal>bootstrap.yml</literal>.</simpara>
</note>
<simpara>To change the location of the server endpoints you can (optionally)
set <literal>spring.cloud.config.server.prefix</literal>, e.g. "/config", to serve the
resources under a prefix. The prefix should start but not end with a
"/". It is applied to the <literal>@RequestMappings</literal> in the Config Server
(i.e. underneath the Spring Boot prefixes <literal>server.servletPath</literal> and
<literal>server.contextPath</literal>).</simpara>
<simpara>If you want to read the configuration for an application directly from
the backend repository (instead of from the config server) that&#8217;s
basically an embedded config server with no endpoints. You can switch
off the endpoints entirely if you don&#8217;t use the <literal>@EnableConfigServer</literal>
annotation (just set <literal>spring.cloud.config.server.bootstrap=true</literal>).</simpara>
</chapter>
<chapter xml:id="_push_notifications_and_spring_cloud_bus">
<title>Push Notifications and Spring Cloud Bus</title>
<simpara>Many source code repository providers (like Github, Gitlab or Bitbucket
for instance) will notify you of changes in a repository through a
webhook. You can configure the webhook via the provider&#8217;s user
interface as a URL and a set of events in which you are
interested. For instance
<link xl:href="https://developer.github.com/v3/activity/events/types/#pushevent">Github</link>
will POST to the webhook with a JSON body containing a list of
commits, and a header "X-Github-Event" equal to "push". If you add a
dependency on the <literal>spring-cloud-config-monitor</literal> library and activate
the Spring Cloud Bus in your Config Server, then a "/monitor" endpoint
is enabled.</simpara>
<simpara>When the webhook is activated the Config Server will send a
<literal>RefreshRemoteApplicationEvent</literal> targeted at the applications it thinks
might have changed. The change detection can be strategized, but by
default it just looks for changes in files that match the application
name (e.g. "foo.properties" is targeted at the "foo" application, and
"application.properties" is targeted at all applications). The strategy
if you want to override the behaviour is <literal>PropertyPathNotificationExtractor</literal>
which accepts the request headers and body as parameters and returns a list
of file paths that changed.</simpara>
<simpara>The default configuration works out of the box with Github, Gitlab or
Bitbucket. In addition to the JSON notifications from Github, Gitlab
or Bitbucket you can trigger a change notification by POSTing to
"/monitor" with a form-encoded body parameters <literal>path={name}</literal>. This will
broadcast to applications matching the "{name}" pattern (can contain
wildcards).</simpara>
<note>
<simpara>the <literal>RefreshRemoteApplicationEvent</literal> will only be transmitted if
the <literal>spring-cloud-bus</literal> is activated in the Config Server and in the
client application.</simpara>
</note>
<note>
<simpara>the default configuration also detects filesystem changes in
local git repositories (the webhook is not used in that case but as
soon as you edit a config file a refresh will be broadcast).</simpara>
</note>
</chapter>
<chapter xml:id="_spring_cloud_config_client">
<title>Spring Cloud Config Client</title>
<simpara>A Spring Boot application can take immediate advantage of the Spring
Config Server (or other external property sources provided by the
application developer), and it will also pick up some additional
useful features related to <literal>Environment</literal> change events.</simpara>
<section xml:id="config-first-bootstrap">
<title>Config First Bootstrap</title>
<simpara>This is the default behaviour for any application which has the Spring
Cloud Config Client on the classpath. When a config client starts up
it binds to the Config Server (via the bootstrap configuration
property <literal>spring.cloud.config.uri</literal>) and initializes Spring
<literal>Environment</literal> with remote property sources.</simpara>
<simpara>The net result of this is that all client apps that want to consume
the Config Server need a <literal>bootstrap.yml</literal> (or an environment variable)
with the server address in <literal>spring.cloud.config.uri</literal> (defaults to
"http://localhost:8888").</simpara>
</section>
<section xml:id="discovery-first-bootstrap">
<title>Discovery First Bootstrap</title>
<simpara>If you are using a `DiscoveryClient implementation, such as Spring Cloud Netflix
and Eureka Service Discovery or Spring Cloud Consul (Spring Cloud Zookeeper does
not support this yet), then you can have the Config Server register with the
Discovery Service if you want to, but in the default "Config First" mode,
clients won&#8217;t be able to take advantage of the registration.</simpara>
<simpara>If you prefer to use <literal>DiscoveryClient</literal> to locate the Config Server, you can do
that by setting <literal>spring.cloud.config.discovery.enabled=true</literal> (default
"false"). The net result of that is that client apps all need a
<literal>bootstrap.yml</literal> (or an environment variable) with the appropriate discovery
configuration. For example, with Spring Cloud Netflix, you need to define the
Eureka server address, e.g. in <literal>eureka.client.serviceUrl.defaultZone</literal>.  The
price for using this option is an extra network round trip on start up to
locate the service registration. The benefit is that the Config Server
can change its co-ordinates, as long as the Discovery Service is a fixed point. The
default service id is "configserver" but you can change that on the
client with <literal>spring.cloud.config.discovery.serviceId</literal> (and on the server
in the usual way for a service, e.g. by setting <literal>spring.application.name</literal>).</simpara>
<simpara>The discovery client implementations all support some kind of metadata
map (e.g. for Eureka we have <literal>eureka.instance.metadataMap</literal>). Some
additional properties of the Config Server may need to be configured
in its service registration metadata so that clients can connect
correctly. If the Config Server is secured with HTTP Basic you can
configure the credentials as "username" and "password". And if the
Config Server has a context path you can set "configPath". Example,
for a Config Server that is a Eureka client:</simpara>
<formalpara>
<title>bootstrap.yml</title>
<para>
<programlisting language="yaml" linenumbering="unnumbered">eureka:
  instance:
    ...
    metadataMap:
      user: osufhalskjrtl
      password: lviuhlszvaorhvlo5847
      configPath: /config</programlisting>
</para>
</formalpara>
</section>
<section xml:id="config-client-fail-fast">
<title>Config Client Fail Fast</title>
<simpara>In some cases, it may be desirable to fail startup of a service if
it cannot connect to the Config Server.  If this is the desired
behavior, set the bootstrap configuration property
<literal>spring.cloud.config.failFast=true</literal> and the client will halt with
an Exception.</simpara>
</section>
<section xml:id="config-client-retry">
<title>Config Client Retry</title>
<simpara>If you expect that the config server may occasionally be unavailable when
your app starts, you can ask it to keep trying after a failure. First you need
to set <literal>spring.cloud.config.failFast=true</literal>, and then you need to add
<literal>spring-retry</literal> and <literal>spring-boot-starter-aop</literal> to your classpath. The default
behaviour is to retry 6 times with an initial backoff interval of 1000ms and an
exponential multiplier of 1.1 for subsequent backoffs. You can configure these
properties (and others) using <literal>spring.cloud.config.retry.*</literal> configuration properties.</simpara>
<tip>
<simpara>To take full control of the retry add a <literal>@Bean</literal> of type
<literal>RetryOperationsInterceptor</literal> with id "configServerRetryInterceptor". Spring
Retry has a <literal>RetryInterceptorBuilder</literal> that makes it easy to create one.</simpara>
</tip>
</section>
<section xml:id="_locating_remote_configuration_resources">
<title>Locating Remote Configuration Resources</title>
<simpara>The Config Service serves property sources from <literal>/{name}/{profile}/{label}</literal>, where the default bindings in the client app are</simpara>
<itemizedlist>
<listitem>
<simpara>"name" = <literal>${spring.application.name}</literal></simpara>
</listitem>
<listitem>
<simpara>"profile" = <literal>${spring.profiles.active}</literal> (actually <literal>Environment.getActiveProfiles()</literal>)</simpara>
</listitem>
<listitem>
<simpara>"label" = "master"</simpara>
</listitem>
</itemizedlist>
<simpara>All of them can be overridden by setting <literal>spring.cloud.config.*</literal>
(where <literal>*</literal> is "name", "profile" or "label"). The "label" is useful for
rolling back to previous versions of configuration; with the default
Config Server implementation it can be a git label, branch name or
commit id. Label can also be provided as a comma-separated list, in
which case the items in the list are tried on-by-one until one succeeds.
This can be useful when working on a feature branch, for instance,
when you might want to align the config label with your branch, but
make it optional (e.g. <literal>spring.cloud.config.label=myfeature,develop</literal>).</simpara>
</section>
<section xml:id="_security_2">
<title>Security</title>
<simpara>If you use HTTP Basic security on the server then clients just need to
know the password (and username if it isn&#8217;t the default). You can do
that via the config server URI, or via separate username and password
properties, e.g.</simpara>
<formalpara>
<title>bootstrap.yml</title>
<para>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
     uri: https://user:secret@myconfig.mycompany.com</programlisting>
</para>
</formalpara>
<simpara>or</simpara>
<formalpara>
<title>bootstrap.yml</title>
<para>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
     uri: https://myconfig.mycompany.com
     username: user
     password: secret</programlisting>
</para>
</formalpara>
<simpara>The <literal>spring.cloud.config.password</literal> and <literal>spring.cloud.config.username</literal>
values override anything that is provided in the URI.</simpara>
<simpara>If you deploy your apps on Cloud Foundry then the best way to provide
the password is through service credentials, e.g. in the URI, since
then it doesn&#8217;t even need to be in a config file. An example which
works locally and for a user-provided service on Cloud Foundry named
"configserver":</simpara>
<formalpara>
<title>bootstrap.yml</title>
<para>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
     uri: ${vcap.services.configserver.credentials.uri:http://user:password@localhost:8888}</programlisting>
</para>
</formalpara>
<simpara>If you use another form of security you might need to <link linkend="custom-rest-template">provide a
<literal>RestTemplate</literal></link> to the <literal>ConfigServicePropertySourceLocator</literal> (e.g. by
grabbing it in the bootstrap context and injecting one).</simpara>
<section xml:id="_health_indicator_2">
<title>Health Indicator</title>
<simpara>The Config Client supplies a Spring Boot Health Indicator that attempts to load configuration from Config Server. The health indicator can be disabled by setting <literal>health.config.enabled=false</literal>. The response is also cached for performance reasons. The default cache time to live is 5 minutes. To change that value set the <literal>health.config.time-to-live</literal> property (in milliseconds).</simpara>
</section>
<section xml:id="custom-rest-template">
<title>Providing A Custom RestTemplate</title>
<simpara>In some cases you might need to customize the requests made to the config server from
the client.  Typically this involves passing special <literal>Authorization</literal> headers to
authenticate requests to the server.  To provide a custom <literal>RestTemplate</literal> follow the
steps below.</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>Create a new configuration bean with an implementation of <literal>PropertySourceLocator</literal>.</simpara>
</listitem>
</orderedlist>
<formalpara>
<title>CustomConfigServiceBootstrapConfiguration.java</title>
<para>
<programlisting language="java" linenumbering="unnumbered">@Configuration
public class CustomConfigServiceBootstrapConfiguration {
    @Bean
    public ConfigServicePropertySourceLocator configServicePropertySourceLocator() {
        ConfigClientProperties clientProperties = configClientProperties();
       ConfigServicePropertySourceLocator configServicePropertySourceLocator =  new ConfigServicePropertySourceLocator(clientProperties);
        configServicePropertySourceLocator.setRestTemplate(customRestTemplate(clientProperties));
        return configServicePropertySourceLocator;
    }
}</programlisting>
</para>
</formalpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>In <literal>resources/META-INF</literal> create a file called
<literal>spring.factories</literal> and specify your custom configuration.</simpara>
</listitem>
</orderedlist>
<formalpara>
<title>spring.factories</title>
<para>
<programlisting language="properties" linenumbering="unnumbered">org.springframework.cloud.bootstrap.BootstrapConfiguration = com.my.config.client.CustomConfigServiceBootstrapConfiguration</programlisting>
</para>
</formalpara>
</section>
<section xml:id="_vault">
<title>Vault</title>
<simpara>When using Vault as a backend to your config server the client will need to
supply a token for the server to retrieve values from Vault.  This token
can be provided within the client by setting <literal>spring.cloud.config.token</literal>
in <literal>bootstrap.yml</literal>.</simpara>
<formalpara>
<title>bootstrap.yml</title>
<para>
<programlisting language="yaml" linenumbering="unnumbered">spring:
  cloud:
    config:
      token: YourVaultToken</programlisting>
</para>
</formalpara>
</section>
</section>
<section xml:id="_vault_2">
<title>Vault</title>
<section xml:id="_nested_keys_in_vault">
<title>Nested Keys In Vault</title>
<simpara>Vault supports the ability to nest keys in a value stored in Vault.  For example</simpara>
<simpara><literal>echo -n '{"appA": {"secret": "appAsecret"}, "bar": "baz"}' | vault write secret/myapp -</literal></simpara>
<simpara>This command will write a JSON object to your Vault.  To access these values in Spring
you would use the traditional dot(.) annotation.  For example</simpara>
<programlisting language="java" linenumbering="unnumbered">@Value("${appA.secret}")
String name = "World";</programlisting>
<simpara>The above code would set the <literal>name</literal> variable to <literal>appAsecret</literal>.</simpara>
</section>
</section>
</chapter>
</book>