214 lines
11 KiB
Plaintext
214 lines
11 KiB
Plaintext
// Do not edit this file (e.g. go instead to src/main/asciidoc)
|
|
|
|
image::https://travis-ci.org/spring-cloud/spring-cloud-consul.svg?branch=master[Build Status, link=https://travis-ci.org/spring-cloud/spring-cloud-consul]
|
|
|
|
This project provides Consul integrations for Spring Boot apps through autoconfiguration
|
|
and binding to the Spring Environment and other Spring programming model idioms. With a few
|
|
simple annotations you can quickly enable and configure the common patterns inside your
|
|
application and build large distributed systems with Consul based components. The
|
|
patterns provided include Service Discovery, Control Bus and Configuration.
|
|
Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon), Circuit Breaker
|
|
(Hystrix) are provided by integration with Spring Cloud Netflix.
|
|
|
|
|
|
== Consul overview
|
|
|
|
Features of Consul
|
|
|
|
* Distributed configuration
|
|
* Service registration and discovery
|
|
* Distributed events
|
|
* Distributed locking and sessions
|
|
* Supports multiple data centers
|
|
* Built in, user-friendly user interface
|
|
|
|
See the https://consul.io/intro/index.html[intro] for more information.
|
|
|
|
== Spring Cloud Consul Features
|
|
|
|
* Spring Cloud `DiscoveryClient` implementation
|
|
** supports Ribbon and Zuul
|
|
* Consul based `PropertySource` loaded during the 'bootstrap' phase.
|
|
* Spring Cloud Bus implementation based on Consul https://www.consul.io/docs/agent/http/event.html[events]
|
|
|
|
== Running the sample
|
|
|
|
1. Run `docker-compose up`
|
|
2. Verify consul is running by visiting http://localhost:8500
|
|
3. Run `mvn package` this will bring in the required spring cloud maven repositories and build
|
|
4. Run `java -jar spring-cloud-consul-sample/target/spring-cloud-consul-sample-1.0.0.BUILD-SNAPSHOT.jar`
|
|
5. visit http://localhost:8080, verify that `{"serviceId":"<yourhost>:8080","host":"<yourhost>","port":8080}` results
|
|
6. run `java -jar spring-cloud-consul-sample/target/spring-cloud-consul-sample-1.0.0.BUILD-SNAPSHOT.jar --server.port=8081`
|
|
7. visit http://localhost:8080 again, verify that `{"serviceId":"<yourhost>:8081","host":"<yourhost>","port":8081}` eventually shows up in the results in a round robbin fashion (may take a minute or so).
|
|
|
|
== Building
|
|
|
|
:jdkversion: 1.7
|
|
|
|
=== Basic Compile and Test
|
|
|
|
To build the source you will need to install JDK {jdkversion}.
|
|
|
|
Spring Cloud uses Maven for most build-related activities, and you
|
|
should be able to get off the ground quite quickly by cloning the
|
|
project you are interested in and typing
|
|
|
|
----
|
|
$ ./mvnw install
|
|
----
|
|
|
|
NOTE: You can also install Maven (>=3.3.3) yourself and run the `mvn` command
|
|
in place of `./mvnw` in the examples below. If you do that you also
|
|
might need to add `-P spring` if your local Maven settings do not
|
|
contain repository declarations for spring pre-release artifacts.
|
|
|
|
NOTE: Be aware that you might need to increase the amount of memory
|
|
available to Maven by setting a `MAVEN_OPTS` environment variable with
|
|
a value like `-Xmx512m -XX:MaxPermSize=128m`. We try to cover this in
|
|
the `.mvn` configuration, so if you find you have to do it to make a
|
|
build succeed, please raise a ticket to get the settings added to
|
|
source control.
|
|
|
|
For hints on how to build the project look in `.travis.yml` if there
|
|
is one. There should be a "script" and maybe "install" command. Also
|
|
look at the "services" section to see if any services need to be
|
|
running locally (e.g. mongo or rabbit). Ignore the git-related bits
|
|
that you might find in "before_install" since they're related to setting git
|
|
credentials and you already have those.
|
|
|
|
The projects that require middleware generally include a
|
|
`docker-compose.yml`, so consider using
|
|
http://compose.docker.io/[Docker Compose] to run the middeware servers
|
|
in Docker containers. See the README in the
|
|
https://github.com/spring-cloud-samples/scripts[scripts demo
|
|
repository] for specific instructions about the common cases of mongo,
|
|
rabbit and redis.
|
|
|
|
NOTE: If all else fails, build with the command from `.travis.yml` (usually
|
|
`./mvnw install`).
|
|
|
|
=== Documentation
|
|
|
|
The spring-cloud-build module has a "docs" profile, and if you switch
|
|
that on it will try to build asciidoc sources from
|
|
`src/main/asciidoc`. As part of that process it will look for a
|
|
`README.adoc` and process it by loading all the includes, but not
|
|
parsing or rendering it, just copying it to `${main.basedir}`
|
|
(defaults to `${basedir}`, i.e. the root of the project). If there are
|
|
any changes in the README it will then show up after a Maven build as
|
|
a modified file in the correct place. Just commit it and push the change.
|
|
|
|
=== Working with the code
|
|
If you don't have an IDE preference we would recommend that you use
|
|
http://www.springsource.com/developer/sts[Spring Tools Suite] or
|
|
http://eclipse.org[Eclipse] when working with the code. We use the
|
|
http://eclipse.org/m2e/[m2eclipe] eclipse plugin for maven support. Other IDEs and tools
|
|
should also work without issue as long as they use Maven 3.3.3 or better.
|
|
|
|
==== Importing into eclipse with m2eclipse
|
|
We recommend the http://eclipse.org/m2e/[m2eclipe] eclipse plugin when working with
|
|
eclipse. If you don't already have m2eclipse installed it is available from the "eclipse
|
|
marketplace".
|
|
|
|
NOTE: Older versions of m2e do not support Maven 3.3, so once the
|
|
projects are imported into Eclipse you will also need to tell
|
|
m2eclipse to use the right profile for the projects. If you
|
|
see many different errors related to the POMs in the projects, check
|
|
that you have an up to date installation. If you can't upgrade m2e,
|
|
add the "spring" profile to your `settings.xml`. Alternatively you can
|
|
copy the repository settings from the "spring" profile of the parent
|
|
pom into your `settings.xml`.
|
|
|
|
==== Importing into eclipse without m2eclipse
|
|
If you prefer not to use m2eclipse you can generate eclipse project metadata using the
|
|
following command:
|
|
|
|
[indent=0]
|
|
----
|
|
$ ./mvnw eclipse:eclipse
|
|
----
|
|
|
|
The generated eclipse projects can be imported by selecting `import existing projects`
|
|
from the `file` menu.
|
|
|
|
|
|
==== Adding Project Lombok Agent
|
|
|
|
Spring Cloud uses http://projectlombok.org/features/index.html[Project Lombok]
|
|
to generate getters and setters etc. Compiling from the command line this
|
|
shouldn't cause any problems, but in an IDE you need to add an agent
|
|
to the JVM. Full instructions can be found in the Lombok website. The
|
|
sign that you need to do this is a lot of compiler errors to do with
|
|
missing methods and fields, e.g.
|
|
|
|
[indent=0]
|
|
----
|
|
The method getInitialStatus() is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 120 Java Problem
|
|
The method getInitialStatus() is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 121 Java Problem
|
|
The method setNonSecurePort(int) is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 112 Java Problem
|
|
The type EurekaInstanceConfigBean.IdentifyingDataCenterInfo must implement the inherited abstract method DataCenterInfo.getName() EurekaInstanceConfigBean.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 131 Java Problem
|
|
The method getId() is undefined for the type ProxyRouteLocator.ProxyRouteSpec PreDecorationFilter.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/zuul/filters/pre line 60 Java Problem
|
|
The method getLocation() is undefined for the type ProxyRouteLocator.ProxyRouteSpec PreDecorationFilter.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/zuul/filters/pre line 55 Java Problem
|
|
----
|
|
|
|
==== Importing into Intellij
|
|
Spring Cloud projects use annotation processing, particularly Lombok, which requires configuration
|
|
or you will encounter compile problems. It also needs a specific version of maven and a profile
|
|
enabled. Intellij 14.1+ requires some configuration to ensure these are setup properly.
|
|
|
|
1. Click Preferences, Plugins. *Ensure Lombok is installed*
|
|
2. Click New, Project from Existing Sources, choose your spring-cloud project directory
|
|
3. Choose Maven, and select Environment Settings. *Ensure you are using Maven 3.3.3*
|
|
4. In the next screen, *Select the profile `spring`* click Next until Finish.
|
|
5. Click Preferences, "Build, Execution, Deployment", Compiler, Annotation Processors. *Click Enable Annotation Processing*
|
|
6. Click Build, Rebuild Project, and you are ready to go!
|
|
|
|
==== Importing into other IDEs
|
|
Maven is well supported by most Java IDEs. Refer to you vendor documentation.
|
|
|
|
== Contributing
|
|
|
|
Spring Cloud is released under the non-restrictive Apache 2.0 license,
|
|
and follows a very standard Github development process, using Github
|
|
tracker for issues and merging pull requests into master. If you want
|
|
to contribute even something trivial please do not hesitate, but
|
|
follow the guidelines below.
|
|
|
|
=== Sign the Contributor License Agreement
|
|
Before we accept a non-trivial patch or pull request we will need you to sign the
|
|
https://support.springsource.com/spring_committer_signup[contributor's agreement].
|
|
Signing the contributor's agreement does not grant anyone commit rights to the main
|
|
repository, but it does mean that we can accept your contributions, and you will get an
|
|
author credit if we do. Active contributors might be asked to join the core team, and
|
|
given the ability to merge pull requests.
|
|
|
|
=== Code of Conduct
|
|
This project adheres to the Contributor Covenant https://github.com/spring-cloud/spring-cloud-build/blob/master/docs/src/main/asciidoc/code-of-conduct.adoc[code of
|
|
conduct]. By participating, you are expected to uphold this code. Please report
|
|
unacceptable behavior to spring-code-of-conduct@pivotal.io.
|
|
|
|
=== Code Conventions and Housekeeping
|
|
None of these is essential for a pull request, but they will all help. They can also be
|
|
added after the original pull request but before a merge.
|
|
|
|
* Use the Spring Framework code format conventions. If you use Eclipse
|
|
you can import formatter settings using the
|
|
`eclipse-code-formatter.xml` file from the
|
|
https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-dependencies-parent/eclipse-code-formatter.xml[Spring
|
|
Cloud Build] project. If using IntelliJ, you can use the
|
|
http://plugins.jetbrains.com/plugin/6546[Eclipse Code Formatter
|
|
Plugin] to import the same file.
|
|
* Make sure all new `.java` files to have a simple Javadoc class comment with at least an
|
|
`@author` tag identifying you, and preferably at least a paragraph on what the class is
|
|
for.
|
|
* Add the ASF license header comment to all new `.java` files (copy from existing files
|
|
in the project)
|
|
* Add yourself as an `@author` to the .java files that you modify substantially (more
|
|
than cosmetic changes).
|
|
* Add some Javadocs and, if you change the namespace, some XSD doc elements.
|
|
* A few unit tests would help a lot as well -- someone has to do it.
|
|
* If no-one else is using your branch, please rebase it against the current master (or
|
|
other target branch in the main project).
|
|
* When writing a commit message please follow http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[these conventions],
|
|
if you are fixing an existing issue please add `Fixes gh-XXXX` at the end of the commit
|
|
message (where XXXX is the issue number). |