Sync docs from master to gh-pages
This commit is contained in:
buildmaster
@@ -1,6 +1,6 @@
|
||||
<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.78.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).
|
||||
<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"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
||||
@@ -60,12 +60,12 @@ If you use a command-line client such as curl, be careful with the brackets in t
|
||||
<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>: <span class="hl-number">4</span></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 “one repository per application” 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>:
|
||||
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 “one repository per profile” policy by using a similar pattern but with
|
||||
<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>:
|
||||
@@ -88,7 +88,7 @@ The pattern format is a comma-separated list of <code class="literal">{applicati
|
||||
<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 “simple” repository, the pattern is <code class="literal">simple/*</code> (it only matches one application named <code class="literal">simple</code> in all profiles). The “local” 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 “one-liner” short cut used in the “simple” example can be used only if the only property to be set is the URI.
|
||||
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>:
|
||||
@@ -107,7 +107,7 @@ You may need to do so if you are going to run apps with multiple profiles, as sh
|
||||
- <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 “development” profile locally but also the “cloud” 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>.
|
||||
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>:
|
||||
@@ -195,7 +195,7 @@ In order to activate property-based SSH configuration, the <code class="literal"
|
||||
CPjyCMa9AoGBAMhsITNe3QcbsXAbdUR00dDsIFVROzyFJ2m40i4KCRM35bC/BIBs
|
||||
q0TY3we+ERB40U8Z2BvU61QuwaunJ2+uGadHo58VSVdggqAo0BSkH58innKKt96J
|
||||
<span class="hl-number">69</span>pcVH/<span class="hl-number">4</span>rmLbXdcmNYGm6iu+MlPQk4BUZknHSmVHIFdJ0EPupVaQ8RHT
|
||||
-----END RSA PRIVATE KEY-----</pre><p>The following table describes the SSH configuration properties.</p><div class="table"><a name="d0e607" href="#d0e607"></a><p class="title"><b>Table 2.1. SSH Configuration Properties</b></p><div class="table-contents"><table summary="SSH Configuration Properties" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; "><colgroup><col class="col_1"><col class="col_2"></colgroup><thead><tr><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">Property Name</th><th style="border-bottom: 0.5pt solid ; " align="left" valign="top">Remarks</th></tr></thead><tbody><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><span class="strong"><strong>ignoreLocalSshSettings</strong></span></p></td><td style="border-bottom: 0.5pt 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: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><span class="strong"><strong>privateKey</strong></span></p></td><td style="border-bottom: 0.5pt 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: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><span class="strong"><strong>hostKey</strong></span></p></td><td style="border-bottom: 0.5pt 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: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><span class="strong"><strong>hostKeyAlgorithm</strong></span></p></td><td style="border-bottom: 0.5pt 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: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><span class="strong"><strong>strictHostKeyChecking</strong></span></p></td><td style="border-bottom: 0.5pt 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: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><span class="strong"><strong>knownHostsFile</strong></span></p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Location of custom <code class="literal">.known_hosts</code> file.</p></td></tr><tr><td style="border-right: 0.5pt 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
|
||||
-----END RSA PRIVATE KEY-----</pre><p>The following table describes the SSH configuration properties.</p><div class="table"><a name="d0e631" href="#d0e631"></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>:
|
||||
@@ -246,7 +246,7 @@ By default, they are put in the system temporary directory with a prefix of <cod
|
||||
On linux, for example, it could be <code class="literal">/tmp/config-repo-<randomid></code>.
|
||||
Some operating systems <a class="link" href="http://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 “native” 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 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>).
|
||||
@@ -255,12 +255,12 @@ To use it in production, you need to be sure that the file system is reliable an
|
||||
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><p>Vault is a tool for securely accessing secrets.
|
||||
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://www.vaultproject.io/intro/index.html" 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 style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; "><colgroup><col class="col_1"><col class="col_2"></colgroup><thead><tr><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">Name</th><th style="border-bottom: 0.5pt solid ; " align="left" valign="top">Default Value</th></tr></thead><tbody><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>host</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>127.0.0.1</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>port</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>8200</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>scheme</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>http</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>backend</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>secret</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>defaultKey</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>application</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>profileSeparator</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>,</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>kvVersion</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>skipSslValidation</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td></tr><tr><td style="border-right: 0.5pt solid ; " align="left" valign="top"><p>timeout</p></td><td style="" align="left" valign="top"><p>5</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>.</p></td></tr></table></div><p>All configurable properties can be found in <code class="literal">org.springframework.cloud.config.server.environment.VaultEnvironmentRepository</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>With your config server running, you can make HTTP requests to the server to retrieve
|
||||
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 ; " align="left" valign="top"><p>timeout</p></td><td style="" align="left" valign="top"><p>5</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>.</p></td></tr></table></div><p>All configurable properties can be found in <code class="literal">org.springframework.cloud.config.server.environment.VaultEnvironmentRepository</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>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 write secret/application foo=bar baz=bam
|
||||
$ vault write 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>
|
||||
@@ -292,7 +292,7 @@ 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.8 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="d0e1086" href="#d0e1086"></a><p class="title"><b>Table 2.2. Proxy Configuration Properties</b></p><div class="table-contents"><table summary="Proxy Configuration Properties" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; "><colgroup><col class="col_1"><col class="col_2"></colgroup><thead><tr><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">Property Name</th><th style="border-bottom: 0.5pt solid ; " align="left" valign="top">Remarks</th></tr></thead><tbody><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><span class="strong"><strong>host</strong></span></p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The host of the proxy.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><span class="strong"><strong>port</strong></span></p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The port with which to access the proxy.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><span class="strong"><strong>nonProxyHosts</strong></span></p></td><td style="border-bottom: 0.5pt 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: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><span class="strong"><strong>username</strong></span></p></td><td style="border-bottom: 0.5pt 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: 0.5pt 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>:
|
||||
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.8 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="d0e1113" href="#d0e1113"></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>:
|
||||
@@ -308,7 +308,7 @@ When <code class="literal">myApp</code> has the <code class="literal">dev</code>
|
||||
<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 “native” profile (a local file system backend) , you should use an explicit search location that is not part of the server’s own configuration.
|
||||
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><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>.
|
||||
@@ -353,7 +353,7 @@ The priority order of a repository helps resolve any potential conflicts between
|
||||
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.9 Property Overrides</h3></div></div></div><p>The Config Server has an “overrides” feature that lets the operator provide configuration properties to all applications.
|
||||
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.9 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>:
|
||||
@@ -377,9 +377,9 @@ By default, it asks the <code class="literal">EnvironmentRepository</code> for a
|
||||
<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 “Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files” 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 “at rest” (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 “not applicable” (usually <code class="literal"><n/a></code>).
|
||||
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>:
|
||||
@@ -402,7 +402,7 @@ mysecret</pre><p>To use a key in a file (such as an RSA public key for encryptio
|
||||
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><p>To configure an asymmetric key, you can either set the key as a PEM-encoded text value (in <code class="literal">encrypt.key</code>) or use a keystore (such as the keystore created by the <code class="literal">keytool</code> utility that comes with the JDK).
|
||||
The following table describes the keystore properties:</p><div class="informaltable"><table style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; "><colgroup><col class="col_1"><col class="col_2"></colgroup><thead><tr><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="top">Property</th><th style="border-bottom: 0.5pt solid ; " align="center" valign="top">Description</th></tr></thead><tbody><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><code class="literal">encrypt.keyStore.location</code></p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Contains a <code class="literal">Resource</code> location</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><code class="literal">encrypt.keyStore.password</code></p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Holds the password that unlocks the keystore</p></td></tr><tr><td style="border-right: 0.5pt solid ; " align="left" valign="top"><p><code class="literal">encrypt.keyStore.alias</code></p></td><td style="" align="left" valign="top"><p>Identifies which key in the store to use</p></td></tr></tbody></table></div><p>The encryption is done with the public key, and a private key is
|
||||
The following table describes the keystore 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="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 ; " align="left" valign="top"><p><code class="literal">encrypt.keyStore.alias</code></p></td><td style="" align="left" valign="top"><p>Identifies which key in the store to use</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
|
||||
|
||||
Reference in New Issue
Block a user