493 lines
115 KiB
HTML
493 lines
115 KiB
HTML
<html><head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>2. Spring Cloud Config Server</title><link rel="stylesheet" type="text/css" href="css/manual-multipage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="multi_spring-cloud-config.html" title="Spring Cloud Config"><link rel="up" href="multi_spring-cloud-config.html" title="Spring Cloud Config"><link rel="prev" href="multi__quick_start.html" title="1. Quick Start"><link rel="next" href="multi__serving_alternative_formats.html" title="3. Serving Alternative Formats"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2. Spring Cloud Config Server</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="multi__quick_start.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="multi__serving_alternative_formats.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_config_server" href="#_spring_cloud_config_server"></a>2. Spring Cloud Config Server</h1></div></div></div><p>Spring Cloud Config Server provides an HTTP resource-based API for external configuration (name-value pairs or equivalent YAML content).
|
|
The server is embeddable in a Spring Boot application, by using the <code class="literal">@EnableConfigServer</code> annotation.
|
|
Consequently, the following application is a config server:</p><p><b>ConfigServer.java. </b>
|
|
</p><pre class="programlisting"><xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@SpringBootApplication</xslthl:annotation>
|
|
<xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@EnableConfigServer</xslthl:annotation>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ConfigServer {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
SpringApplication.run(ConfigServer.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, args);
|
|
}
|
|
}</pre><p>
|
|
</p><p>Like all Spring Boot applications, it runs on port 8080 by default, but you can switch it to the more conventional port 8888 in various ways.
|
|
The easiest, which also sets a default configuration repository, is by launching it with <code class="literal">spring.config.name=configserver</code> (there is a <code class="literal">configserver.yml</code> in the Config Server jar).
|
|
Another is to use your own <code class="literal">application.properties</code>, as shown in the following example:</p><p><b>application.properties. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">server.port</span>: 8888
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.config.server.git.uri</span>: file://${user.home}/config-repo</pre><p>
|
|
</p><p>where <code class="literal">${user.home}/config-repo</code> is a git repository containing YAML and properties files.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>On Windows, you need an extra "/" in the file URL if it is absolute with a drive prefix (for example,<code class="literal"><a class="link" href="file:///${user.home}/config-repo" target="_top">file:///${user.home}/config-repo</a></code>).</p></td></tr></table></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>The following listing shows a recipe for creating the git repository in the preceding example:</p><pre class="screen">$ cd $HOME
|
|
$ mkdir config-repo
|
|
$ cd config-repo
|
|
$ git init .
|
|
$ echo info.foo: bar > application.properties
|
|
$ git add -A .
|
|
$ git commit -m "Add application.properties"</pre></td></tr></table></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>Using the local filesystem for your git repository is intended for testing only.
|
|
You should use a server to host your configuration repositories in production.</p></td></tr></table></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>The initial clone of your configuration repository can be quick and efficient if you keep only text files in it.
|
|
If you store binary files, especially large ones, you may experience delays on the first request for configuration or encounter out of memory errors in the server.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_environment_repository" href="#_environment_repository"></a>2.1 Environment Repository</h2></div></div></div><p>Where should you store the configuration data for the Config Server?
|
|
The strategy that governs this behaviour is the <code class="literal">EnvironmentRepository</code>, serving <code class="literal">Environment</code> objects.
|
|
This <code class="literal">Environment</code> is a shallow copy of the domain from the Spring <code class="literal">Environment</code> (including <code class="literal">propertySources</code> as the main feature).
|
|
The <code class="literal">Environment</code> resources are parametrized by three variables:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">{application}</code>, which maps to <code class="literal">spring.application.name</code> on the client side.</li><li class="listitem"><code class="literal">{profile}</code>, which maps to <code class="literal">spring.profiles.active</code> on the client (comma-separated list).</li><li class="listitem"><code class="literal">{label}</code>, which is a server side feature labelling a "versioned" set of config files.</li></ul></div><p>Repository implementations generally behave like a Spring Boot application, loading configuration files from a <code class="literal">spring.config.name</code> equal to the <code class="literal">{application}</code> parameter, and <code class="literal">spring.profiles.active</code> equal to the <code class="literal">{profiles}</code> parameter.
|
|
Precedence rules for profiles are also the same as in a regular Spring Boot application: Active profiles take precedence over defaults, and, if there are multiple profiles, the last one wins (similar to adding entries to a <code class="literal">Map</code>).</p><p>The following sample client application has this bootstrap configuration:</p><p><b>bootstrap.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> application</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> name</span>: foo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> profiles</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> active</span>: dev,mysql</pre><p>
|
|
</p><p>(As usual with a Spring Boot application, these properties could also be set by environment variables or command line arguments).</p><p>If the repository is file-based, the server creates an
|
|
<code class="literal">Environment</code> from <code class="literal">application.yml</code> (shared between all clients) and
|
|
<code class="literal">foo.yml</code> (with <code class="literal">foo.yml</code> 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).
|
|
If there are profile-specific YAML (or properties) files, these are also applied with higher precedence than the defaults.
|
|
Higher precedence translates to a <code class="literal">PropertySource</code> listed earlier in the <code class="literal">Environment</code>.
|
|
(These same rules apply in a standalone Spring Boot application.)</p><p>You can set spring.cloud.config.server.accept-empty to false so that Server would return a HTTP 404 status, if the application is not found.By default, this flag is set to true.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_git_backend" href="#_git_backend"></a>2.1.1 Git Backend</h3></div></div></div><p>The default implementation of <code class="literal">EnvironmentRepository</code> uses a Git backend, which is very convenient for managing upgrades and physical environments and for auditing changes.
|
|
To change the location of the repository, you can set the <code class="literal">spring.cloud.config.server.git.uri</code> configuration property in the Config Server (for example in <code class="literal">application.yml</code>).
|
|
If you set it with a <code class="literal">file:</code> prefix, it should work from a local repository so that you can get started quickly and easily without a server. However, in that case, the server operates directly on the local repository without cloning it (it does not matter if it is 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 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 <code class="literal">ssh:</code> protocol for a shared filesystem repository, so that the server can clone it and use a local working copy as a cache.</p><p>This repository implementation maps the <code class="literal">{label}</code> 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 (<code class="literal">/</code>), then the label in the HTTP URL should instead be specified with the special string <code class="literal">(_)</code> (to avoid ambiguity with other URL paths).
|
|
For example, if the label is <code class="literal">foo/bar</code>, replacing the slash would result in the following label: <code class="literal">foo(_)bar</code>.
|
|
The inclusion of the special string <code class="literal">(_)</code> can also be applied to the <code class="literal">{application}</code> parameter.
|
|
If you use a command-line client such as curl, be careful with the brackets in the URL — you should escape them from the shell with single quotes ('').</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_skipping_ssl_certificate_validation" href="#_skipping_ssl_certificate_validation"></a>Skipping SSL Certificate Validation</h4></div></div></div><p>The configuration server’s validation of the Git server’s SSL certificate can be disabled by setting the <code class="literal">git.skipSslValidation</code> property to <code class="literal">true</code> (default is <code class="literal">false</code>).</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://example.com/my/repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> skipSslValidation</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_setting_http_connection_timeout" href="#_setting_http_connection_timeout"></a>Setting HTTP Connection Timeout</h4></div></div></div><p>You can configure the time, in seconds, that the configuration server will wait to acquire an HTTP connection. Use the <code class="literal">git.timeout</code> property.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://example.com/my/repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> timeout</span>: <xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">4</xslthl:number></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_placeholders_in_git_uri" href="#_placeholders_in_git_uri"></a>Placeholders in Git URI</h4></div></div></div><p>Spring Cloud Config Server supports a git repository URL with placeholders for the <code class="literal">{application}</code> and <code class="literal">{profile}</code> (and <code class="literal">{label}</code> if you need it, but remember that the label is applied as a git label anyway).
|
|
So you can support a <span class="quote">“<span class="quote">one repository per application</span>”</span> policy by using a structure similar to the following:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/myorg/{application<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><p>You can also support a <span class="quote">“<span class="quote">one repository per profile</span>”</span> policy by using a similar pattern but with
|
|
<code class="literal">{profile}</code>.</p><p>Additionally, using the special string "(_)" within your <code class="literal">{application}</code> parameters can enable support for multiple
|
|
organizations, as shown in the following example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/{application<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><p>where <code class="literal">{application}</code> is provided at request time in the following format: <code class="literal">organization(_)application</code>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_pattern_matching_and_multiple_repositories" href="#_pattern_matching_and_multiple_repositories"></a>Pattern Matching and Multiple Repositories</h4></div></div></div><p>Spring Cloud Config also includes support for more complex requirements with pattern
|
|
matching on the application and profile name.
|
|
The pattern format is a comma-separated list of <code class="literal">{application}/{profile}</code> names with wildcards (note that a pattern beginning with a wildcard may need to be quoted), as shown in the following example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/spring-cloud-samples/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> repos</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> simple</span>: https://github.com/simple/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> special</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: special*/dev*,*special*/dev*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/special/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> local</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: local*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: file:/home/configsvc/config-repo</pre><p>If <code class="literal">{application}/{profile}</code> does not match any of the patterns, it uses the default URI defined under <code class="literal">spring.cloud.config.server.git.uri</code>.
|
|
In the above example, for the <span class="quote">“<span class="quote">simple</span>”</span> repository, the pattern is <code class="literal">simple/*</code> (it only matches one application named <code class="literal">simple</code> in all profiles). The <span class="quote">“<span class="quote">local</span>”</span> repository matches all application names beginning with <code class="literal">local</code> in all profiles (the <code class="literal">/*</code> suffix is added automatically to any pattern that does not have a profile matcher).</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The <span class="quote">“<span class="quote">one-liner</span>”</span> short cut used in the <span class="quote">“<span class="quote">simple</span>”</span> example can be used only if the only property to be set is the URI.
|
|
If you need to set anything else (credentials, pattern, and so on) you need to use the full form.</p></td></tr></table></div><p>The <code class="literal">pattern</code> property in the repo is actually an array, so you can use a YAML array (or <code class="literal">[0]</code>, <code class="literal">[1]</code>, etc. suffixes in properties files) to bind to multiple patterns.
|
|
You may need to do so if you are going to run apps with multiple profiles, as shown in the following example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/spring-cloud-samples/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> repos</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> development</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>:
|
|
- <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'*/development'</span>
|
|
- <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'*/staging'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/development/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> staging</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>:
|
|
- <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'*/qa'</span>
|
|
- <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'*/production'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/staging/config-repo</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Spring Cloud guesses that a pattern containing a profile that does not end in <code class="literal">*</code> implies that you actually want to match a list of profiles starting with this pattern (so <code class="literal">*/staging</code> is a shortcut for <code class="literal">["*/staging", "*/staging,*"]</code>, and so on).
|
|
This is common where, for instance, you need to run applications in the <span class="quote">“<span class="quote">development</span>”</span> profile locally but also the <span class="quote">“<span class="quote">cloud</span>”</span> profile remotely.</p></td></tr></table></div><p>Every repository can also optionally store config files in sub-directories, and patterns to search for those directories can be specified as <code class="literal">searchPaths</code>.
|
|
The following example shows a config file at the top level:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/spring-cloud-samples/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> searchPaths</span>: foo,bar*</pre><p>In the preceding example, the server searches for config files in the top level and in the <code class="literal">foo/</code> sub-directory and also any sub-directory whose name begins with <code class="literal">bar</code>.</p><p>By default, the server clones remote repositories when configuration
|
|
is first requested.
|
|
The server can be configured to clone the repositories at startup, as shown in the following top-level example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://git/common/config-repo.git
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> repos</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> team-a</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: team-a-*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloneOnStart</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://git/team-a/config-repo.git
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> team-b</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: team-b-*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloneOnStart</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">false</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://git/team-b/config-repo.git
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> team-c</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: team-c-*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://git/team-a/config-repo.git</pre><p>In the preceding example, the server clones team-a’s config-repo on startup, before it
|
|
accepts any requests.
|
|
All other repositories are not cloned until configuration from the repository is requested.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Setting a repository to be cloned when the Config Server starts up can help to identify a misconfigured configuration source (such as an invalid repository URI) quickly, while the Config Server is starting up.
|
|
With <code class="literal">cloneOnStart</code> 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.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_authentication" href="#_authentication"></a>Authentication</h4></div></div></div><p>To use HTTP basic authentication on the remote repository, add the <code class="literal">username</code> and <code class="literal">password</code> properties separately (not in the URL), as shown in the following example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/spring-cloud-samples/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> username</span>: trolley
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password</span>: strongpassword</pre><p>If you do not use HTTPS and user credentials, SSH should also work out of the box when you store keys in the default directories (<code class="literal">~/.ssh</code>) and the URI points to an SSH location, such as <code class="literal">git@github.com:configuration/cloud-configuration</code>.
|
|
It is important that an entry for the Git server be present in the <code class="literal">~/.ssh/known_hosts</code> file and that it is in <code class="literal">ssh-rsa</code> format.
|
|
Other formats (such as <code class="literal">ecdsa-sha2-nistp256</code>) are not supported.
|
|
To avoid surprises, you should ensure that only one entry is present in the <code class="literal">known_hosts</code> file for the Git server and that it matches the URL you provided to the config server.
|
|
If you use a hostname in the URL, you want to have exactly that (not the IP) in the <code class="literal">known_hosts</code> file.
|
|
The repository is accessed by using JGit, so any documentation you find on that should be applicable.
|
|
HTTPS proxy settings can be set in <code class="literal">~/.git/config</code> or (in the same way as for any other JVM process) with
|
|
system properties (<code class="literal">-Dhttps.proxyHost</code> and <code class="literal">-Dhttps.proxyPort</code>).</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>If you do not know where your <code class="literal">~/.git</code> directory is, use <code class="literal">git config --global</code> to manipulate the settings (for example, <code class="literal">git config --global http.sslVerify false</code>).</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_authentication_with_aws_codecommit" href="#_authentication_with_aws_codecommit"></a>Authentication with AWS CodeCommit</h4></div></div></div><p>Spring Cloud Config Server also supports <a class="link" href="https://docs.aws.amazon.com/codecommit/latest/userguide/welcome.html" target="_top">AWS CodeCommit</a> authentication.
|
|
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 is created if the Git URI matches the AWS CodeCommit pattern.
|
|
AWS CodeCommit URIs follow this pattern://git-codecommit.${AWS_REGION}.amazonaws.com/${repopath}.</p><p>If you provide a username and password with an AWS CodeCommit URI, they must be the <a class="link" href="https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSGettingStartedGuide/AWSCredentials.html" target="_top">AWS accessKeyId and secretAccessKey</a> that provide access to the repository.
|
|
If you do not specify a username and password, the accessKeyId and secretAccessKey are retrieved by using the <a class="link" href="https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html" target="_top">AWS Default Credential Provider Chain</a>.</p><p>If your Git URI matches the CodeCommit URI pattern (shown earlier), 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 <a class="link" href="https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html" target="_top">IAM Roles for EC2 Instances</a>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The <code class="literal">aws-java-sdk-core</code> jar is an optional dependency.
|
|
If the <code class="literal">aws-java-sdk-core</code> jar is not on your classpath, the AWS Code Commit credential provider is not created, regardless of the git server URI.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_git_ssh_configuration_using_properties" href="#_git_ssh_configuration_using_properties"></a>Git SSH configuration using properties</h4></div></div></div><p>By default, the JGit library used by Spring Cloud Config Server uses SSH configuration files such as <code class="literal">~/.ssh/known_hosts</code> and <code class="literal">/etc/ssh/ssh_config</code> when connecting to Git repositories by using an SSH URI.
|
|
In cloud environments such as Cloud Foundry, the local filesystem may be ephemeral or not easily accessible.
|
|
For those cases, SSH configuration can be set by using Java properties.
|
|
In order to activate property-based SSH configuration, the <code class="literal">spring.cloud.config.server.git.ignoreLocalSshSettings</code> property must be set to <code class="literal">true</code>, as shown in the following example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: git<xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@gitserver.com:team/repo1.git</xslthl:annotation>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> ignoreLocalSshSettings</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> hostKey</span>: someHostKey
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> hostKeyAlgorithm</span>: ssh-rsa
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> privateKey</span>: |
|
|
-----BEGIN RSA PRIVATE KEY-----
|
|
MIIEpgIBAAKCAQEAx4UbaDzY5xjW6hc9jwN0mX33XpTDVW9WqHp5AKaRbtAC3DqX
|
|
IXFMPgw3K45jxRb93f8tv9vL3rD9CUG1Gv4FM+o7ds7FRES5RTjv2RT/JVNJCoqF
|
|
ol8+ngLqRZCyBtQN7zYByWMRirPGoDUqdPYrj2yq+ObBBNhg5N+hOwKjjpzdj2Ud
|
|
<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">1l</xslthl:number>7R+wxIqmJo1IYyy16xS8WsjyQuyC0lL456qkd5BDZ0Ag8j2X9H9D5220Ln7s9i
|
|
oezTipXipS7p7Jekf3Ywx6abJwOmB0rX79dV4qiNcGgzATnG1PkXxqt76VhcGa0W
|
|
DDVHEEYGbSQ6hIGSh0I7BQun0aLRZojfE3gqHQIDAQABAoIBAQCZmGrk8BK6tXCd
|
|
fY6yTiKxFzwb38IQP0ojIUWNrq0+<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">9</xslthl:number>Xt+NsypviLHkXfXXCKKU4zUHeIGVRq5MN9b
|
|
BO56/RrcQHHOoJdUWuOV2qMqJvPUtC0CpGkD+valhfD75MxoXU7s3FK7yjxy3rsG
|
|
EmfA6tHV8/<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">4</xslthl:number>a5umo5TqSd2YTm5B19AhRqiuUVI1wTB41DjULUGiMYrnYrhzQlVvj
|
|
<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">5</xslthl:number>MjnKTlYu3V8PoYDfv1GmxPPh6vlpafXEeEYN8VB97e5x3DGHjZ5UrurAmTLTdO8
|
|
+AahyoKsIY612TkkQthJlt7FJAwnCGMgY6podzzvzICLFmmTXYiZ/<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">28</xslthl:number>I4BX/mOSe
|
|
pZVnfRixAoGBAO6Uiwt40/PKs53mCEWngslSCsh9oGAaLTf/XdvMns5VmuyyAyKG
|
|
ti8Ol5wqBMi4GIUzjbgUvSUt+IowIrG3f5tN85wpjQ1UGVcpTnl5Qo9xaS1PFScQ
|
|
xrtWZ9eNj2TsIAMp/svJsyGG3OibxfnuAIpSXNQiJPwRlW3irzpGgVx/AoGBANYW
|
|
dnhshUcEHMJi3aXwR12OTDnaLoanVGLwLnkqLSYUZA7ZegpKq90UAuBdcEfgdpyi
|
|
PhKpeaeIiAaNnFo8m9aoTKr+<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">7</xslthl:number>I6/uMTlwrVnfrsVTZv3orxjwQV20YIBCVRKD1uX
|
|
VhE0ozPZxwwKSPAFocpyWpGHGreGF1AIYBE9UBtjAoGBAI8bfPgJpyFyMiGBjO6z
|
|
FwlJc/xlFqDusrcHL7abW5qq0L4v3R+FrJw3ZYufzLTVcKfdj6GelwJJO+<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">8</xslthl:number>wBm+R
|
|
gTKYJItEhT48duLIfTDyIpHGVm9+I1MGhh5zKuCqIhxIYr9jHloBB7kRm0rPvYY4
|
|
VAykcNgyDvtAVODP+<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">4</xslthl:number>m6JvhjAoGBALbtTqErKN47V0+JJpapLnF0KxGrqeGIjIRV
|
|
cYA6V4WYGr7NeIfesecfOC356PyhgPfpcVyEztwlvwTKb3RzIT1TZN8fH4YBr6Ee
|
|
KTbTjefRFhVUjQqnucAvfGi29f+<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">9</xslthl:number>oE3Ei9f7wA+H35ocF6JvTYUsHNMIO/<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">3</xslthl:number>gZ38N
|
|
CPjyCMa9AoGBAMhsITNe3QcbsXAbdUR00dDsIFVROzyFJ2m40i4KCRM35bC/BIBs
|
|
q0TY3we+ERB40U8Z2BvU61QuwaunJ2+uGadHo58VSVdggqAo0BSkH58innKKt96J
|
|
<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">69</xslthl:number>pcVH/<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">4</xslthl:number>rmLbXdcmNYGm6iu+MlPQk4BUZknHSmVHIFdJ0EPupVaQ8RHT
|
|
-----END RSA PRIVATE KEY-----</pre><p>The following table describes the SSH configuration properties.</p><div class="table"><a name="d0e633" href="#d0e633"></a><p class="title"><b>Table 2.1. SSH Configuration Properties</b></p><div class="table-contents"><table class="table" summary="SSH Configuration Properties" style="border-collapse: collapse;border-top: 1px solid ; border-bottom: 1px solid ; border-left: 1px solid ; border-right: 1px solid ; "><colgroup><col class="col_1"><col class="col_2"></colgroup><thead><tr><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top">Property Name</th><th style="border-bottom: 1px solid ; " align="left" valign="top">Remarks</th></tr></thead><tbody><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><span class="strong"><strong>ignoreLocalSshSettings</strong></span></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>If <code class="literal">true</code>, use property-based instead of file-based SSH config. Must be set at as <code class="literal">spring.cloud.config.server.git.ignoreLocalSshSettings</code>, <span class="strong"><strong>not</strong></span> inside a repository definition.</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><span class="strong"><strong>privateKey</strong></span></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>Valid SSH private key. Must be set if <code class="literal">ignoreLocalSshSettings</code> is true and Git URI is SSH format.</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><span class="strong"><strong>hostKey</strong></span></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>Valid SSH host key. Must be set if <code class="literal">hostKeyAlgorithm</code> is also set.</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><span class="strong"><strong>hostKeyAlgorithm</strong></span></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>One of <code class="literal">ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, or ecdsa-sha2-nistp521</code>. Must be set if <code class="literal">hostKey</code> is also set.</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><span class="strong"><strong>strictHostKeyChecking</strong></span></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">true</code> or <code class="literal">false</code>. If false, ignore errors with host key.</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><span class="strong"><strong>knownHostsFile</strong></span></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>Location of custom <code class="literal">.known_hosts</code> file.</p></td></tr><tr><td style="border-right: 1px solid ; " align="left" valign="top"><p><span class="strong"><strong>preferredAuthentications</strong></span></p></td><td style="" align="left" valign="top"><p>Override server authentication method order. This should allow for evading login prompts if server has keyboard-interactive authentication before the <code class="literal">publickey</code> method.</p></td></tr></tbody></table></div></div><br class="table-break"></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_placeholders_in_git_search_paths" href="#_placeholders_in_git_search_paths"></a>Placeholders in Git Search Paths</h4></div></div></div><p>Spring Cloud Config Server also supports a search path with placeholders for the <code class="literal">{application}</code> and <code class="literal">{profile}</code> (and <code class="literal">{label}</code> if
|
|
you need it), as shown in the following example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/spring-cloud-samples/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> searchPaths</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'{application}'</span></pre><p>The preceding listing causes a search of 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).</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_force_pull_in_git_repositories" href="#_force_pull_in_git_repositories"></a>Force pull in Git Repositories</h4></div></div></div><p>As mentioned earlier, Spring Cloud Config Server makes a clone of the remote git repository in case the local copy gets dirty (for example,
|
|
folder content changes by an OS process) such that Spring Cloud Config Server cannot update the local copy from remote repository.</p><p>To solve this issue, there is a <code class="literal">force-pull</code> property that makes Spring Cloud Config Server force pull from the remote repository if the local copy is dirty, as shown in the following example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/spring-cloud-samples/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> force-pull</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span></pre><p>If you have a multiple-repositories configuration, you can configure the <code class="literal">force-pull</code> property per repository, as shown in the following example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://git/common/config-repo.git
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> force-pull</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> repos</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> team-a</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: team-a-*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://git/team-a/config-repo.git
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> force-pull</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> team-b</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: team-b-*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://git/team-b/config-repo.git
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> force-pull</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> team-c</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: team-c-*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://git/team-a/config-repo.git</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The default value for <code class="literal">force-pull</code> property is <code class="literal">false</code>.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_deleting_untracked_branches_in_git_repositories" href="#_deleting_untracked_branches_in_git_repositories"></a>Deleting untracked branches in Git Repositories</h4></div></div></div><p>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 <code class="literal">--spring.cloud.config.label=deletedRemoteBranch,master</code>
|
|
it will fetch properties from <code class="literal">deletedRemoteBranch</code> local branch, but not from <code class="literal">master</code>.</p><p>In order to keep local repository branches clean and up to remote - <code class="literal">deleteUntrackedBranches</code> property could be set.
|
|
It will make Spring Cloud Config Server <span class="strong"><strong>force</strong></span> delete untracked branches from local repository.
|
|
Example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/spring-cloud-samples/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> deleteUntrackedBranches</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span></pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The default value for <code class="literal">deleteUntrackedBranches</code> property is <code class="literal">false</code>.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_git_refresh_rate" href="#_git_refresh_rate"></a>Git Refresh Rate</h4></div></div></div><p>You can control how often the config server will fetch updated configuration data
|
|
from your Git backend by using <code class="literal">spring.cloud.config.server.git.refreshRate</code>. The
|
|
value of this property is specified in seconds. By default the value is 0, meaning
|
|
the config server will fetch updated configuration from the Git repo every time it
|
|
is requested.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_version_control_backend_filesystem_use" href="#_version_control_backend_filesystem_use"></a>2.1.2 Version Control Backend Filesystem Use</h3></div></div></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>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 <code class="literal">config-repo-</code>.
|
|
On linux, for example, it could be <code class="literal">/tmp/config-repo-<randomid></code>.
|
|
Some operating systems <a class="link" href="https://serverfault.com/questions/377348/when-does-tmp-get-cleared/377349#377349" target="_top">routinely clean out</a> temporary directories.
|
|
This can lead to unexpected behavior, such as missing properties.
|
|
To avoid this problem, change the directory that Config Server uses by setting <code class="literal">spring.cloud.config.server.git.basedir</code> or <code class="literal">spring.cloud.config.server.svn.basedir</code> to a directory that does not reside in the system temp structure.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_file_system_backend" href="#_file_system_backend"></a>2.1.3 File System Backend</h3></div></div></div><p>There is also a <span class="quote">“<span class="quote">native</span>”</span> profile in the Config Server that does not use Git but loads the config files from the local classpath or file system (any static URL you want to point to with <code class="literal">spring.cloud.config.server.native.searchLocations</code>).
|
|
To use the native profile, launch the Config Server with <code class="literal">spring.profiles.active=native</code>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Remember to use the <code class="literal">file:</code> prefix for file resources (the default without a prefix is usually the classpath).
|
|
As with any Spring Boot configuration, you can embed <code class="literal">${}</code>-style environment placeholders, but remember that absolute paths in Windows require an extra <code class="literal">/</code> (for example, <code class="literal"><a class="link" href="file:///${user.home}/config-repo" target="_top">file:///${user.home}/config-repo</a></code>).</p></td></tr></table></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>The default value of the <code class="literal">searchLocations</code> is identical to a local Spring Boot application (that is, <code class="literal">[classpath:/, classpath:/config,
|
|
file:./, file:./config]</code>).
|
|
This does not expose the <code class="literal">application.properties</code> from the server to all clients, because any property sources present in the server are removed before being sent to the client.</p></td></tr></table></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>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.</p></td></tr></table></div><p>The search locations can contain placeholders for <code class="literal">{application}</code>, <code class="literal">{profile}</code>, and <code class="literal">{label}</code>.
|
|
In this way, you can segregate the directories in the path and choose a strategy that makes sense for you (such as subdirectory per application or subdirectory per profile).</p><p>If you do not use placeholders in the search locations, this repository also appends the <code class="literal">{label}</code> parameter of the HTTP resource to a suffix on the search path, so properties files are loaded from each search location <span class="strong"><strong>and</strong></span> 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 <code class="literal">/{label}/</code>.
|
|
For example, <code class="literal">file:/tmp/config</code> is the same as <code class="literal">file:/tmp/config,file:/tmp/config/{label}</code>.
|
|
This behavior can be disabled by setting <code class="literal">spring.cloud.config.server.native.addLabelLocations=false</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="vault-backend" href="#vault-backend"></a>2.1.4 Vault Backend</h3></div></div></div><p>Spring Cloud Config Server also supports <a class="link" href="https://www.vaultproject.io" target="_top">Vault</a> as a backend.</p><div class="sidebar"><div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div><p>Vault is a tool for securely accessing secrets.
|
|
A secret is anything that to which you want to tightly control access, such as API keys, passwords, certificates, and other sensitive information. Vault provides a unified interface to any secret while providing tight access control and recording a detailed audit log.</p></div><p>For more information on Vault, see the <a class="link" href="https://learn.hashicorp.com/vault/?track=getting-started#getting-started" target="_top">Vault quick start guide</a>.</p><p>To enable the config server to use a Vault backend, you can run your config server with the <code class="literal">vault</code> profile.
|
|
For example, in your config server’s <code class="literal">application.properties</code>, you can add <code class="literal">spring.profiles.active=vault</code>.</p><p>By default, the config server assumes that your Vault server runs at <code class="literal"><a class="link" href="http://127.0.0.1:8200" target="_top">http://127.0.0.1:8200</a></code>.
|
|
It also assumes that the name of backend is <code class="literal">secret</code> and the key is <code class="literal">application</code>.
|
|
All of these defaults can be configured in your config server’s <code class="literal">application.properties</code>.
|
|
The following table describes configurable Vault properties:</p><div class="informaltable"><table class="informaltable" style="border-collapse: collapse;border-top: 1px solid ; border-bottom: 1px solid ; border-left: 1px solid ; border-right: 1px solid ; "><colgroup><col class="col_1"><col class="col_2"></colgroup><thead><tr><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top">Name</th><th style="border-bottom: 1px solid ; " align="left" valign="top">Default Value</th></tr></thead><tbody><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>host</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>127.0.0.1</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>port</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>8200</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>scheme</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>http</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>backend</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>secret</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>defaultKey</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>application</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>profileSeparator</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>,</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>kvVersion</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>1</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>skipSslValidation</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>false</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>timeout</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>5</p></td></tr><tr><td style="border-right: 1px solid ; " align="left" valign="top"><p>namespace</p></td><td style="" align="left" valign="top"><p>null</p></td></tr></tbody></table></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>All of the properties in the preceding table must be prefixed with <code class="literal">spring.cloud.config.server.vault</code> or placed in the correct Vault section of a composite configuration.</p></td></tr></table></div><p>All configurable properties can be found in <code class="literal">org.springframework.cloud.config.server.environment.VaultEnvironmentProperties</code>.</p><p>Vault 0.10.0 introduced a versioned key-value backend (k/v backend version 2) that exposes a different API than earlier versions, it now requires a <code class="literal">data/</code> between the mount path and the actual context path and wraps secrets in a <code class="literal">data</code> object. Setting <code class="literal">kvVersion=2</code> will take this into account.</p><p>Optionally, there is support for the Vault Enterprise <code class="literal">X-Vault-Namespace</code> header. To have it sent to Vault set the <code class="literal">namespace</code> property.</p><p>With your config server running, you can make HTTP requests to the server to retrieve
|
|
values from the Vault backend.
|
|
To do so, you need a token for your Vault server.</p><p>First, place some data in you Vault, as shown in the following example:</p><pre class="programlisting">$ vault kv put secret/application foo=bar baz=bam
|
|
$ vault kv put secret/myapp foo=myappsbar</pre><p>Second, make an HTTP request to your config server to retrieve the values, as shown in the following example:</p><p><code class="literal">$ curl -X "GET" "http://localhost:8888/myapp/default" -H "X-Config-Token: yourtoken"</code></p><p>You should see a response similar to the following:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"myapp"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"profiles"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">[</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"default"</span>
|
|
]<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"label"</span>:null<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"version"</span>:null<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"state"</span>:null<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"propertySources"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">[</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"vault:myapp"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"source"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"myappsbar"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"vault:application"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"source"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"baz"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bam"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">]</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_multiple_properties_sources" href="#_multiple_properties_sources"></a>Multiple Properties Sources</h4></div></div></div><p>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:</p><pre class="programlisting">secret/myApp,dev
|
|
secret/myApp
|
|
secret/application,dev
|
|
secret/application</pre><p>Properties written to <code class="literal">secret/application</code> are available to <a class="link" href="">all applications using the Config Server</a>.
|
|
An application with the name, <code class="literal">myApp</code>, would have any properties written to <code class="literal">secret/myApp</code> and <code class="literal">secret/application</code> available to it.
|
|
When <code class="literal">myApp</code> has the <code class="literal">dev</code> profile enabled, 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.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_accessing_backends_through_a_proxy" href="#_accessing_backends_through_a_proxy"></a>2.1.5 Accessing Backends Through a Proxy</h3></div></div></div><p>The configuration server can access a Git or Vault backend through an HTTP or HTTPS proxy. This behavior is controlled for either Git or Vault by settings under <code class="literal">proxy.http</code> and <code class="literal">proxy.https</code>. These settings are per repository, so if you are using a <a class="link" href="multi__spring_cloud_config_server.html#composite-environment-repositories" title="2.1.9 Composite Environment Repositories">composite environment repository</a> you must configure proxy settings for each backend in the composite individually. If using a network which requires separate proxy servers for HTTP and HTTPS URLs, you can configure both the HTTP and the HTTPS proxy settings for a single backend.</p><p>The following table describes the proxy configuration properties for both HTTP and HTTPS proxies. All of these properties must be prefixed by <code class="literal">proxy.http</code> or <code class="literal">proxy.https</code>.</p><div class="table"><a name="d0e1138" href="#d0e1138"></a><p class="title"><b>Table 2.2. Proxy Configuration Properties</b></p><div class="table-contents"><table class="table" summary="Proxy Configuration Properties" style="border-collapse: collapse;border-top: 1px solid ; border-bottom: 1px solid ; border-left: 1px solid ; border-right: 1px solid ; "><colgroup><col class="col_1"><col class="col_2"></colgroup><thead><tr><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top">Property Name</th><th style="border-bottom: 1px solid ; " align="left" valign="top">Remarks</th></tr></thead><tbody><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><span class="strong"><strong>host</strong></span></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>The host of the proxy.</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><span class="strong"><strong>port</strong></span></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>The port with which to access the proxy.</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><span class="strong"><strong>nonProxyHosts</strong></span></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>Any hosts which the configuration server should access outside the proxy. If values are provided for both <code class="literal">proxy.http.nonProxyHosts</code> and <code class="literal">proxy.https.nonProxyHosts</code>, the <code class="literal">proxy.http</code> value will be used.</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><span class="strong"><strong>username</strong></span></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>The username with which to authenticate to the proxy. If values are provided for both <code class="literal">proxy.http.username</code> and <code class="literal">proxy.https.username</code>, the <code class="literal">proxy.http</code> value will be used.</p></td></tr><tr><td style="border-right: 1px solid ; " align="left" valign="top"><p><span class="strong"><strong>password</strong></span></p></td><td style="" align="left" valign="top"><p>The password with which to authenticate to the proxy. If values are provided for both <code class="literal">proxy.http.password</code> and <code class="literal">proxy.https.password</code>, the <code class="literal">proxy.http</code> value will be used.</p></td></tr></tbody></table></div></div><br class="table-break"><p>The following configuration uses an HTTPS proxy to access a Git repository.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> profiles</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> active</span>: git
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/spring-cloud-samples/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> proxy</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> https</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> host</span>: my-proxy.host.io
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password</span>: myproxypassword
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> port</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'3128'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> username</span>: myproxyusername
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> nonProxyHosts</span>: example.com</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_sharing_configuration_with_all_applications" href="#_sharing_configuration_with_all_applications"></a>2.1.6 Sharing Configuration With All Applications</h3></div></div></div><p>Sharing configuration between all applications varies according to which approach you take, as described in the following topics:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="xref" href="multi__spring_cloud_config_server.html#spring-cloud-config-server-file-based-repositories" title="File Based Repositories">the section called “File Based Repositories”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_config_server.html#spring-cloud-config-server-vault-server" title="Vault Server">the section called “Vault Server”</a></li></ul></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="spring-cloud-config-server-file-based-repositories" href="#spring-cloud-config-server-file-based-repositories"></a>File Based Repositories</h4></div></div></div><p>With file-based (git, svn, and native) repositories, resources with file names in <code class="literal">application*</code> (<code class="literal">application.properties</code>, <code class="literal">application.yml</code>, <code class="literal">application-*.properties</code>, and so on) are shared between all client applications.
|
|
You can use resources with these file names to configure global defaults and have them be overridden by application-specific files as necessary.</p><p>The #_property_overrides[property overrides] feature can also be used for setting global defaults, with placeholders applications
|
|
allowed to override them locally.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>With the <span class="quote">“<span class="quote">native</span>”</span> profile (a local file system backend) , you should use an explicit search location that is not part of the server’s own configuration.
|
|
Otherwise, the <code class="literal">application*</code> resources in the default search locations get removed because they are part of the server.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="spring-cloud-config-server-vault-server" href="#spring-cloud-config-server-vault-server"></a>Vault Server</h4></div></div></div><p>When using Vault as a backend, you can share configuration with all applications by placing configuration in <code class="literal">secret/application</code>.
|
|
For example, if you run the following Vault command, all applications using the config server will have the properties <code class="literal">foo</code> and <code class="literal">baz</code> available to them:</p><pre class="programlisting">$ vault write secret/application foo=bar baz=bam</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_credhub_server" href="#_credhub_server"></a>CredHub Server</h4></div></div></div><p>When using CredHub as a backend, you can share configuration with all applications by placing configuration in <code class="literal">/application/</code> or by placing it in the <code class="literal">default</code> profile for the application.
|
|
For example, if you run the following CredHub command, all applications using the config server will have the properties <code class="literal">shared.color1</code> and <code class="literal">shared.color2</code> available to them:</p><pre class="programlisting">credhub set --name "/application/profile/master/shared" --type=json
|
|
value: {"shared.color1": "blue", "shared.color": "red"}</pre><pre class="programlisting">credhub set --name "/my-app/default/master/more-shared" --type=json
|
|
value: {"shared.word1": "hello", "shared.word2": "world"}</pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_jdbc_backend" href="#_jdbc_backend"></a>2.1.7 JDBC Backend</h3></div></div></div><p>Spring Cloud Config Server supports JDBC (relational database) as a backend for configuration properties.
|
|
You can enable this feature by adding <code class="literal">spring-jdbc</code> to the classpath and using the <code class="literal">jdbc</code> profile or by adding a bean of type <code class="literal">JdbcEnvironmentRepository</code>.
|
|
If you include the right dependencies on the classpath (see the user guide for more details on that), Spring Boot configures a data source.</p><p>The database needs to have a table called <code class="literal">PROPERTIES</code> with columns called <code class="literal">APPLICATION</code>, <code class="literal">PROFILE</code>, and <code class="literal">LABEL</code> (with the usual <code class="literal">Environment</code> meaning), plus <code class="literal">KEY</code> and <code class="literal">VALUE</code> for the key and value pairs in <code class="literal">Properties</code> style.
|
|
All fields are of type String in Java, so you can make them <code class="literal">VARCHAR</code> of whatever length you need.
|
|
Property values behave in the same way as they would if they came from Spring Boot properties files named <code class="literal">{application}-{profile}.properties</code>, including all the encryption and decryption, which will be applied as post-processing steps (that is, not in the repository implementation directly).</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_credhub_backend" href="#_credhub_backend"></a>2.1.8 CredHub Backend</h3></div></div></div><p>Spring Cloud Config Server supports <a class="link" href="https://docs.cloudfoundry.org/credhub" target="_top">CredHub</a> as a backend for configuration properties.
|
|
You can enable this feature by adding a dependency to <a class="link" href="https://spring.io/projects/spring-credhub" target="_top">Spring CredHub</a>.</p><p><b>pom.xml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.credhub<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-credhub-starter<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span></pre><p>
|
|
</p><p>The following configuration uses mutual TLS to access a CredHub:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> profiles</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> active</span>: credhub
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> credhub</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> url</span>: https://credhub:<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">8844</xslthl:number></pre><p>The properties should be stored as JSON, such as:</p><pre class="programlisting">credhub set --name "/demo-app/default/master/toggles" --type=json
|
|
value: {"toggle.button": "blue", "toggle.link": "red"}</pre><pre class="programlisting">credhub set --name "/demo-app/default/master/abs" --type=json
|
|
value: {"marketing.enabled": true, "external.enabled": false}</pre><p>All client applications with the name <code class="literal">spring.cloud.config.name=demo-app</code> will have the following properties available to them:</p><pre class="screen">{
|
|
toggle.button: "blue",
|
|
toggle.link: "red",
|
|
marketing.enabled: true,
|
|
external.enabled: false
|
|
}</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>When no profile is specified <code class="literal">default</code> will be used and when no label is specified <code class="literal">master</code> will be used as a default value.
|
|
NOTE: Values added to <code class="literal">application</code> will be shared by all the applications.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_oauth_2_0" href="#_oauth_2_0"></a>OAuth 2.0</h4></div></div></div><p>You can authenticate with <a class="link" href="https://oauth.net/2/" target="_top">OAuth 2.0</a> using <a class="link" href="https://docs.cloudfoundry.org/concepts/architecture/uaa.html" target="_top">UAA</a> as a provider.</p><p><b>pom.xml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.security<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-security-config<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.security<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-security-oauth2-client<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span></pre><p>
|
|
</p><p>The following configuration uses OAuth 2.0 and UAA to access a CredHub:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> profiles</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> active</span>: credhub
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> credhub</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> url</span>: https://credhub:<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">8844</xslthl:number>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> oauth2</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> registration-id</span>: credhub-client
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> security</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> oauth2</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> client</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> registration</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> credhub-client</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> provider</span>: uaa
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> client-id</span>: credhub_config_server
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> client-secret</span>: asecret
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> authorization-grant-type</span>: client_credentials
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> provider</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uaa</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> token-uri</span>: https://uaa:<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">8443</xslthl:number>/oauth/token</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The used UAA client-id should have <code class="literal">credhub.read</code> as scope.</p></td></tr></table></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="composite-environment-repositories" href="#composite-environment-repositories"></a>2.1.9 Composite Environment Repositories</h3></div></div></div><p>In some scenarios, you may wish to pull configuration data from multiple environment repositories.
|
|
To do so, you can enable the <code class="literal">composite</code> profile in your configuration server’s application properties or YAML file.
|
|
If, for example, you want to pull configuration data from a Subversion repository as well as two Git repositories, you can set the following properties for your configuration server:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> profiles</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> active</span>: composite
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> composite</span>:
|
|
-
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> type</span>: svn
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: file:///path/to/svn/repo
|
|
-
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> type</span>: git
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: file:///path/to/rex/git/repo
|
|
-
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> type</span>: git
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: file:///path/to/walter/git/repo</pre><p>Using this configuration, precedence is determined by the order in which repositories are listed under the <code class="literal">composite</code> key.
|
|
In the above example, the Subversion repository is listed first, so a value found in the Subversion repository will override values found for the same property in one of the Git repositories.
|
|
A value found in the <code class="literal">rex</code> Git repository will be used before a value found for the same property in the <code class="literal">walter</code> Git repository.</p><p>If you want to pull configuration data only from repositories that are each of distinct types, you can enable the corresponding profiles, rather than the <code class="literal">composite</code> profile, in your configuration server’s application properties or YAML file.
|
|
If, for example, you want to pull configuration data from a single Git repository and a single HashiCorp Vault server, you can set the following properties for your configuration server:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> profiles</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> active</span>: git<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> vault
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: file:///path/to/git/repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> order</span>: <xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">2</xslthl:number>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> host</span>: <xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">127.0</xslthl:number>.<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">0.1</xslthl:number>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> port</span>: <xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">8200</xslthl:number>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> order</span>: <xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">1</xslthl:number></pre><p>Using this configuration, precedence can be determined by an <code class="literal">order</code> property.
|
|
You can use the <code class="literal">order</code> property to specify the priority order for all your repositories.
|
|
The lower the numerical value of the <code class="literal">order</code> property, the higher priority it has.
|
|
The priority order of a repository helps resolve any potential conflicts between repositories that contain values for the same properties.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>If your composite environment includes a Vault server as in the previous example, you must include a Vault token in every request made to the configuration server. See <a class="link" href="multi__spring_cloud_config_server.html#vault-backend" title="2.1.4 Vault Backend">Vault Backend</a>.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Any type of failure when retrieving values from an environment repository results in a failure for the entire composite environment.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>When using a composite environment, it is important that all repositories contain the same labels.
|
|
If you have an environment similar to those in the preceding examples and you request configuration data with the <code class="literal">master</code> label but the Subversion repository does not contain a branch called <code class="literal">master</code>, the entire request fails.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_custom_composite_environment_repositories" href="#_custom_composite_environment_repositories"></a>Custom Composite Environment Repositories</h4></div></div></div><p>In addition to using one of the environment repositories from Spring Cloud, you can also provide your own <code class="literal">EnvironmentRepository</code> bean to be included as part of a composite environment.
|
|
To do so, your bean must implement the <code class="literal">EnvironmentRepository</code> interface.
|
|
If you want to control the priority of your custom <code class="literal">EnvironmentRepository</code> within the composite environment, you should also implement the <code class="literal">Ordered</code> interface and override the <code class="literal">getOrdered</code> method.
|
|
If you do not implement the <code class="literal">Ordered</code> interface, your <code class="literal">EnvironmentRepository</code> is given the lowest priority.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_property_overrides" href="#_property_overrides"></a>2.1.10 Property Overrides</h3></div></div></div><p>The Config Server has an <span class="quote">“<span class="quote">overrides</span>”</span> feature that lets the operator provide configuration properties to all applications.
|
|
The overridden properties cannot be accidentally changed by the application with the normal Spring Boot hooks.
|
|
To declare overrides, add a map of name-value pairs to <code class="literal">spring.cloud.config.server.overrides</code>, as shown in the following example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> overrides</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> foo</span>: bar</pre><p>The preceding examples causes all applications that are config clients to read <code class="literal">foo=bar</code>, independent of their own configuration.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>A configuration system cannot force an application to use configuration data in any particular way.
|
|
Consequently, overrides are not enforceable.
|
|
However, they do provide useful default behavior for Spring Cloud Config clients.</p></td></tr></table></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>Normally, Spring environment placeholders with <code class="literal">${}</code> can be escaped (and resolved on the client) by using backslash (<code class="literal">\</code>) to escape the <code class="literal">$</code> or the <code class="literal">{</code>.
|
|
For example, <code class="literal">\${app.foo:bar}</code> resolves to <code class="literal">bar</code>, unless the app provides its own <code class="literal">app.foo</code>.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>In YAML, you do not need to escape the backslash itself.
|
|
However, in properties files, you do need to escape the backslash, when you configure the overrides on the server.</p></td></tr></table></div><p>You can change the priority of all overrides in the client to be more like default values, letting applications supply their own values in environment variables or System properties, by setting the <code class="literal">spring.cloud.config.overrideNone=true</code> flag (the default is false) in the remote repository.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_health_indicator" href="#_health_indicator"></a>2.2 Health Indicator</h2></div></div></div><p>Config Server comes with a Health Indicator that checks whether the configured <code class="literal">EnvironmentRepository</code> is working.
|
|
By default, it asks the <code class="literal">EnvironmentRepository</code> for an application named <code class="literal">app</code>, the <code class="literal">default</code> profile, and the default label provided by the <code class="literal">EnvironmentRepository</code> implementation.</p><p>You can configure the Health Indicator to check more applications along with custom profiles and custom labels, as shown in the following example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> health</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> repositories</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> myservice</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> label</span>: mylabel
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> myservice-dev</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> name</span>: myservice
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> profiles</span>: development</pre><p>You can disable the Health Indicator by setting <code class="literal">spring.cloud.config.server.health.enabled=false</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_security" href="#_security"></a>2.3 Security</h2></div></div></div><p>You can secure your Config Server in any way that makes sense to you (from physical network security to OAuth2 bearer tokens), because Spring Security and Spring Boot offer support for many security arrangements.</p><p>To use the default Spring Boot-configured HTTP Basic security, include Spring Security on the classpath (for example, through <code class="literal">spring-boot-starter-security</code>).
|
|
The default is a username of <code class="literal">user</code> and a randomly generated password. A random password is not useful in practice, so we recommend you configure the password (by setting <code class="literal">spring.security.user.password</code>) and encrypt it (see below for instructions on how to do that).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_encryption_and_decryption" href="#_encryption_and_decryption"></a>2.4 Encryption and Decryption</h2></div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>To use the encryption and decryption features you need the full-strength JCE installed in your JVM (it is not included by default).
|
|
You can download the <span class="quote">“<span class="quote">Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files</span>”</span> from Oracle and follow the installation instructions (essentially, you need to replace the two policy files in the JRE lib/security directory with the ones that you downloaded).</p></td></tr></table></div><p>If the remote property sources contain encrypted content (values starting with <code class="literal">{cipher}</code>), they are decrypted before sending to clients over HTTP.
|
|
The main advantage of this setup is that the property values need not be in plain text when they are <span class="quote">“<span class="quote">at rest</span>”</span> (for example, 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 <code class="literal">invalid</code> and a value that means <span class="quote">“<span class="quote">not applicable</span>”</span> (usually <code class="literal"><n/a></code>).
|
|
This is largely to prevent cipher text being used as a password and accidentally leaking.</p><p>If you set up a remote config repository for config client applications, it might contain an <code class="literal">application.yml</code> similar to the following:</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> datasource</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> username</span>: dbuser
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'{cipher}FKSAJDFGYOS8F7GLHAKERGFHLSAJ'</span></pre><p>
|
|
</p><p>Encrypted values in a .properties file must not be wrapped in quotes. Otherwise, the value is not decrypted. The following example shows values that would work:</p><p><b>application.properties. </b>
|
|
</p><pre class="screen">spring.datasource.username: dbuser
|
|
spring.datasource.password: {cipher}FKSAJDFGYOS8F7GLHAKERGFHLSAJ</pre><p>
|
|
</p><p>You can safely push this plain text to a shared git repository, and the secret password remains protected.</p><p>The server also exposes <code class="literal">/encrypt</code> and <code class="literal">/decrypt</code> endpoints (on the assumption that these are secured and only accessed by authorized agents).
|
|
If you edit a remote config file, you can use the Config Server to encrypt values by POSTing to the <code class="literal">/encrypt</code> endpoint, as shown in the following example:</p><pre class="screen">$ curl localhost:8888/encrypt -d mysecret
|
|
682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>If the value you encrypt has characters in it that need to be URL encoded, you should use the <code class="literal">--data-urlencode</code> option to <code class="literal">curl</code> to make sure they are encoded properly.</p></td></tr></table></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>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.</p></td></tr></table></div><p>The inverse operation is also available through <code class="literal">/decrypt</code> (provided the server is
|
|
configured with a symmetric key or a full key pair), as shown in the following example:</p><pre class="screen">$ curl localhost:8888/decrypt -d 682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
|
|
mysecret</pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>If you testing with curl, then use <code class="literal">--data-urlencode</code> (instead of <code class="literal">-d</code>) or set an explicit <code class="literal">Content-Type: text/plain</code> to make sure curl encodes the data correctly when there are special characters ('+' is particularly tricky).</p></td></tr></table></div><p>Take the encrypted value and add the <code class="literal">{cipher}</code> prefix before you put it in the YAML or properties file and before you commit and push it to a remote (potentially insecure) store.</p><p>The <code class="literal">/encrypt</code> and <code class="literal">/decrypt</code> endpoints also both accept paths in the form of <code class="literal">/*/{application}/{profiles}</code>, which can be used to control cryptography on a per-application (name) and per-profile basis when clients call into the main environment resource.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>To control the cryptography in this granular way, you must also provide a <code class="literal">@Bean</code> of type <code class="literal">TextEncryptorLocator</code> that creates a different encryptor per name and profiles.
|
|
The one that is provided by default does not do so (all encryptions use the same key).</p></td></tr></table></div><p>The <code class="literal">spring</code> command line client (with Spring Cloud CLI extensions
|
|
installed) can also be used to encrypt and decrypt, as shown in the following example:</p><pre class="screen">$ spring encrypt mysecret --key foo
|
|
682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
|
|
$ spring decrypt --key foo 682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
|
|
mysecret</pre><p>To use a key in a file (such as an RSA public key for encryption), prepend
|
|
the key value with "@" and provide the file path, as shown in the following example:</p><pre class="screen">$ spring encrypt mysecret --key @${HOME}/.ssh/id_rsa.pub
|
|
AQAjPgt3eFZQXwt8tsHAVv/QHiY5sI2dRcR+...</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The <code class="literal">--key</code> argument is mandatory (despite having a <code class="literal">--</code> prefix).</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_key_management" href="#_key_management"></a>2.5 Key Management</h2></div></div></div><p>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 a single property value to configure in the <code class="literal">bootstrap.properties</code>.</p><p>To configure a symmetric key, you need to set <code class="literal">encrypt.key</code> to a secret String (or use the <code class="literal">ENCRYPT_KEY</code> environment variable to keep it out of plain-text configuration files).</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>You cannot configure an asymmetric key using <code class="literal">encrypt.key</code>.</p></td></tr></table></div><p>To configure an asymmetric key use a keystore (e.g. as
|
|
created by the <code class="literal">keytool</code> utility that comes with the JDK). The
|
|
keystore properties are <code class="literal">encrypt.keyStore.*</code> with <code class="literal">*</code> equal to</p><div class="informaltable"><table class="informaltable" style="border-collapse: collapse;border-top: 1px solid ; border-bottom: 1px solid ; border-left: 1px solid ; border-right: 1px solid ; "><colgroup><col class="col_1"><col class="col_2"></colgroup><thead><tr><th style="border-right: 1px solid ; border-bottom: 1px solid ; " align="center" valign="top">Property</th><th style="border-bottom: 1px solid ; " align="center" valign="top">Description</th></tr></thead><tbody><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">encrypt.keyStore.location</code></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>Contains a <code class="literal">Resource</code> location</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">encrypt.keyStore.password</code></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>Holds the password that unlocks the keystore</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">encrypt.keyStore.alias</code></p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>Identifies which key in the store to use</p></td></tr><tr><td style="border-right: 1px solid ; " align="left" valign="top"><p><code class="literal">encrypt.keyStore.type</code></p></td><td style="" align="left" valign="top"><p>The type of KeyStore to create. Defaults to <code class="literal">jks</code>.</p></td></tr></tbody></table></div><p>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 want to only encrypt (and are prepared to decrypt the values yourself locally with the private key).
|
|
In practice, you might not want to do decrypt locally, because it spreads the key management process around all the clients, instead of
|
|
concentrating it in the server.
|
|
On the other hand, it can be a useful option if your config server is relatively insecure and only a handful of clients need the encrypted properties.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_creating_a_key_store_for_testing" href="#_creating_a_key_store_for_testing"></a>2.6 Creating a Key Store for Testing</h2></div></div></div><p>To create a keystore for testing, you can use a command resembling the following:</p><pre class="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</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>When using JDK 11 or above you may get the following warning when using the command above. In this case
|
|
you probably want to make sure the <code class="literal">keypass</code> and <code class="literal">storepass</code> values match.</p></td></tr></table></div><pre class="screen">Warning: Different store and key passwords not supported for PKCS12 KeyStores. Ignoring user-specified -keypass value.</pre><p>Put the <code class="literal">server.jks</code> file in the classpath (for instance) and then, in
|
|
your <code class="literal">bootstrap.yml</code>, for the Config Server, create the following settings:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">encrypt</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> keyStore</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> location</span>: classpath:/server.jks
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password</span>: letmein
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> alias</span>: mytestkey
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> secret</span>: changeme</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_using_multiple_keys_and_key_rotation" href="#_using_multiple_keys_and_key_rotation"></a>2.7 Using Multiple Keys and Key Rotation</h2></div></div></div><p>In addition to the <code class="literal">{cipher}</code> prefix in encrypted property values, the Config Server looks for zero or more <code class="literal">{name:value}</code> prefixes before the start of the (Base64 encoded) cipher text.
|
|
The keys are passed to a <code class="literal">TextEncryptorLocator</code>, which can do whatever logic it needs to locate a <code class="literal">TextEncryptor</code> for the cipher.
|
|
If you have configured a keystore (<code class="literal">encrypt.keystore.location</code>), the default locator looks for keys with aliases supplied by the <code class="literal">key</code> prefix, with a cipher text like resembling the following:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">foo</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> bar</span>: `{cipher}{key:testkey}...`</pre><p>The locator looks for a key named "testkey".
|
|
A secret can also be supplied by using a <code class="literal">{secret:…​}</code> value in the prefix.
|
|
However, if it is not supplied, the default is to use the keystore password (which is what you get when you build a keystore and do not specify a secret).
|
|
If you do supply a secret, you should also encrypt the secret using a custom <code class="literal">SecretLocator</code>.</p><p>When the keys are being used only to encrypt a few bytes of configuration data (that is, they are not being used elsewhere), key rotation is hardly ever necessary on cryptographic grounds.
|
|
However, you might occasionally need to change the keys (for example, in the event of a security breach).
|
|
In that case, all the clients would need to change their source config files (for example, in git) and use a new <code class="literal">{key:…​}</code> prefix in all the ciphers.
|
|
Note that the clients need to first check that the key alias is available in the Config Server keystore.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>If you want to let the Config Server handle all encryption as well as decryption, the <code class="literal">{name:value}</code> prefixes can also be added as plain text posted to the <code class="literal">/encrypt</code> endpoint, .</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_serving_encrypted_properties" href="#_serving_encrypted_properties"></a>2.8 Serving Encrypted Properties</h2></div></div></div><p>Sometimes you want the clients to decrypt the configuration locally, instead of doing it in the server.
|
|
In that case, if you provide the <code class="literal">encrypt.*</code> configuration to locate a key, you can still have <code class="literal">/encrypt</code> and <code class="literal">/decrypt</code> endpoints, but you need to explicitly switch off the decryption of outgoing properties by placing <code class="literal">spring.cloud.config.server.encrypt.enabled=false</code> in <code class="literal">bootstrap.[yml|properties]</code>.
|
|
If you do not care about the endpoints, it should work if you do not configure either the key or the enabled flag.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="multi__quick_start.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="multi__serving_alternative_formats.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1. Quick Start </td><td width="20%" align="center"><a accesskey="h" href="multi_spring-cloud-config.html">Home</a></td><td width="40%" align="right" valign="top"> 3. Serving Alternative Formats</td></tr></table></div></body></html> |