SpringCloud/spring-cloud-config
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Move docs to submodule for multi-module projects

Browse Source
This commit is contained in:
Dave Syer
2014-10-06 14:58:44 +01:00
parent a9a97d9351
commit 548157ef97
11 changed files with 255 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

205
docs/README.adoc Normal file
View File

@@ -0,0 +1,205 @@
// Do not edit this file (e.g. go instead to src/main/asciidoc)
Spring Cloud Config provides server and client-side support for externalized configuration in a distributed system. With the Config Server you have a central place to manage external properties for applications across all environments. The concepts on both client and server map identically to the Spring `Environment` and `PropertySource` abstractions, so they fit very well with Spring applications, but can be used with any application running in any language. As an application moves through the deployment pipeline from dev to test and into production you can manage the configuration between those environments and be certain that applications have everything they need to run when they migrate. The default implementation of the server storage backend uses git so it easily supports labelled versions of configuration environments, as well as being accessible to a wide range of tooling for managing the content. It is easy to add alternative implementations and plug them in with Spring configuration.
== Features
=== Spring Cloud Config Server
* HTTP, resource-based API for external configuration (name-value pairs, or equivalent YAML content)
* Encrypt and decrypt property values (symmetric or asymmetric)
* Embeddable easily in a Spring Boot application using `@EnableConfigServer`
=== Spring Cloud Config Client
Specifically for Spring applications:
* Bind to the Config Server and initialize Spring `Environment` with remote property sources
* Encrypt and decrypt property values (symmetric or asymmetric)
* `@RefreshScope` for Spring `@Beans` that want to be re-initialized when configuration changes
* Management endpoints:
** `/env` for updating `Environment` and rebinding `@ConfigurationProperties` and log levels
** `/refresh` for refreshing the `@RefreshScope` beans
** `/restart` for restarting the Spring context (disabled by default)
** `/pause` and `/resume` for calling the `Lifecycle` methods (`stop()` and `start()` on the `ApplicationContext`)
* Bootstrap appplication context: a parent context for the main application that can be trained to do anything (by default it binds to the Config Server, and decrypts property values)
== Quick Start
Start the server:
----
$ cd spring-cloud-config-server
$ mvn spring-boot:run
----
The server is a Spring Boot application so you can build the jar file
and run that (`java -jar ...`) or pull it down from a Maven
repository. Then try it out as a client:
----
$ curl localhost:8888/foo/development
{"name":"development","label":"master","propertySources":[
{"name":"https://github.com/scratches/config-repo/foo-development.properties","source":{"bar":"spam"}},
{"name":"https://github.com/scratches/config-repo/foo.properties","source":{"foo":"bar"}}
]}
----
The default strategy for locating property sources is to clone a git
repository (at "spring.platform.config.server.uri") and use it to
initialize a mini `SpringApplication`. The mini-application's
`Environment` is used to enumerate property sources and publish them
via a JSON endpoint. The service has resources in the form:
----
/{application}/{profile}[/{label}]
----
where the "application" is injected as the "spring.config.name" in the
`SpringApplication` (i.e. what is normally "application" in a regular
Spring Boot app), "profile" is an active profile (or comma-separated
list of properties), and "label" is an optional git label (defaults to
"master").
=== Client Side Usage
To use these features in an application, just build it as a Spring
Boot application that depends on spring-cloud-config-client (e.g. see
the test cases for the config-client, or the sample app). The most
convenient way to add the dependency is via a Spring Boot starter
`org.springframework.cloud:spring-cloud-starter`. There is also a
parent pom and BOM (`spring-cloud-starters`) for Maven users and a
Spring IO version management properties file for Gradle and Spring CLI
users. Example Maven configuration:
[source,xml,indent=0]
.pom.xml
----
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.1.7.RELEASE</version>
<relativePath /> <!-- lookup parent from repository -->
</parent>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starters</artifactId>
<version>1.0.0.BUILD-SNAPSHOT</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
<!-- repositories also needed for snapshots and milestones -->
----
Then you can create a standard Spring Boot application, like this simple HTTP server:
----
@Configuration
@EnableAutoConfiguration
@RestController
public class Application {
@RequestMapping("/")
public String home() {
return "Hello World!";
}
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
----
When it runs it will pick up the external configuration from the
default local config server on port 8888 if it is running. To modify
the startup behaviour you can change the location of the config server
using `bootstrap.properties` (like `application.properties` but for
the bootstrap phase of an application context), e.g.
----
spring.cloud.config.uri: http://myconfigserver.com
----
The bootstrap properties will show up in the `/env` endpoint as a
high-priority property source, e.g.
----
$ curl localhost:8080/env
{
"profiles":[],
"configService:https://github.com/scratches/config-repo/bar.properties":{"foo":"bar"},
"servletContextInitParams":{},
"systemProperties":{...},
...
}
----
(a property source called "configService:<URL of remote
repository>/<file name>" contains the property "foo" with value
"bar" and is highest priority).
=== Sample Application
There is a sample application
https://github.com/spring-cloud/spring-cloud-config/tree/master/spring-cloud-config-sample[here]. It
is a Spring Boot application so you can run it using the usual
mechanisms (for instance "mvn spring-boot:run"). When it runs it will
look for the config server on "http://localhost:8888" by default, so
you could run the server as well to see it all working together.
The sample has a test case where the config server is also started in
the same JVM (with a different port), and the test asserts that an
environment property from the git configuration repo is present. To
change the location of the config server just set
"spring.platform.config.uri" in "bootstrap.yml" (or via System
properties etc.).
The test case has a `main()` method that runs the server in the same
way (watch the logs for its port), so you can run the whole system in
one process and play with it (e.g. right click on the main in your IDE
and run it). The `main()` method uses `target/config` for the working
directory of the git repository, so you can make local changes there
and see them reflected in the running app.
----
$ curl localhost:8080/env/foo
bar
$ vi target/config/bar.properties
.. change value of "foo", optionally commit
$ curl localhost:8080/refresh
["foo"]
$ curl localhost:8080/env/foo
baz
----
The refresh endpoint reports that the "foo" property changed.

44
docs/pom.xml Normal file
View File

@@ -0,0 +1,44 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-config-docs</artifactId>
<version>1.0.0.BUILD-SNAPSHOT</version>
<parent>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-build</artifactId>
<version>1.0.0.BUILD-SNAPSHOT</version>
<relativePath/>
</parent>
<packaging>pom</packaging>
<name>Spring Cloud Config Docs</name>
<description>Spring Cloud Docs</description>
<properties>
<docs.main>spring-cloud-config</docs.main>
<main.basedir>${basedir}/..</main.basedir>
</properties>
<profiles>
<profile>
<id>docs</id>
<build>
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<inherited>false</inherited>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId>
<inherited>false</inherited>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<inherited>false</inherited>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>

64
docs/src/main/asciidoc/README.adoc Normal file
View File

@@ -0,0 +1,64 @@
include::intro.adoc[]
== Features
=== Spring Cloud Config Server
* HTTP, resource-based API for external configuration (name-value pairs, or equivalent YAML content)
* Encrypt and decrypt property values (symmetric or asymmetric)
* Embeddable easily in a Spring Boot application using `@EnableConfigServer`
=== Spring Cloud Config Client
Specifically for Spring applications:
* Bind to the Config Server and initialize Spring `Environment` with remote property sources
* Encrypt and decrypt property values (symmetric or asymmetric)
* `@RefreshScope` for Spring `@Beans` that want to be re-initialized when configuration changes
* Management endpoints:
** `/env` for updating `Environment` and rebinding `@ConfigurationProperties` and log levels
** `/refresh` for refreshing the `@RefreshScope` beans
** `/restart` for restarting the Spring context (disabled by default)
** `/pause` and `/resume` for calling the `Lifecycle` methods (`stop()` and `start()` on the `ApplicationContext`)
* Bootstrap appplication context: a parent context for the main application that can be trained to do anything (by default it binds to the Config Server, and decrypts property values)
== Quick Start
include::quickstart.adoc[]
=== Sample Application
There is a sample application
https://github.com/spring-cloud/spring-cloud-config/tree/master/spring-cloud-config-sample[here]. It
is a Spring Boot application so you can run it using the usual
mechanisms (for instance "mvn spring-boot:run"). When it runs it will
look for the config server on "http://localhost:8888" by default, so
you could run the server as well to see it all working together.
The sample has a test case where the config server is also started in
the same JVM (with a different port), and the test asserts that an
environment property from the git configuration repo is present. To
change the location of the config server just set
"spring.platform.config.uri" in "bootstrap.yml" (or via System
properties etc.).
The test case has a `main()` method that runs the server in the same
way (watch the logs for its port), so you can run the whole system in
one process and play with it (e.g. right click on the main in your IDE
and run it). The `main()` method uses `target/config` for the working
directory of the git repository, so you can make local changes there
and see them reflected in the running app.
----
$ curl localhost:8080/env/foo
bar
$ vi target/config/bar.properties
.. change value of "foo", optionally commit
$ curl localhost:8080/refresh
["foo"]
$ curl localhost:8080/env/foo
baz
----
The refresh endpoint reports that the "foo" property changed.

46
docs/src/main/asciidoc/ghpages.sh Executable file
View File

@@ -0,0 +1,46 @@
#!/bin/bash -x
git remote set-url --push origin `git config remote.origin.url | sed -e 's/^git:/https:/'`
if ! (git remote set-branches --add origin gh-pages && git fetch -q); then
echo "No gh-pages, so not syncing"
exit 0
fi
if ! [ -d docs/target/generated-docs ]; then
echo "No gh-pages sources in docs/target/generated-docs, so not syncing"
exit 0
fi
# Stash any outstanding changes
###################################################################
git diff-index --quiet HEAD
dirty=$?
if [ "$dirty" != "0" ]; then git stash; fi
# Switch to gh-pages branch to sync it with master
###################################################################
git checkout gh-pages
for f in docs/target/generated-docs/*; do
file=${f#docs/target/generated-docs/*}
if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then
# Not ignored...
cp -rf $f .
git add -A $file
fi
done
git commit -a -m "Sync docs from master to gh-pages"
# Uncomment the following push if you want to auto push to
# the gh-pages branch whenever you commit to master locally.
# This is a little extreme. Use with care!
###################################################################
git push origin gh-pages
# Finally, switch back to the master branch and exit block
git checkout master
if [ "$dirty" != "0" ]; then git stash pop; fi
exit 0

2
docs/src/main/asciidoc/intro.adoc Normal file
View File

@@ -0,0 +1,2 @@
Spring Cloud Config provides server and client-side support for externalized configuration in a distributed system. With the Config Server you have a central place to manage external properties for applications across all environments. The concepts on both client and server map identically to the Spring `Environment` and `PropertySource` abstractions, so they fit very well with Spring applications, but can be used with any application running in any language. As an application moves through the deployment pipeline from dev to test and into production you can manage the configuration between those environments and be certain that applications have everything they need to run when they migrate. The default implementation of the server storage backend uses git so it easily supports labelled versions of configuration environments, as well as being accessible to a wide range of tooling for managing the content. It is easy to add alternative implementations and plug them in with Spring configuration.

139
docs/src/main/asciidoc/quickstart.adoc Normal file
View File

@@ -0,0 +1,139 @@
Start the server:
----
$ cd spring-cloud-config-server
$ mvn spring-boot:run
----
The server is a Spring Boot application so you can build the jar file
and run that (`java -jar ...`) or pull it down from a Maven
repository. Then try it out as a client:
----
$ curl localhost:8888/foo/development
{"name":"development","label":"master","propertySources":[
{"name":"https://github.com/scratches/config-repo/foo-development.properties","source":{"bar":"spam"}},
{"name":"https://github.com/scratches/config-repo/foo.properties","source":{"foo":"bar"}}
]}
----
The default strategy for locating property sources is to clone a git
repository (at "spring.platform.config.server.uri") and use it to
initialize a mini `SpringApplication`. The mini-application's
`Environment` is used to enumerate property sources and publish them
via a JSON endpoint. The service has resources in the form:
----
/{application}/{profile}[/{label}]
----
where the "application" is injected as the "spring.config.name" in the
`SpringApplication` (i.e. what is normally "application" in a regular
Spring Boot app), "profile" is an active profile (or comma-separated
list of properties), and "label" is an optional git label (defaults to
"master").
=== Client Side Usage
To use these features in an application, just build it as a Spring
Boot application that depends on spring-cloud-config-client (e.g. see
the test cases for the config-client, or the sample app). The most
convenient way to add the dependency is via a Spring Boot starter
`org.springframework.cloud:spring-cloud-starter`. There is also a
parent pom and BOM (`spring-cloud-starters`) for Maven users and a
Spring IO version management properties file for Gradle and Spring CLI
users. Example Maven configuration:
[source,xml,indent=0]
.pom.xml
----
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.1.7.RELEASE</version>
<relativePath /> <!-- lookup parent from repository -->
</parent>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starters</artifactId>
<version>1.0.0.BUILD-SNAPSHOT</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
<!-- repositories also needed for snapshots and milestones -->
----
Then you can create a standard Spring Boot application, like this simple HTTP server:
----
@Configuration
@EnableAutoConfiguration
@RestController
public class Application {
@RequestMapping("/")
public String home() {
return "Hello World!";
}
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
----
When it runs it will pick up the external configuration from the
default local config server on port 8888 if it is running. To modify
the startup behaviour you can change the location of the config server
using `bootstrap.properties` (like `application.properties` but for
the bootstrap phase of an application context), e.g.
----
spring.cloud.config.uri: http://myconfigserver.com
----
The bootstrap properties will show up in the `/env` endpoint as a
high-priority property source, e.g.
----
$ curl localhost:8080/env
{
"profiles":[],
"configService:https://github.com/scratches/config-repo/bar.properties":{"foo":"bar"},
"servletContextInitParams":{},
"systemProperties":{...},
...
}
----
(a property source called "configService:<URL of remote
repository>/<file name>" contains the property "foo" with value
"bar" and is highest priority).

299
docs/src/main/asciidoc/spring-cloud-config.adoc Normal file
View File

@@ -0,0 +1,299 @@
= Spring Cloud Config
:toc:
include::intro.adoc[]
== Quick Start
include::quickstart.adoc[]
== Spring Cloud Config Server
The Server provides an HTTP, resource-based API for external
configuration (name-value pairs, or equivalent YAML content). The
server is easily embeddable in a Spring Boot application using the
`@EnableConfigServer` annotation.
=== Encryption and Decryption
IMPORTANT: **Prerequisites:** to use the encryption and decryption features
you need the full-strength JCE installed in your JVM (it's not there by default).
You can download the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files"
from Oracle, and follow instructions for installation (essentially replace the 2 policy files
in the JRE lib/security directory with the ones that you downloaded).
The server exposes `/encrypt` and `/decrypt` endpoints (on the
assumption that these will be secured and only accessed by authorized
agents). If the remote property sources contain encryted content
(values starting with `{cipher}`) they will be decrypted before
sending to clients over HTTP. The main advantage of this set up is
that the property values don't have to be in plain text when they are
"at rest" (e.g. in a git repository).
If you are setting up a remote config repository for config client
applications it might contain an `application.yml` like this, for
instance:
.application.yml
----
spring:
datasource:
username: dbuser
password: {cipher}FKSAJDFGYOS8F7GLHAKERGFHLSAJ
----
You can safely push this plain text to a shared git repository and the
secret password is protected.
If you are editing a remote config file you can use the Config Server
to encrypt values by POSTing to the `/encrypt` endpoint, e.g.
----
$ curl localhost:8888/encrypt -d mysecret
682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
----
The inverse operation is also available via `/decrypt` (provided the server is
configured with a symmetric key or a full key pair):
----
$ curl localhost:8888/edecrypt -d 682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
mysecret
----
Take the encypted value and add the `{cipher}` prefix before you put
it in the YAML or properties file, and before you commit and push it
to a remote, potentially insecure store.
The `spring` command line client (with Spring Cloud CLI extensions
installed) can also be used to encrypt and decrypt, e.g.
----
$ spring encrypt mysecret --key foo
682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
$ spring decrypt --key foo 682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
mysecret
----
To use a key in a file (e.g. an RSA public key for encyption) prepend
the key value with "@" and provide the file path, e.g.
----
$ spring encrypt mysecret --key @${HOME}/.ssh/id_rsa.pub
AQAjPgt3eFZQXwt8tsHAVv/QHiY5sI2dRcR+...
----
=== Key Management
The Config Server can use a symmetric (shared) key or an asymmetric
one (RSA key pair). The asymmetric choice is superior in terms of
security, but it is often more convenient to use a symmetric key since
it is just a single property value to configure.
To configure a symmetric key you just need to set `encrypt.key` to a
secret String (or use an enviroment variable `ENCRYPT_KEY` to keep it
out of plain text configuration files). You can also POST a key value
to the `/key` endpoint (but that won't change any existing encrypted
values in remote repositories).
To configure an asymmetric key you can either set the key as a
PEM-encoded text value (in `encrypt.key`), or via a keystore (e.g. as
created by the `keytool` utility that comes with the JDK). The
keystore properties are `encrypt.keyStore.\*` with `*` equal to
* `location` (a `Resource` location),
* `password` (to unlock the keystore) and
* `alias` (to identify which key in the store is to be
used).
The encryption is done with the public key, and a private key is
needed for decryption. Thus in principle you can configure only the
public key in the server if you only want to do encryption (and are
prepared to decrypt the values yourself locally with the private
key). In practice you might not want to do that because it spreads the
key management process around all the clients, instead of
concentrating it in the server. On the other hand it's a useful option
if your config server really is relatively insecure and only a
handful of clients need the encrypted properties.
=== Creating a Key Store for Testing
To create a keystore for testing you can do something like this:
----
$ 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
----
Put the `server.jks` file in the classpath (for instance) and then in
your `application.yml` for the Config Server:
----
encrypt:
keyStore:
location: classpath:/server.jks
alias: mytestkey
password: letmein
----
== Spring Cloud Config Client
A Spring Boot application can take immediate advantage of the Spring
Config Server (or other external property sources provided by the
application developer), and it will also pick up some additional
useful features related to `Environment` change events. When a config
client starts up it binds to the Config Server (via the bootstrap
configuration property `spring.cloud.config.uri`) and initializes
Spring `Environment` with remote property sources
=== Environment Changes
The application will listen for an `EnvironmentChangedEvent` and react
to the change in a couple of standard ways (additional
`ApplicationListeners` can be added as `@Beans` by the user in the
normal way). When an `EnvironmentChangedEvent` is observed it will
have a list of key values that have changed, and the application will
use those to:
* Re-bind any `@ConfigurationProperties` beans in the context
* Set the logger levels for any properties in `logging.level.*`
This covers a large class of refresh use cases, and you can verify the
changes by visiting the `/configprops` endpoint (normal Spring Boot
Actuator feature). For instance a `DataSource` can have its
`maxPoolSize` changed at runtime (the default `DataSource` created by
Spring Boot is an `@ConfigurationProperties` bean) and grow capacity
dynamically. It does not cover another large class of use cases, where
you need more control over the refresh, and where you need a
configuration change to be atomic over the whole
`ApplicationContext`. To address those concerns we have
`@RefreshScope`.
=== Refresh Scope
A Spring `@Bean` that is marked as `@RefreshScope` will get special
treatment when there is a configuration change. This addresses the
problem of stateful beans that only get their configuration injected
when they are initialized. For instance if a `DataSource` has open
connections when the database URL is changed via the `Environment`, we
probably want the holders of those connections to be able to complete
what they are doing. Then the next time someone borrows a connection
from the pool he gets one with the new URL.
Refresh scope beans are lazy proxies that initialize when they are
used (i.e. when a method is called), and the scope acts as a cache of
initialized values. To force a bean to re-initialize on the next
method call you just need to invalidate its cache entry.
The `RefreshScope` is a bean in the context and it has a public method
`refreshAll()` to refresh all beans in the scope by clearing the
target cache. There is also a `refresh(String)` method to refresh an
individual bean by name. This functionality is exposed in the
`/refresh` endpoint (over HTTP or JMX).
=== Encryption and Decryption
The Config Client has an `Environment` pre-processor for decrypting
property values locally. It follows the same rules as the Config
Server, and has the same external configuration via `encrypt.\*`. Thus
you can use encrypted values in the form `{cipher}*` and as long as
there is a valid key then they will be decrypted before the main
application context gets the `Environment`.
=== Endpoints
For a Spring Boot Actuator application there are some additional management endpoints:
* POST to `/env` to update the `Environment` and rebind `@ConfigurationProperties` and log levels
* `/refresh` for re-loading the boot strap context and refreshing the `@RefreshScope` beans
* `/restart` for closing the `ApplicationContext` and restarting it (disabled by default)
* `/pause` and `/resume` for calling the `Lifecycle` methods (`stop()` and `start()` on the `ApplicationContext`)
=== The Bootstrap Application Context
The Config Client operates by creating a "bootstrap" application
context, which is a parent context for the main application. Out of
the box it is responsible for loading configuration properties from
the Config Server, and also decrypting properties in the local
external configuration files. The two contexts share an `Environment`
which is the source of external properties for any Spring
application. Bootstrap properties are added with high precedence, so
they cannot be overridden by local configuration.
The bootstrap context uses a different convention for locating
external configuration than the main application context, so instead
of `application.yml` (or `.properties`) you use `bootstrap.yml`,
keeping the external configuration for bootstrap and main context
nicely separate. Example:
.bootstrap.yml
----
spring:
application:
name: foo
cloud:
config:
uri: ${SPRING_CONFIG_URI:http://localhost:8888}
----
It is a good idea to set the `spring.application.name` in
`bootstrap.yml` if your application needs any application-specific
configuration from the server.
You can disable the bootstrap process completely by setting
`spring.platform.bootstrap.enabled=false` (e.g. in System properties).
=== Customizing the Bootstrap
The bootstrap context can be trained to do anything you like by adding
entries to `/META-INF/spring.factories` under the key
`org.springframework.cloud.bootstrap.BootstrapConfiguration`. This is
a comma-separated list of Spring `@Configuration` classes which will
be used to create the context. Any beans that you want to be available
to the main application context for autowiring can be created here,
and also there is a special contract for `@Beans` of type
`ApplicationContextInitializer`.
The bootstrap process ends by injecting initializers into the main
`SpringApplication` instance (i.e. the normal Spring Boot startup
sequence, whether it is running as a standalone app or deployed in an
application server). First a bootstrap context is created from the
classes found in `spring.factories` and then all `@Beans` of type
`ApplicationContextInitializer` are added to the main
`SpringApplication` before it is started.
=== Customizing the Property Sources
The default property source for external configuration added by the
bootstrap process is the Config Server, but you can add additional
sources by adding beans of type `PropertySourceLocator` to the
bootstrap context (via `spring.factories`). You could use this to
insert additional properties from a different server, or from a
database, for instance.
As an example, consider the following trivial custom locator:
[source,java]
----
@Configuration
public class CustomPropertySourceLocator implements PropertySourceLocator {
@Override
public PropertySource<?> locate() {
return new MapPropertySource("customProperty",
Collections.<String, Object>singletonMap("property.from.sample.custom.source", "worked as intended"));
}
}
----
If you create a jar with this class in it and then add a
`META-INF/spring.factories` containing:
----
org.springframework.cloud.bootstrap.BootstrapConfiguration=sample.custom.CustomPropertySourceLocator
----
then the "customProperty" `PropertySource` will show up in any
application that includes that jar on its classpath.

19
docs/src/main/ruby/generate_readme.sh Executable file
View File

@@ -0,0 +1,19 @@
#!/usr/bin/env ruby
base_dir = File.join(File.dirname(__FILE__),'../../..')
src_dir = File.join(base_dir, "/src/main/asciidoc")
require File.join(File.dirname(__FILE__), 'readme.rb')
require 'optparse'
options = {}
input = "#{src_dir}/README.adoc"
OptionParser.new do |o|
o.on('-o OUTPUT_FILE', 'Output file (default is stdout)') { |file| options[:to_file] = file unless file=='-' }
o.on('-h', '--help') { puts o; exit }
o.parse!
end
input = ARGV[0] if ARGV.length>0
SpringCloud::Build.render_file(input, options)

54
docs/src/main/ruby/readme.rb Normal file
View File

@@ -0,0 +1,54 @@
require 'open-uri'
module SpringCloud
module Build
IncludeDirectiveRx = /^\\?include::([^\[]+)\[(.*?)\]$/
class << self
def process_include out, src, target, attrs
unless target.include?(':') || target.start_with?('/')
target = File.join(src, target)
end
open(target) do |file|
file.each do |line|
self.process(out, File.dirname(target), line)
end
end
end
def process out, src, line
if ((escaped = line.start_with?('\\include::')) || line.start_with?('include::')) && (match = IncludeDirectiveRx.match(line))
if escaped
out << line[1..-1]
else
self.process_include out, src, match[1], match[2].strip
end
else
out << line
end
end
def render_file file, options = {}
srcDir = File.dirname(file)
out = ["// Do not edit this file (e.g. go instead to src/main/asciidoc)\n","\n"]
File.new(file).each do |line|
self.process(out, srcDir, line)
end
unless options[:to_file]
puts out
else
File.open(options[:to_file],'w+') do |file|
out.each { |line| file.write(line) }
end
end
end
end
end
end