Rather than jakarta.ws.rs.client.ClientRequestFilter, use jakarta.ws.rs.client.ClientRequestFilter
Also exclude jersey-client rather than jaxrs api
See gh-4176
Fixes gh-4177
* Fix CSS and JS on Eureka Dashboard
The dashboard interface was broken after changes in
https://github.com/spring-cloud/spring-cloud-netflix/pull/4075.
Bootstrap has changed a lot since version 3.
This patch converts dashboard's CSS to Bootstrap v.5 API.
Also, remove unnecessary JavaScript. Table striping and tab activation
is done completely in Bootstrap now. While at it, remove IE support.
It is not supported in Bootstrap v.5 anymore.
* Fix dashboard navigation tests
Change RestTemplateTransportClientFactory to always build a RestTemplate
utilizing the provided EurekaClientHttpRequestFactorySupplier even when
the SSLContext is null (default case when eureka.client.tls.* properties
aren't configured/enabled). Ignore null SSLContext being passed to
DefaultEurekaClientHttpRequestFactorySupplier.get() to align with
behavior of HostnameVerifier parameter.
Fixes gh-3967
* Add tests reproducing the issue.
* Strip `'` from path for route search.
* Add information on contributing, community support and commercial support to project site.
* Add checking for "#". Add logging.
* Add test.
* Revert "Add test."
This reverts commit 81875849
* Revert "Add checking for "#". Add logging."
This reverts commit 0232945a
* Verify for urls.
* Verify for encoded and double-encoded Strings.
* Verify insecure paths with `..\` and '..//'. Add more tests.
This eliminates the oddness of having multiple discovery client beans and related behavior and simplifies bootstrap significantly.
Moves to ConfigServerInstanceProvider.Function for config client bootstrap.
Removes conditions for dealing with DiscoverClient in parent context.
Updates tests to reflect the new reality of no DiscoveryClient in bootstrap.
Renames config bootstrap to EurekaConfigServerBootstrapConfiguration
Fixes gh-3795
See https://github.com/spring-cloud/spring-cloud-gateway/issues/1514
a little excited but seeing the current module into the maintenance phase and not knowing if it will be merged, I would like to be involved in the spring community to contribute.
* fixed#3692 issue
fixed#3692 : Ribbon not getting list of servers from properties with lazy initialization
* Fixeds #3692 issue & add add test
* fix check style failed
If the original request has Accept-Encoding not set, the origin response may still be gzipped.
In that case (in which Zuul unzips the response), it must not set the Content-Encoding response header.
traceRequestBody requires the body to be buffered which reduces performance and can be problematic, such as when used in combination with `zuul.use-filter=true` and `zuul.servlet-path=/` See https://github.com/spring-cloud/spring-cloud-netflix/issues/3418
traceRequestBody should only be set when logging the request body is actually necessary.
If we repeatedly call String#replaceAll, we internally repeatedly call the regular expression pattern compilation every time as following:
```java
public String replaceAll(String regex, String replacement) {
return Pattern.compile(regex).matcher(this).replaceAll(replacement);
}
```
The modifications are to keep the compiled pattern.
Therefore, compiling a relatively expensive regular expression pattern does not have to be done every time.
Added `@ConditionalOnMissingBean` for `PreDecorationFilter`, `RibbonRoutingFilter` beans in `org.springframework.cloud.netflix.zuul.ZuulProxyAutoConfiguration` class.
* Always forward Content-Length from origin when set unless response is compressed and client does not support it
Fix for #2832
* Add test cases to assert behaviour with regards to the Content-Length header
* Retryable Clients should validate the service server and throw an exception if necessary
* fixing spelling error
* RetryableRibbonLoadBalancingClient should throw a ClientException which can be handled by the RibbonRoutingFilter
* moving service instance validation and service instance chooser to the AbstractLoadBalancingClient
* Updating RetryCallback within RetryableRibbonLoadBalancingHttpClient to handel Exception
* fix assertion check
* polish: replace the type specification in this constructor call with the diamond operator ("<>"),
make EUREKA_PACKAGES final to avoid issue "static non-final field names should comply with a naming convention"
Hopefully spring boot logging provides enough of the API for
Archaius to work (I think that's the only reason it was there).
Causes issues with logging switching to JUL at odd times (like
on context closed events).
* Adding protected getter to obtain CompositeHealthIndicator. This allows subclasses to obtain this indicator's health details map which is useful for error reporting.
* Added util method to upgrade the connection to a secure one.
- Adds support for websocket URIs
- Fixes bug where a non-secure scheme other than http would be changed to https
- Deprecated `updateToHttpsIfNeeded` in favor of `updateToSecureConnectionIfNeeded`
* Expect http when no scheme was set
* Skip update to secure connection when the uri is empty
* Add support loadBalancerKey in RibbonRoutingFilter
* Add documentation about how to provide a loadBalancerKey to Ribbon
* Add integrationtest for RibbonRoutingFilter's loadBalancerKey support
- The fix adds a necessary buffer between the rx-rs adapter and
the timeout operator introduced in AbstractCommand. Unfortunately,
the hystrix operator does not comply with RS backpressure requirements.
It will always request an unbounded demand to a source regardless of
the command consumer demand. With this commit we protect RS adapter and
downstream flow from overflow. Ideally a rework of the operator should
be planned.
In order to fix issue with TPS in hystrix-dashboard threadpool section, removing average calculation for propertyValue_metricsRollingStatisticalWindowInMilliseconds. This was done for hystrixCommand.js previously but not for hystrixThreadpool.js.
* Add new Zuul filters endpoint and refactor routes endpoint
* Refactor FiltersEndpoint
- Extend from AbstractEndpoint and simplify code
- Move tests classes into package endpoint
- Remove usage of Lombok
* Conditionally enable Zuul routes and filters endpoints
* Provide FilterRegistry to FiltersEndpoint via constructor
The message has to be sent after the endpoint starts up, which only
happens after the first request is accepted, so we put that logic
in the response extractor.
According to:
https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/bind/annotation/RequestMapping.html#headers--
the `headers` field can take several formats:
1. Require the header with a concrete value: `"My-Header=myValue"`
2. Require the header with any value: `"My-Header"`
3. Require the header is absent: `"!My-Header"`
4. Require the header with a negated value : `"My-Header!=myValue"`
This fixes `parseHeaders` for cases 2-4 (which previously threw a `StringIndexOutOfBoundsException`).
Fixes gh-1778.
Cause can now be propagated to fallback provider in order to respond accordingly to a exception type.
New interface is introduced in order not to break any existing falback providers.
On certain platforms and compilers the generated bytecode is not what
the configuration expected. By moving inner classes to the upper level
and using @Import this will guarantee the proper order.
fixes gh-2086
On certain platforms and compilers the generated bytecode is not what
the configuration expected. By moving inner classes to the upper level
and using @Import this will guarantee the proper order.
fixes gh-2086
Add a parameter to control the level of details returned with the
routes actuator endpoint. If requested, return all available Zuul route
details including ID, prefix, sensitive headers, etc.
Signed-off-by: Gregor Zurowski <gregor@zurowski.org>
* add feign client properties
* configure feign builder from properties if exists
* change string config to class config and add unit test for feign client using configuration properties
* refactoring and add primary flag configuration
* add decode404 in feign client configuration properties
* change unit test properties decode404 to true
* remove lombok from FeignClientProperties and change primary attribute to default-to-properties
fixes gh-1931
* Support for re-writing Location Headers
* Added additional constructor for Route, removed auto-configuration of LocationRewriteFilter
* Polished docs, more tests
* Add options for RibbonCommand to use separate thread pools for hystrix
* Remove lombok annotation and Add getter/setter for ZuulProperties$HystrixThreadPool
* Add doc about how to configure hystrix thread pools in Zuul Developer Guide
* Add testcases for HystrixThreadPoolKey of RibbonCommand
* Tiny change about if block in AbstractRibbonCommand
This allows clients to send batched up events in the same format as
before (or to continue to send single events). We can switch the
default format to an array in 1.4.x.
Previously, these were managed directly via archaius, but due to
some combination of changes in boot 1.5.x (likely a tomcat change as
zuul filters were initialzed in a servlet context listener) and Dalston,
The filter was created before archaius could be initialized.
The properties are backwards compatible and are in the
`ZuulProperties.Host` object.
fixes gh-1950
Let SecurityContextConcurrencyStrategy be installed as the hystrix
concurrency strategy regardless of if feign's hystrix support is installed.
fixes gh-1969
CounterFactory is used by ZuulException and was previously initialzed
with a dummy impl.
This adds a Spring Boot CounterService based implementation.
Also adds the ability to implement a zuul TracerFactory.
By default, `LoadBalancerBuilder` built a load-balancer with a `PollingServerListUpdater`. This change introduces a `ServerListUpdater` bean which creates a `PollingServerListUpdater(IClientConfig)` so that `ribbon.ServerListRefreshInterval` is respected.
fixes gh-1304
Fix a suspected typo. @Autowired throws a `NoUniqueBeanDefinitionException` if there are multiple beans of the same type without a primary, but the documentation said multiple beans 'cause `@Autowired` to work', rather than 'not work'.
Previously, when feign used the Ribbon RestClient, an exception was thrown if Content-Length was set. Over time, feign has moved away from RestClient, yet removing the header still happened.
Fixes gh-1705
`MetricsRestTemplateConfiguration` creates a BeanPostProcessor used to configure RestTemplate instances when added to the application context. It should be made @ConditionalOnClass(RestTemplate) instead of @ConditionalOnBean(RestTemplate) since it should be present *before* any RestTemplate bean instance is created. (#1747)
fixes gh-1153
prefer-ip-address does not work in statusPageUrlPath when management port != server port
This change gets `prefer-ip-address` via a relaxed property resolver to set the value during the creation of the `EurekaInstanceConfigBean`.
fixes gh-1724
If DiscoveryClient.getLocalServiceInstance() throws an exception (ie consul isn't available), log a warning and continue. This is useful for dev type environments.
fixes gh-1603
Eureka ServerConfiguration is now auto-configuration based, instead of being explicitly specified via configuration pulled in through @EnableEurekaServer. This way specific beans can be conditionally overridden, configuration can be re-ordered.
Supports PeerEurekaNodes bean to be overridden by the user
Fixes gh-1717
* Fix encoding issue in SpringEncoder for binary data
Fixes gh-1698
* Fix encoding issue in SpringEncoder for binary data
Fixes gh-1698
* Fix encoding issue in SpringEncoder for binary data
Add unit test.
Fixes gh-1698
Currently all errors during writing to the outputStream are ignored. So the
response is read to the end. This is a problem when the response is
infite or very long running (`hystrix.stream` for example) and results in the
socket never being closed and eating up threads (on zuul and the proxied
backend). With this commit the errors during writing are not ignored resulting
in closing the response.
As discovered in #1643, using `@Configuration` on a custom configuration with `@FeignClient` is unnecessary and creates extra work for exclusion from a `@ComponentScan`. This updates the docs to make this explicit.
A new version of httpclient introduced by boot changed the behaviour that previously allowed the charset. It now has to be parsed out and passed to the apache `ContentType` object explicitly.
fixes gh-1649
SpringClientFactory returns null if the class is not aware of IClientConfig.
This change catches the exception when trying the constructor with IClientConfig so classes that aren't aware of IClientConfig can be created.
Fixes gh-1608
In addition to `eureka.instance.hostname` property you can now defined `sidecar.hostname` in order to set different hostname from application and its sidecar.
However if `eureka.instance.hostname` is present it will override `sidecar.hostname`.
Fixes#981
Some webserver are picky with the encoding (uWSGI for example) and the current code behavior of decoding and reencoding the query string can lead to valid requests
rejected by the backend after the modifications in Zuul. This commit adds an optional parameter to force the original encoding of the query string in SimpleHostRoutingFilter.
Fixes gh-971
Defaults were set too late and were overriding values set in the environment.
Specifically, spring.application.name took precedence over eureka.instance.appname.
fixes gh-1516
Specifically, add `@ConditionalOnBean(EurekaClient.class)`.
Fixes an issue where eureka and ribbon are on the classpath, eureka.client.enabled=false which would cause a bean not found exception.
fixes gh-1511
(cherry picked from commit d1f8c03)
RxJavaReturnValueHandlerConfig can only be loaded when both spring-web
and spring-webmvc are on the classpath, because it contains a reference
to the WebMvcConfigurerAdapter class.
But the ConditionalOnClass annotation only included the class from
spring-web. In our situation, only spring-web was on the classpath,
resulting in a NoClassDefFoundError for WebMvcConfigurerAdapter. Fix it
by adding that class to the condition as well.
Instead of blocking them (which is the default behaviour of a
Spring MVC controller) Cors requests will flow through the Zuul
filters by default. Users can control it by grabbing the
ZuulHandlerMapping in a @PostConstruct and injecting some
CorsConfiguration via its setCorsConfigurations() method.
This fixes most of the issues people encounter when there are
multiple proxies in the request. The tricky thing is that there
is another header "Forwarded" that we don't recognize, but which
backends probably do, at least some of the time (since it is
from an actual RFC). The problem is that "Forwarded" does not
contain the ports, so Spring UriComponentsBuilder cannot use it
to rewrite links to a specific port. Since we do not support it
already, this change doesn't make things any worse, but the
corner case is there still.
Moving eureka.server.{expectedNumberOfRenewsPerMin,defaultOpenForTrafficCount} to eureka.instance.registry so relaxed binding can be used. Default to old values for backwards compatibility.
Secure ribbon urls were forced to use https scheme via UriComponentsBuilder, that was created from original uri. This transformation url encoded previously encoded url parts that were used to create builder. This was introduced in c883495.
This change fixes double url encoding using RibbonUtils.updateToHttpsIfNeeded that fixes double escaping case and corner case with '+' in url as well.
Fixes gh-1382
Previously, parameter names with colons (ie foo:bar), caused an IllegalArgumentException because 41c364002f introduced UriTemplate to properly encode.
fixes gh-1193
* add config option to not ignore security headers
* fix field documentation of ignoreSecurityHeaders
* add documenation for zuul.ignoreSecurityHeaders
fixes gh-1096
RibbonUtils now replace the encoded space character '+' in the query string in favor of the equivalent '%20' when rewriting the URI in https. This is due to UriComponentsBuilder verifying the allowed characters in the encoded URI when building to the URI java.net class. The '+' is considered illegal but is widely used in the field. (#1367)
This eliminates them being created for every zuul request.
Also makes properties consistent accross modules: ribbon.httpclient.*, ribbon.restclient.* and ribbon.okhttp.*
fixes gh-1150
The SimpleHostRoutingFilter now accepts normal -Dhttps.proxy= and
-Dhttps.port= settings (and other things that generally work with
java.net).
Fixes gh-510
* Check if object is already a ResponseEntity, if so return instead of wrapping in another ResponseEnitiy. Which caused headers and status code from original ResponseEnitiy to be lost and for body to be output with whole ResponseEntity instead of just the body
* added test
This fixes a case where the ribbon property is set `ribbon.IsSecure=false`, but because the eureka secure port was enabled, the uri created by ribbon was prefixed with https when it shouldn't have.
All places where isSecure is need have been consolidated into RibbonUtils.
fixes gh-1270
Previously with a `@FeignClient(name="http://bad_hostname")` would pass the start time test and fail later in runtime. The test now fails fast.
fixes gh-1257
A problem in Spring Boot means that the extra conditions are combined
with OR not AND, so it's a bug to have more than one until that
gets fixed (in an AnyNestedCondition).
See https://github.com/spring-projects/spring-boot/pull/6672
- add zuul.add-host-header property to add Host header
- add port to X-Forwarded-Host as defined in RFC 7239
- extract PreDecorationFilter.filterOrder() into a public constant
fixes gh-1108
Add a check to current context as contentLength is already in the context
Get content length from Headers when RibbonCommandContext is built + add tests
Use request content length RibbonRoutingFilter
Add documentation for new zuul.ribbonIsolationStrategy property
fixes gh-339
What we're missing ATM is different documentation versions for different application versions. What this change does is that it's:
- finding out what is the current branch (e.g. 1.0.x)
- finding out out what is the name of the main adoc file (e.g. spring-cloud-sleuth)
- pulling the changes from gh-pages after checkout
- finding out what is the list of comma separated whitelisted branches (via the `docs.whitelisted.branches` prop)
- in gh-pages creating a folder with name of the branch (e.g. /1.0.x)
copying all the docs/target/generated-docs/ to that folder
- if the branch from which we're calling the script is NOT master then we're changing the ${main.adoc}.html to index.html so that it's easier to access the docs (e.g. http://cloud.spring.io/spring-cloud-sleuth/1.0.x/)
The FormBodyWrapperFilter handles the application/x-www-form-urlencoded. In the case of requests received by curl or javascript, the FormHttpMessageConverter will reencode the parameters differently (for example, '(' will be encoded while it's not with the javascript encodeURIComponent method).
While this doesn't create any problem, the content length was not properly set in AbstractRibbonCommand. This causes the form params being stripped or the backend server would wait a long time for additional bytes depending on if the content length header was bigger/smaller than the actual data.
Since revision 7b270c4b46, Zuul add support of `X-Forwarded-Prefix` for route with `stripPrefix=true`.
However it supposes that Zuul context-path is equals to `/`. By using a custom context-path on Zuul we can expect that `zuul.add-proxy-headers=true` will compute a prefix regarding that context-path.
Indeed with following architecture:
- Zuul with context-path equals to `/foo`
- A random service (*bar-service*) without context-path
Zuul configurations:
```
zuul:
add-proxy-headers: true
routes:
bar-service: /bar/**
```
We expect that *bar-service* when targeting `http://blabla.com/foo/bar/1` will produce endpoint url equals to `http://blabla.com/foo/bar` and not only `http://blabla.com/bar` (that will not be resolvable).
Furthermore context-path influence not only `stripPrefix=true` routes because with following configuration
```
zuul:
add-proxy-headers: true
routes:
bar-service:
path: /bar/**
strip-prefix: false
```
We expect that *bar-service* when targeting `http://blabla.com/foo/bar/1` will also prodcues endpoint url equals to `http://blabla.com/foo/bar`...
---
Moreover since *Spring 4.3* and new [`ForwardedHeaderFilter`](http://docs.spring.io/spring-framework/docs/4.3.0.BUILD-SNAPSHOT/javadoc-api/org/springframework/web/filter/ForwardedHeaderFilter.html) to handle `X-Forwarded-*` headers, when filter catches `X-Forwarded-Prefix` header it will override request context-path by `X-Forwarded-Prefix` header value and then **removes headers from request**. Thus the fact to support context-path will allow to use that filter with Zuul!
---
Attention there is only one edge case, when `X-Forwarded-Prefix` header is present as same as custom `context-path`! In that case context-path will be ignored in favor to `X-Forwarded-Prefix` as same does `ForwardedHeaderFilter`
This allows developers to customize the request builders for zuul requests to inject headers or modify the request in general. Each zuul request type (RestClient, Apache HttpClient and OkHttp) is supported.
fixes gh-1141
Previously ProxyRequestHelper contained a TraceRepository field. This caused zuul apps to fail with a class not found exception if they excluded actuator. This splits TraceRepository functionality into a new TraceProxyRequestHelper that extends ProxyRequestHelper. Auto configuration creates the appropriate ProxyRequestHelper based on the existence or not of actuator classes.
fixes gh-1135
Zuul sets an empty entity for GET requests. The apache http client either sets transfer encoding to chunked or a content length header. This change sets the apache entity contentLength to 0 (not the header), to that in RequestContent the "content-length" header is set to 0 rathern than transfer encoding.
See gh-1042
If the content length isn't set on the entity, when http client determines which header to set, it sets transfer-encoding to chunked rather than content-length.
This fixes a missing content-length issue when using `HttpClientRibbonCommandFactory`.
See gh-1042
It isn't very helpful to have a Collection converted to a String
anyway. We need to implement something new in Feign to apply
the converter (expander) to individual elements in the collection
but this change should get back to the old behaviour with
List<String> at least.
Fixes gh-1115
This commit adds the support to SpringMvcContract for path parameters
defined in the class' @RequestMapping Annotation that is applied to all
methods of a feign interface.
fixes gh-1023
When the character encoding was set to UTF-8 for example, the path was correctly decoded in PreDecorationFilter but was reencoded in ProxyRequestHelper using the Servlet default ISO-8859-1. This commit uses the character encoding when set and fallback on default.
When using property placeholders in the @RequestMapping annotation the ones placed in the headers attribute do not get replaced. This appears to be because the other attributes, such as the url, use the resolve() function to perform the substitution whereas the header is parsed as-is. This change adds a call to resolve for each side of the equals in the header string so that the properties are substituted correctly.
The Angel client has an idiosyncratic way of calculating an instance
id, and the Brixton client aligned with that already, but the
Brixton server did not. This change should make Brixton Eureka
Servers work with Angel clients.
See gh-978
The way it was being used internally means that we didn't need the
annotation anyway. It would be nice to have it back if the Spring
issue gets resolved, because then we could actually use it as
intended.
Fixes gh-1025
This commit adds the support for query string defined in the class'
@RequestMapping Annotation that is applied to all method of a
controller.
Fxies gh-1023, fixes gh-1024
Before this change we were seeing test failures in
spring-cloud-netflix-eureka-server (but only with Spring Boot 1.4)
caused by annotation processing explosion when
RefreshScopeAutoConfiguration is not on the classpath.
* fix-IgnoredHeadersCasingNotIgnored:
Sensitive headers set in PreDecorationFilter no longer override previously set ignored headers. Removed the case sensitiveness when the sensitive headers are set. Fixes https://github.com/spring-cloud/spring-cloud-netflix/issues/1003
Test for default ribbon client configuration
Tidy up more compiler warnings for generics
Add note to clarify that zuul starter does not include discovery
Adds an `@ExportMetricReader` which was missing before and
led to people losing their metric exports when they had Servo
on the classpath.
Also allow servo metrics autoconfiguration to be disabled via
a flag netflix.metrics.servo.enabled=false (as an alternative to
excluding the class in `@EnableAutoConfiguration`).
The zone for a remote server comes from its
eureka.instance.metadataMap.zone, but we didn't (until this change)
apply the same logic to the client. If the client is registering
itslef with eureka then it will have a metadataMap itself and
we should be able to just reverse the logic.
Fixes gh-991
Spring HttpMessageConverters can modify headers. This change passes the modified headersr back to the feign request, so the proper headers are sent on the request.
fixes gh-977
This change requires setting `ribbon.http.client.enabled=true`.
This change addresses issue #648 Getting Retry Working In RestTemplate. There is also a fix in place that addresses the issue #357 RestTemplate Error.
fixes gh-648
By default we now discard all Set-Cookie and Cookie headers. User
can manipulate it per route via zuul.routes.*.sensitiveHeaders, or
globally via zuul.ignoredHeaders.
Latest Eureka from Netflix uses a different HTTP client, and it
ignores the HTTP basic credentials in a service URL. This change
partially restores the old behaviour by providing an interceptor
(ClientFilter) that has a single, global username/password
taken from the first serviceUrl that contains credentials.
Fixes gh-849
Any client that wants to can include it back again, but generally
it only causes problems (XML returned from apps instead of
JSON by Spring MVC for instance). In general it only causes problems
for services whose clients use "Accept: application/xml,*/*", for
instance (like a browser).
See gh-306
Eureka now has the option (maybe always there) to not register
and that's a sensible default in the bootstrap phase (when we
might not know the port yet).
This reverts commit 3f34ccc8fb. We
need to discuss a bit more (that thread local is probably unavoidable
given the design of Feign, but I don't like it yet).
See gh-841
Spring MVC Feign Contract did not support parameter name fallback
for the #value() attributes of known parameter annotations. Makes
this feature available when the interface has been compiled with
the Java 8 -parameters compiler arg
Fixes gh-835
Supports Spring REST parameter annotations considered
only #value() members without respecting @AliasFor meta-annotations.
Address by passing a Spring-synthesized annotation to individual
AnnotatedParameterProcessors. This approach has the benefit of impacting
present as well as any future implementations alike.
Fixes gh-828
The super class deals with syncing to peers, so we need that
call. It still delegates to the other register method and seems
to work just fine without the override.
Fixes gh-838
User can exclude headers (generally in responses is most useful)
by configuring them, or calling a setter in ZuulProperties.
If Spring Security is on the classpath we add a few headers
automatically, corresponding to the ones that would be added
by Spring Security in the remote backend anyway (so they are not
added twice). Nothing is actually removed, so if the remote
service doesn't add those headers, we don't change anything.
The X-Application-Context header is also added to the hard coded
list of ignored headers, because it isn't relevant in the
gateway (and leaks information about the remote service).
Fixes gh-819
Otherwise there can be duplicate beans with the same type and different
names, becasue the autoconfig does not (for some reason) use
@EnableConfigurationProperties to create the ServerProperties bean.
It isn't an issue until someone writes some autoconfig that itself
imports the ZuulConfiguration (i.e. regular concious users of
@EnableZuulServer do not see any problems and hence no tests fail
here or in integration projects).
Fixes gh-821
Also does not rename another one because it fails (see gh-804). The
bug can be fixed in feign (https://github.com/Netflix/feign/pull/324),
and if that gets merged and released we can revert some of the recent
changes to the apache load balancer here.
The primary change is to fix a memory leak reported in
Netflix/spectator#264. Each time a gauge was updated it
was creating a new registration and because the map holds
a strong reference these would never get collected.
Further, the aggregate value created by the multiple
registrations was not correct.
In addition I added some test cases around the various
inputs and checked that the results were reflected as
expected in the registry. I noticed the timer values
had a unit of milliseconds, but it isn't immediately
clear if the reported value can ever less than 1.0. The
conversion to long is now delayed until after converting
to nanoseconds so duration values less than 1.0 will now
work instead of just recording 0.
For the histogram I changed to just using a cast to `long`
to avoid boxing to a `Double`. As an FYI for the future,
there is a DoubleDistributionSummary we have experimented
with in spectator-ext-sandbox that might be more appropriate
for this use-case.
The Apcahe client does not allow empty body for PATCH, nor does it
allow a request to be pre-populated with a Content-Length. Spring
Cloud tests were trying to do the former, and Feign allows the latter.
Apparently we already support eureka.datacenter as an alias for
archaius.deployment.datacenter and it looks like when that code
was written we intended to support eureka.environment in a similar way.
But it was never finished off, so this change adds the necessary one
line of code.
Fixes gh-791
Otherwise apps register the wrong health and status URLs by default. If
there is no explicit management.port we just need a default that is
the same as server.port.
A change in Zuul in NetflixOSS means that it buffers all requests unless
you switch it off at the level of the servlet. And even when you do that
you need to ensure that Spring Cloud doesn't re-introduce a buffer through
the Servlet30RequestWrapper.
This change restores the feature in Spring Cloud Angel that multipart files
posted to /zuul/* go straight through the servlet and are not buffered in
memory.
Fixes gh-773
More often than not what Route.path was used it had to be concatenated
with the prefix. This change just encapsulates that concern in the
Route itself.
The RouteLocator interface wasn't very useful to anyone in its
1.0.x form. If ProxyRouteLocator features are consolidated into
the RouteLocator interface then users can supply their own
strategies more easily.
Also added RefreshableRouteLocator for implementations that need
to recompute routes when something changes. SimpleRouteLocator
doesn't need to do that because all the routes are in the configuration.
Added spring-cloud-starter-archaius so downstream projects
like consul and zookeeper don't need to maintain the list of
archaius depenencies.
fixes gh-765
The new module is a BOM that doesn't have any parent or direct
dependency management in spring-boot-*. So users can include it
in their dependency management without polluting the spring boot
dependency versions.
Luckily it can also be used in the main spring-cloud-netflix pom,
which should no longer be used as a BOM.
The exception class has to be "fixed"
You may register a serviceId with invalid URI characters (e.g.: '_'), but the URI::getHost() fails when such chars are found.
Fixes a problem with a header in the response containing
content-encoding in lowercase letters. Uses HttpHeaders for case
insensitve check.
Also fixes an issue checking if a request is made for gzip content.
If headers has more than gzip (ie gzip,deflate,sdch), checks if
contains gzip instead of equals to.
Fixes gh-662
RibbonLoadBalancingHttpClient being IClientConfigAware, it is now
initialized within initWithNiwsConfig. The values of the config keys
FollowRedirects, ConnectTimeout and ReadTimeout are now respected.
Fixes gh-691
If the management.port is explicitly set to something other than the
server.port, we can use it to set the status page and health URL
default values. (They can still be overridden by config properties.)
If management.port=0 there's not much we can do because we don't know
the port number yet when the instance config is created.
Fixes gh-425
The aspectjweaver jar includes all of aspectjrt, and the former is
used at runtime in a number of places (tests fail if you remove
it). Both are not needed so we have picked one (the other one than
recommended in gh-666).
Fixes gh-666
This is an implementation of a RibbonCommand and a factory which makes
use of a loadbalancing http client based on apache's http-components
http-client.
With this command/factory it is possible to route PATCH http requests
via zuul/ribbon as well.
fixes gh-412
so that Eureka InstanceInfo (which is designed to be immutable)
can effectively be mutated (by using a different instance) after the
dynamic port is available.
* For Java 8 users, Spectator is the recommended metrics library as Servo is now deprecated in favor of Spectator
* Servo support now needs to be specifically enabled via @EnableServo, even if servo-core is included on the classpath
* Added starter modules for both Spectator and Atlas support
* ServoMetricReader defines a convention for mapping tag-based metrics to hiearchical names for rendering by the Actuator /metrics endpoint
User can provide a url in the route that starts with "forward:"
(instead of "http:" etc.) to handle the request locally.
Also properly ignores ignored routes, so they can be handled locally
(rather than giving up and sending 404).
Fixes gh-536
Still a release candidate (not yet GA), but seems to work, so we'll
try and update before Spring Cloud is released again.
Fixes gh-546, fixes gh-567, fixes gh-553 (probably)
Other Ribbon clients in Spring Cloud use a ServerIntrospector
to check if the Server wanted to be secure. This change levels things
up (and makes the Spring Feign Client a lit easier to customize).
See gh-414
Most clients send "Transfer-Encoding: chunked" so this isn't often
an issue, but if they don't (e.g. if you use "-H Expect:" with
curl) then it's not a great idea to slurp it all into memory.
Fixes gh-563
When using Ribbon the hystrix config and metrics are namespaced
as "RibbonCommand" (via the group key). the command key can then be
serviceId, making it easier to remember how to configure
Ribbon and Hystrix.
Fixes gh-329
There are usually some hints available, especially if the Server
came from Eureka. Unfortunately Server on it's own doesn't contain
enough information (why?), but as a fallback we can guess that
anyone using port 443 is secure.
Fixes gh-459
Remove Servo from EurekaHealthIndicator.
Remove custom DataCenterInfo.
EurekaInstanceConfig.SID is now used as eureka id.
EurekaInstanceConfigBean.getSID falls back to metadataMap.instanceId for
backwards compatibility.
And also when using eureka-first for discovering config server.
The EurekaClient is very rigid and initializes itself, registering
with the remote service on instantiation. Hance it needs to be
in @RefreshScope for it to be properly refreshable. Doing that
leads to a sequence of other changes (e.g. to account for the
fact that there is no @RefreshScope in bootstrap context).
Fixes gh-551
When the parent (bootstrap) context registers the app as well as consuming
the registry it causes problems, e.g. when you refresh that context is
re-created and destroyed, which tends to unregister the app and it's hard
to get it back. It is simpler if the parent context use eureka read-only.
To ensure this we have to remove the @EnableDiscoveryClient from the
bootstrap context.
Tested with vanilla config server and eureka with the 'eureka-first'
sample and the 'zuul-proxy-eureka' sample.
Fixes gh-421
Reverts part of a change made for gh-349 and rationalizes a bit of the
Eureka configuration. The Eureka client cannot be shutdown without
attempting to restart it (but there isn't an obvious public API for
that), so it's better not to shut it down at all.
See gh-421
Move turbine/hystrix amqp specific implementations to spring-cloud-stream based implementations and let the user decide which broker to use.
fixes gh-545
If the zuul reverse proxy and the destination services are using a different scheme
(for example HTTPS on proxy side and HTTP on service side) an additional HTTP
header is required according to RFC7239 [http://tools.ietf.org/html/rfc7239]
RibbonLoadBalancer and RibbonLoadBalancer use IClientConfig IsSecure
property for service ID to determine if the service is secure. Replaces
scheme of URI of request with https if the request is secure.
fixes gh-337
Implements forwarding of eureka CacheRefreshedEvent as HeartbeatEvent,
rather thank serialization hack. Uses new Eureka DI functionality
(mostly there, some issues). Updates EurekaJacksonCodec to be
"DataCenterAware". Reference EurekaClient interface rather than
DiscoveryClient class.
fixes gh-349
* zuul-ignored-patterns:
If more fine-grained ignoring is needed, you can specify specific patterns to ignore. These patterns are being evaluated at the end of the route location process, which means prefixes should be included in the pattern to warrant a match. Ignored patterns span all services and supersede any other route specification.
zuul:
ignoredPatterns: */admin/**
routes:
users: /myusers/**
This means that all calls such as "/myusers/101" will be forwarded to "/101" on the "users" service. But calls including "/admin/" will not resolve.
Recreate query string from either getCurrentContext().getRequestQueryParams()
or original request as fallback. This allows to override query string
params in pre filters.
fixes gh-426
The flag has always been there, it just isn't carried through to the ribbon client configuration
without this change if I understand this change correctly.
Fixes gh-315, fixes gh-423.
Should be no change for users of Boot 1.2 right now, but with this
patch it is possible to use 1.3 with the new conventions for metrics
(e.g. in particular exporting by declaring beans of type
MetricWriter)
With the following configuration at `bootstrap.yaml`
```yaml
spring:
application.name: spring-cloud-hystrix-dashboard
profiles.active: prod
cloud:
config:
discovery:
enabled: true
serviceId: spring-cloud-server-config-with-eureka
server.port: 9003
turbine:
appConfig: some-service
clusterNameExpression: 'default'
```
I wasn't able to see why Turbine can't find the instance. The reason was related to SPEL:
```
org.springframework.expression.spel.SpelEvaluationException: EL1008E:(pos 0): Property or field 'default' cannot be found on object of type 'com.netflix.appinfo.InstanceInfo' - maybe not public?
```
Anyways there was nothing there in the logs so maybe it should not be silenced like right now?
When the Apache HTTP client is being set up for the Ribbon client we can jump
in and explicitly set a cookie policy. Obviously, since the client will generally
be shared across sessions, the only sensible default is IGNORE_COOKIES.
I couldn't find a way round this without using deprecated APIs (but there
are other instances of that in our code because of the way Netflix uses
it, so maybe that doesn't matter).
Fixes gh-301
This commit resolves an issue where some versions of Cloud Foundry are
setting the 'Connection: close' HTTP header in the Hystrix stream
response, which causes the dashboard to not display the stream data.
See https://github.com/cloudfoundry/gorouter/issues/71
However turbine and zuul are depending on mockito-all in compile-scope. Not only I want to get rid of these (usually) test-dependencies, but also mockito-all contains some hamcrest-classes (in older versions) getting in conflict with the classes from spring-test
It took me quite a bit, to figure out how to configure Zuul to use a loadbalanced route without Eureka. I hope this short explicit example will clarify it for other people.
If the app has a context path then the route locator does not match
the whole requestURI (as provided by the raw servlet API), but Spring
has a utility for stripping it off, so we can just use that.
Fixes gh-270
If there is a default route (/**) then the ZuulHandlerMapping will
mask the /error path in a normal Spring Boot application. This change
makes it a special case so that ZuulHandlerMapping will never map
the /error route (the one specified by the ErrorController).
Fixes gh-284
This was kind of ugly, and caused a static usage of the eureka
DiscoveryCLient to become necessary again, just so the @Bean that is
provided for the user stays accurate (it has to be the one in the main
application context, even if the parent boot strap has different
instance metadata).
I tested with a vanilla Eureka server and config server, and used the
client in tests/eureka-first.
Fixes gh-268
This change adds more data to the stream with {"type":"Ping"}
so (I believe) the existing dashboard client will discard it,
but stay alive.
Fixes gh-264
Since hostnames ahve quite strict syntax (e.g. no underscores) we should
validate the feign client name to prevent nasty surprises at runtime.
Fixes gh-263
It turns out that the suckiness of Zuul with multipart requests
comes almost entirely from the Multipart handling in Spring's
DispatcherServlet. This change makes the proxy routes available
on an alternative path /zuul/<normal_path> (where
/zuul is the default value of zuul.servletPath). I have
tested those with 800MB file uploads using the main method in
the FormZuulServletProxyApplicationTests and the main
observation is that there is no OutOfMemory error (no-one tries
to download the complete request body). It works with Ribbon
and with the simple (HttpClient) filter. With Ribbon you
will need to set some timeouts if you want to upload files
as large as that, e.g. see application.yml in the tests:
hystrix.command.default.execution.isolation.thread.timeoutInMilliseconds: 60000
ribbon:
ConnectTimeout: 3000
ReadTimeout: 60000
You need to set "Transfer-Encoding: chunked" in the
incoming request. Chrome does not do this by default
apparently, but I was able to test with curl, e.g.
$ curl -v -H "Transfer-Encoding: chunked" \
-F "file=@mylarg.iso" \
localhost:9999/zuul/direct/file
The old proxy paths through the DispatcherServlet are still
available (for backwards compatibility and for convenience of
having the paths available at the root of the context path).
Fixes gh-254
Because of the way that a FormBodyServletRequestWrapper was
implemented (extending the Zuul servlet 2.5 wrapper) it could
barf at runtime if anyone called its servlet 3.0 methods. The fix
for that was to extract our Servlet30RequestWrapper and extend that
instead.
Also tweaked the DebugFilter a bit so it doesn't try and display
the whole payload. Probably speeds up file uploads a bit but the
fact that we have to store the whole request body in memory is
going to kill us eventually.
See gh-254
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 [code of
conduct](https://github.com/spring-cloud/spring-cloud-build/blob/main/docs/src/main/asciidoc/code-of-conduct.adoc). 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
[Spring Cloud Build](https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/spring-cloud-dependencies-parent/eclipse-code-formatter.xml) project. If using IntelliJ, you can use the
[Eclipse Code Formatter Plugin](https://plugins.jetbrains.com/plugin/6546) 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 main (or
other target branch in the main project).
* When writing a commit message please follow [these conventions](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html),
if you are fixing an existing issue please add `Fixes gh-XXXX` at the end of the commit
* Service Discovery: Eureka instances can be registered and clients can discover the instances using Spring-managed beans
* Service Discovery: an embedded Eureka server can be created with declarative Java configuration
* Circuit Breaker: Hystrix clients can be built with a simple annotation-driven method decorator
* Circuit Breaker: embedded Hystrix dashboard with declarative Java configuration
* Declarative REST Client: Feign creates a dynamic implementation of an interface decorated with JAX-RS or Spring MVC annotations
* Client Side Load Balancer: Ribbon
* External Configuration: a bridge from the Sprnig Environment to Archaius (enables native configuration of Netflix components using Spring Boot conventions)
* Router and Filter: automatic regsitration of Zuul filters, and a simple convention over configuration approach to reverse proxy creation
[[building]]
== Building
=== Basic Compile and Test
:jdkversion: 17
To build the source you will need to install
http://maven.apache.org/run-maven/index.html[Apache Maven] v3.0.6 or above and JDK 1.7.
[[basic-compile-and-test]]
== 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
----
$ mvn install -s .settings.xml
$ ./mvnw install
----
NOTE: You may need to increase the amount of memory available to Maven by setting
a `MAVEN_OPTS` environment variable with the value `-Xmx512m -XX:MaxPermSize=128m`
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.
The `.settings.xml` is only required the first time (or after updates
to dependencies). It is there to provide repository declarations so
that those do not need to be hard coded in the project poms.
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 will be able git
credentials and you already have those.
The projects that require middleware (i.e. Redis) for testing generally
require that a local instance of [Docker](https://www.docker.com/get-started) is installed and running.
If you need mongo, rabbit or redis, see the README in the https://github.com/spring-cloud-samples/scripts[scripts
demo repository] for
instructions. For example consider using the "fig.yml" with
http://www.fig.sh/[Fig] to run them in Docker containers.
=== Documentation
[[documentation]]
== 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
that on it will try to build asciidoc sources using https://docs.antora.org/antora/latest/[Antora] from
`modules/ROOT/`.
As part of that process it will look for a
`docs/src/main/asciidoc/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
(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.
=== Pull Requests
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
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 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 and you follow
the ``Importing into eclipse'' instructions below you should get project specific
formatting automatically. You can also import formatter settings using the
`eclipse-code-formatter.xml` file from the `eclipse` folder. 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).
=== Working with the code
[[working-with-the-code]]
== 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.
https://www.springsource.com/developer/sts[Spring Tools Suite] or
https://eclipse.org[Eclipse] when working with the code. We use the
https://eclipse.org/m2e/[m2eclipse] 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
[[activate-the-spring-maven-profile]]
=== Activate the Spring Maven profile
Spring Cloud projects require the 'spring' Maven profile to be activated to resolve
the spring milestone and snapshot repositories. Use your preferred IDE to set this
profile to be active, or you may experience build errors.
[[importing-into-eclipse-with-m2eclipse]]
=== Importing into eclipse with m2eclipse
We recommend the https://eclipse.org/m2e/[m2eclipse] eclipse plugin when working with
eclipse. If you don't already have m2eclipse installed it is available from the "eclipse
marketplace".
==== Importing into eclipse without m2eclipse
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]]
=== Importing into eclipse without m2eclipse
If you prefer not to use m2eclipse you can generate eclipse project metadata using the
following command:
[indent=0]
----
$ mvn eclipse:eclipse
$ ./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 [Project
Lombok](http://projectlombok.org/features/index.html) 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 other IDEs
Maven is well supported by most Java IDEs. Refer to you vendor documentation.
NOTE: To build the module `spring-cloud-netflix-hystrix-contract` along with the entire Netflix project run the
`build.sh` script in the `scripts` directory.
[[contributing]]
== Contributing
Spring Cloud is released under the non-restrictive Apache 2.0 license. If you would like
to contribute something, or simply want to hack on the code this document should help
you get started.
NOTE: Spring Cloud is released under the non-restrictive Apache 2.0 license. If you would like to contribute to this section of the documentation or if you find an error, please find the source code and issue trackers in the project at {github-project}[github].
=== Sign the Contributor License Agreement
Before we accept a non-trivial patch or pull request we will need you to sign the
com.sun.jersey.core.spi.scanning.ScannerException: IO error when scanning jar jar:file:/Users/sgibb/workspace/spring/spring-boot-eureka/target/eureka-server-1.0.0.BUILD-SNAPSHOT.war!/WEB-INF/lib/jersey-apache-client4-1.11.jar!/com/sun/jersey
at com.sun.jersey.core.spi.scanning.uri.JarZipSchemeScanner.scan(JarZipSchemeScanner.java:82)
at com.sun.jersey.core.spi.scanning.PackageNamesScanner.scan(PackageNamesScanner.java:223)
at com.sun.jersey.core.spi.scanning.PackageNamesScanner.scan(PackageNamesScanner.java:139)
at com.sun.jersey.api.core.ScanningResourceConfig.init(ScanningResourceConfig.java:80)
at com.sun.jersey.api.core.PackagesResourceConfig.init(PackagesResourceConfig.java:104)
at com.sun.jersey.api.core.PackagesResourceConfig.<init>(PackagesResourceConfig.java:78)
at com.sun.jersey.api.core.PackagesResourceConfig.<init>(PackagesResourceConfig.java:89)
at com.sun.jersey.spi.container.servlet.WebComponent.createResourceConfig(WebComponent.java:700)
at com.sun.jersey.spi.container.servlet.WebComponent.createResourceConfig(WebComponent.java:678)
at com.sun.jersey.spi.container.servlet.WebComponent.init(WebComponent.java:203)
at com.sun.jersey.spi.container.servlet.ServletContainer.init(ServletContainer.java:374)
at com.sun.jersey.spi.container.servlet.ServletContainer.init(ServletContainer.java:727)
at org.apache.catalina.core.ApplicationFilterConfig.initFilter(ApplicationFilterConfig.java:279)
at org.apache.catalina.core.ApplicationFilterConfig.<init>(ApplicationFilterConfig.java:109)
at org.apache.catalina.core.StandardContext.filterStart(StandardContext.java:4809)
at org.apache.catalina.core.StandardContext.startInternal(StandardContext.java:5485)
at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:150)
at org.apache.catalina.core.ContainerBase$StartChild.call(ContainerBase.java:1559)
at org.apache.catalina.core.ContainerBase$StartChild.call(ContainerBase.java:1549)
at java.util.concurrent.FutureTask.run(FutureTask.java:262)
at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1145)
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:615)
at java.lang.Thread.run(Thread.java:744)
Caused by: java.io.FileNotFoundException: /Users/sgibb/workspace/spring/spring-boot-eureka/target/eureka-server-1.0.0.BUILD-SNAPSHOT.war!/WEB-INF/lib/jersey-apache-client4-1.11.jar (No such file or directory)
at java.io.FileInputStream.open(Native Method)
at java.io.FileInputStream.<init>(FileInputStream.java:146)
at java.io.FileInputStream.<init>(FileInputStream.java:101)
at sun.net.www.protocol.file.FileURLConnection.connect(FileURLConnection.java:90)
at sun.net.www.protocol.file.FileURLConnection.getInputStream(FileURLConnection.java:188)
at java.net.URL.openStream(URL.java:1037)
at com.sun.jersey.core.spi.scanning.uri.JarZipSchemeScanner.closing(JarZipSchemeScanner.java:123)
at com.sun.jersey.core.spi.scanning.uri.JarZipSchemeScanner.scan(JarZipSchemeScanner.java:75)
// Do not edit this file (e.g. go instead to src/main/asciidoc)
This project provides Netflix OSS 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 battle-tested Netflix components. The
patterns provided include Service Discovery (Eureka), Circuit Breaker (Hystrix),
Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon).
== Features
* Service Discovery: Eureka instances can be registered and clients can discover the instances using Spring-managed beans
* Service Discovery: an embedded Eureka server can be created with declarative Java configuration
* Circuit Breaker: Hystrix clients can be built with a simple annotation-driven method decorator
* Circuit Breaker: embedded Hystrix dashboard with declarative Java configuration
* Declarative REST Client: Feign creates a dynamic implementation of an interface decorated with JAX-RS or Spring MVC annotations
* Client Side Load Balancer: Ribbon
* External Configuration: a bridge from the Sprnig Environment to Archaius (enabls native configuration of Netflix components using Spring Boot conventions)
* Router and Filter: automatic regsitration of Zuul filters,a nd a simple convention over configuration approach to reverse proxy creation
Service Discovery is one of the key tenets of a microservice-based architecture.
Trying to hand-configure each client or some form of convention can be difficult to do and can be brittle.
Eureka is the Netflix Service Discovery Server and Client.
The server can be configured and deployed to be highly available, with each server replicating state about the registered services to the others.
[[netflix-eureka-client-starter]]
=== How to Include Eureka Client
To include the Eureka Client in your project, use the starter with a group ID of `org.springframework.cloud` and an artifact ID of `spring-cloud-starter-netflix-eureka-client`.
See the https://projects.spring.io/spring-cloud/[Spring Cloud Project page] for details on setting up your build system with the current Spring Cloud Release Train.
=== Registering with Eureka
When a client registers with Eureka, it provides meta-data about itself -- such as host, port, health indicator URL, home page, and other details.
Eureka receives heartbeat messages from each instance belonging to a service.
If the heartbeat fails over a configurable timetable, the instance is normally removed from the registry.
// TODO "normally"? Is there some configuration detail that causes a different behavior?
The following example shows a minimal Eureka client application:
Note that the preceding example shows a normal https://projects.spring.io/spring-boot/[Spring Boot] application.
By having `spring-cloud-starter-netflix-eureka-client` on the classpath, your application automatically registers with the Eureka Server. Configuration is required to locate the Eureka server, as shown in the following example:
.application.yml
----
eureka:
client:
serviceUrl:
defaultZone: http://localhost:8761/eureka/
----
In the preceding example, `defaultZone` is a magic string fallback value that provides the service URL for any client that does not express a preference (in other words, it is a useful default).
WARNING: The `defaultZone` property is case sensitive and requires camel case because the `serviceUrl` property is a `Map<String, String>`. Therefore, the `defaultZone` property does not follow the normal Spring Boot snake-case convention of `default-zone`.
The default application name (that is, the service ID), virtual host, and non-secure port (taken from the `Environment`) are `${spring.application.name}`, `${spring.application.name}` and `${server.port}`, respectively.
Having `spring-cloud-starter-netflix-eureka-client` on the classpath makes the app into both a Eureka "`instance`" (that is, it registers itself) and a "`client`" (it can query the registry to locate other services).
The instance behaviour is driven by `eureka.instance.*` configuration keys, but the defaults are fine if you ensure that your application has a value for `spring.application.name` (this is the default for the Eureka service ID or VIP).
See {github-code}/spring-cloud-netflix-eureka-client/src/main/java/org/springframework/cloud/netflix/eureka/EurekaInstanceConfigBean.java[EurekaInstanceConfigBean] and {github-code}/spring-cloud-netflix-eureka-client/src/main/java/org/springframework/cloud/netflix/eureka/EurekaClientConfigBean.java[EurekaClientConfigBean] for more details on the configurable options.
To disable the Eureka Discovery Client, you can set `eureka.client.enabled` to `false`. Eureka Discovery Client will also be disabled when `spring.cloud.discovery.enabled` is set to `false`.
NOTE: Specifying the version of the Spring Cloud Netflix Eureka server as a path parameter is not currently supported. This means you cannot set the version in the context path (`eurekaServerURLContext`). Instead, you can include the version in the server URL (for example, you can set `defaultZone: http://localhost:8761/eureka/v2`).
=== Authenticating with the Eureka Server
HTTP basic authentication is automatically added to your eureka client if one of the `eureka.client.serviceUrl.defaultZone` URLs has credentials embedded in it (curl style, as follows: `https://user:password@localhost:8761/eureka`).
For more complex needs, you can create a `@Bean` of type `DiscoveryClientOptionalArgs` and inject `ClientFilter` instances into it, all of which is applied to the calls from the client to the server.
When Eureka server requires client side certificate for authentication, the client side certificate and trust store can be configured via properties, as shown in following example:
.application.yml
[source,yaml]
----
eureka:
client:
tls:
enabled: true
key-store: <path-of-key-store>
key-store-type: PKCS12
key-store-password: <key-store-password>
key-password: <key-password>
trust-store: <path-of-trust-store>
trust-store-type: PKCS12
trust-store-password: <trust-store-password>
----
The `eureka.client.tls.enabled` needs to be true to enable Eureka client side TLS. When `eureka.client.tls.trust-store` is omitted, a JVM default trust store is used. The default value for `eureka.client.tls.key-store-type` and `eureka.client.tls.trust-store-type` is PKCS12. When password properties are omitted, empty password is assumed.
NOTE: Because of a limitation in Eureka, it is not possible to support per-server basic auth credentials, so only the first set that are found is used.
If you want to customize the RestTemplate used by the Eureka HTTP Client you may want to create a bean of `EurekaClientHttpRequestFactorySupplier` and provide your own logic for generating a `ClientHttpRequestFactory` instance.
All default timeout-related properties for RestTemplate used by the Eureka HTTP Client are set to 3 minutes (in keeping with Apache HC5 default `RequestConfig` and `SocketConfig`). Therefore, to specify the timeout values, you must specify the value directly with the properties in `eureka.client.rest-template-timeout`. (All timeout properties are in milliseconds.)
.application.yml
[source,yaml]
----
eureka:
client:
rest-template-timeout:
connect-timeout: 5000
connect-request-timeout: 8000
socket-timeout: 10000
----
=== Status Page and Health Indicator
The status page and health indicators for a Eureka instance default to `/info` and `/health` respectively, which are the default locations of useful endpoints in a Spring Boot Actuator application.
You need to change these, even for an Actuator application if you use a non-default context path or servlet path (such as `server.servletPath=/custom`). The following example shows the default values for the two settings:
.application.yml
----
eureka:
instance:
statusPageUrlPath: ${server.servletPath}/info
healthCheckUrlPath: ${server.servletPath}/health
----
These links show up in the metadata that is consumed by clients and are used in some scenarios to decide whether to send requests to your application, so it is helpful if they are accurate.
NOTE: In Dalston it was also required to set the status and health check URLs when changing
that management context path. This requirement was removed beginning in Edgware.
=== Registering a Secure Application
If your app wants to be contacted over HTTPS, you can set two flags in the `EurekaInstanceConfigBean`:
Doing so makes Eureka publish instance information that shows an explicit preference for secure communication.
The Spring Cloud `DiscoveryClient` always returns a URI starting with `https` for a service configured this way.
Similarly, when a service is configured this way, the Eureka (native) instance information has a secure health check URL.
Because of the way Eureka works internally, it still publishes a non-secure URL for the status and home pages unless you also override those explicitly.
You can use placeholders to configure the eureka instance URLs, as shown in the following example:
.application.yml
----
eureka:
instance:
statusPageUrl: https://${eureka.hostname}/info
healthCheckUrl: https://${eureka.hostname}/health
homePageUrl: https://${eureka.hostname}/
----
(Note that `${eureka.hostname}` is a native placeholder only available
in later versions of Eureka. You could achieve the same thing with
Spring placeholders as well -- for example, by using `${eureka.instance.hostName}`.)
NOTE: If your application runs behind a proxy, and the SSL termination is in the proxy (for example, if you run in Cloud Foundry or other platforms as a service), then you need to ensure that the proxy "`forwarded`" headers are intercepted and handled by the application.
If the Tomcat container embedded in a Spring Boot application has explicit configuration for the 'X-Forwarded-\*` headers, this happens automatically.
The links rendered by your app to itself being wrong (the wrong host, port, or protocol) is a sign that you got this configuration wrong.
=== Eureka's Health Checks
By default, Eureka uses the client heartbeat to determine if a client is up.
Unless specified otherwise, the Discovery Client does not propagate the current health check status of the application, per the Spring Boot Actuator.
Consequently, after successful registration, Eureka always announces that the application is in 'UP' state. This behavior can be altered by enabling Eureka health checks, which results in propagating application status to Eureka.
As a consequence, every other application does not send traffic to applications in states other then 'UP'.
The following example shows how to enable health checks for the client:
.application.yml
----
eureka:
client:
healthcheck:
enabled: true
----
WARNING: `eureka.client.healthcheck.enabled=true` should only be set in `application.yml`. Setting the value in `bootstrap.yml` causes undesirable side effects, such as registering in Eureka with an `UNKNOWN` status.
If you require more control over the health checks, consider implementing your own `com.netflix.appinfo.HealthCheckHandler`.
=== Eureka Metadata for Instances and Clients
It is worth spending a bit of time understanding how the Eureka metadata works, so you can use it in a way that makes sense in your platform.
There is standard metadata for information such as hostname, IP address, port numbers, the status page, and health check.
These are published in the service registry and used by clients to contact the services in a straightforward way.
Additional metadata can be added to the instance registration in the `eureka.instance.metadataMap`, and this metadata is accessible in the remote clients.
In general, additional metadata does not change the behavior of the client, unless the client is made aware of the meaning of the metadata.
There are a couple of special cases, described later in this document, where Spring Cloud already assigns meaning to the metadata map.
// TODO Add links from here to the relevant places in the document
==== Using Eureka on Cloud Foundry
Cloud Foundry has a global router so that all instances of the same app have the same hostname (other PaaS solutions with a similar architecture have the same arrangement).
This is not necessarily a barrier to using Eureka.
However, if you use the router (recommended or even mandatory, depending on the way your platform was set up), you need to explicitly set the hostname and port numbers (secure or non-secure) so that they use the router.
You might also want to use instance metadata so that you can distinguish between the instances on the client (for example, in a custom load balancer).
By default, the `eureka.instance.instanceId` is `vcap.application.instance_id`, as shown in the following example:
.application.yml
----
eureka:
instance:
hostname: ${vcap.application.uris[0]}
nonSecurePort: 80
----
Depending on the way the security rules are set up in your Cloud Foundry instance, you might be able to register and use the IP address of the host VM for direct service-to-service calls.
This feature is not yet available on Pivotal Web Services (https://run.pivotal.io[PWS]).
==== Using Eureka on AWS
If the application is planned to be deployed to an AWS cloud, the Eureka instance must be configured to be AWS-aware. You can do so by customizing the {github-code}/spring-cloud-netflix-eureka-client/src/main/java/org/springframework/cloud/netflix/eureka/EurekaInstanceConfigBean.java[EurekaInstanceConfigBean] as follows:
[source,java,indent=0]
----
@Bean
@Profile("!default")
public EurekaInstanceConfigBean eurekaInstanceConfig(InetUtils inetUtils) {
EurekaInstanceConfigBean bean = new EurekaInstanceConfigBean(inetUtils);
AmazonInfo info = AmazonInfo.Builder.newBuilder().autoBuild("eureka");
bean.setDataCenterInfo(info);
return bean;
}
----
==== Changing the Eureka Instance ID
A vanilla Netflix Eureka instance is registered with an ID that is equal to its host name (that is, there is only one service per host).
Spring Cloud Eureka provides a sensible default, which is defined as follows:
By using Spring Cloud, you can override this value by providing a unique identifier in `eureka.instance.instanceId`, as shown in the following example:
With the metadata shown in the preceding example and multiple service instances deployed on localhost, the random value is inserted there to make the instance unique.
In Cloud Foundry, the `vcap.application.instance_id` is populated automatically in a Spring Boot application, so the random value is not needed.
=== Using the EurekaClient
Once you have an application that is a discovery client, you can use it to discover service instances from the <<spring-cloud-eureka-server,
Eureka Server>>.
One way to do so is to use the native `com.netflix.discovery.EurekaClient` (as opposed to the Spring Cloud `DiscoveryClient`), as shown in the following example:
Do not use the `EurekaClient` in a `@PostConstruct` method or in a `@Scheduled` method (or anywhere where the `ApplicationContext` might not be started yet).
It is initialized in a `SmartLifecycle` (with `phase=0`), so the earliest you can rely on it being available is in another `SmartLifecycle` with a higher phase.
====
==== Underlying HTTP clients
`EurekaClient` uses either `RestTemplate`, `WebClient` or `JerseyClient` under the hood. In order to use the `EurekaClient`, you need to have one of the supported HTTP clients on your classpath.
To use `RestTemplate`, add `spring-boot-starter-web` to your dependencies. To use `WebClient`, add `spring-boot-starter-webflux` to your dependencies. If both `RestTemplate` and `WebClient` are on the classpath when `eureka.client.webclient.enabled` is set to `true`, `WebClient` is used. Otherwise, `RestTemplate` is used.
If you wish to use Jersey instead, you need to add the Jersey dependencies to your classpath.
The following example shows the dependencies you need to add:
[source,xml]
----
<dependencies>
<dependency>
<groupId>com.sun.jersey</groupId>
<artifactId>jersey-client</artifactId>
</dependency>
<dependency>
<groupId>com.sun.jersey</groupId>
<artifactId>jersey-core</artifactId>
</dependency>
<dependency>
<groupId>com.sun.jersey.contribs</groupId>
<artifactId>jersey-apache-client4</artifactId>
</dependency>
</dependencies>
----
If you have `JerseyClient` on the classpath but do not wish to use it in your `EuerekaClient`, make sure to set `eureka.client.jersey.enabled` to `false`.
=== Alternatives to the Native Netflix EurekaClient
You need not use the raw Netflix `EurekaClient`.
Also, it is usually more convenient to use it behind a wrapper of some sort.
Spring Cloud has support for <<spring-cloud-feign, Feign>> (a REST client builder) and https://docs.spring.io/spring-cloud-commons/reference/4.1/spring-cloud-commons/loadbalancer.html[Spring Cloud LoadBalancer] through the logical Eureka service identifiers (VIPs) instead of physical URLs.
You can also use the `org.springframework.cloud.client.discovery.DiscoveryClient`, which provides a simple API (not specific to Netflix) for discovery clients, as shown in the following example:
----
@Autowired
private DiscoveryClient discoveryClient;
public String serviceUrl() {
List<ServiceInstance> list = discoveryClient.getInstances("STORES");
if (list != null && list.size() > 0 ) {
return list.get(0).getUri();
}
return null;
}
----
=== Why Is It so Slow to Register a Service?
Being an instance also involves a periodic heartbeat to the registry
(through the client's `serviceUrl`) with a default duration of 30 seconds.
A service is not available for discovery by clients until the instance, the server, and the client all have the same metadata in their local
cache (so it could take 3 heartbeats).
You can change the period by setting `eureka.instance.leaseRenewalIntervalInSeconds`.
Setting it to a value of less than 30 speeds up the process of getting clients connected to other services.
In production, it is probably better to stick with the default, because of internal computations in the server that make assumptions about the lease renewal period.
=== Zones
If you have deployed Eureka clients to multiple zones, you may prefer that those clients use services within the same zone before trying services in another zone.
To set that up, you need to configure your Eureka clients correctly.
First, you need to make sure you have Eureka servers deployed to each zone and that
they are peers of each other.
See the section on <<spring-cloud-eureka-server-zones-and-regions,zones and regions>>
for more information.
Next, you need to tell Eureka which zone your service is in.
You can do so by using the `metadataMap` property.
For example, if `service 1` is deployed to both `zone 1` and `zone 2`, you need to set the following Eureka properties in `service 1`:
*Service 1 in Zone 1*
```
eureka.instance.metadataMap.zone = zone1
eureka.client.preferSameZoneEureka = true
```
*Service 1 in Zone 2*
```
eureka.instance.metadataMap.zone = zone2
eureka.client.preferSameZoneEureka = true
```
=== Refreshing Eureka Clients
By default, the `EurekaClient` bean is refreshable, meaning the Eureka client properties can be changed and refreshed.
When a refresh occurs clients will be unregistered from the Eureka server and there might be a brief moment of time
where all instance of a given service are not available. One way to eliminate this from happening is to disable
the ability to refresh Eureka clients. To do this set `eureka.client.refresh.enable=false`.
=== Using Eureka with Spring Cloud LoadBalancer
We offer support for the Spring Cloud LoadBalancer `ZonePreferenceServiceInstanceListSupplier`.
The `zone` value from the Eureka instance metadata (`eureka.instance.metadataMap.zone`) is used for setting the
value of `spring-cloud-loadbalancer-zone` property that is used to filter service instances by zone.
If that is missing and if the `spring.cloud.loadbalancer.eureka.approximateZoneFromHostname` flag is set to `true`,
it can use the domain name from the server hostname as a proxy for the zone.
If there is no other source of zone data, then a guess is made, based on the client configuration (as opposed to the instance configuration).
We take `eureka.client.availabilityZones`, which is a map from region name to a list of zones, and pull out the first zone for the instance's own region (that is, the `eureka.client.region`, which defaults to "us-east-1", for compatibility with native Netflix).
=== AOT and Native Image Support
Spring Cloud Netflix Eureka Client integration supports Spring AOT transformations and native images, however, only with refresh mode disabled.
WARNING: If you want to run Eureka Client in AOT or native image modes, make sure to set `spring.cloud.refresh.enabled` to `false`.
NOTE: Given the AOT and native image closed-world assumption, using random port with Eureka clients is not supported for ahead of time compilation or native images.
[[spring-cloud-eureka-server]]
== Service Discovery: Eureka Server
This section describes how to set up a Eureka server.
[[netflix-eureka-server-starter]]
=== How to Include Eureka Server
To include Eureka Server in your project, use the starter with a group ID of `org.springframework.cloud` and an artifact ID of `spring-cloud-starter-netflix-eureka-server`.
See the https://projects.spring.io/spring-cloud/[Spring Cloud Project page] for details on setting up your build system with the current Spring Cloud Release Train.
NOTE: If your project already uses Thymeleaf as its template engine, the Freemarker templates of the Eureka server may not be loaded correctly. In this case it is necessary to configure the template loader manually:
.application.yml
----
spring:
freemarker:
template-loader-path: classpath:/templates/
prefer-file-system-access: false
----
[[spring-cloud-running-eureka-server]]
=== How to Run a Eureka Server
The following example shows a minimal Eureka server:
The server has a home page with a UI and HTTP API endpoints for the normal Eureka functionality under `/eureka/*`.
The following links have some Eureka background reading: https://github.com/cfregly/fluxcapacitor/wiki/NetflixOSS-FAQ#eureka-service-discovery-load-balancer[flux capacitor] and https://groups.google.com/forum/?fromgroups#!topic/eureka_netflix/g3p2r7gHnN0[google group discussion].
[TIP]
====
Due to Gradle's dependency resolution rules and the lack of a parent bom feature, depending on `spring-cloud-starter-netflix-eureka-server` can cause failures on application startup.
To remedy this issue, add the Spring Boot Gradle plugin and import the Spring cloud starter parent bom as follows:
=== `defaultOpenForTrafficCount` and its effect on EurekaServer warmup time
Netflix Eureka's `waitTimeInMsWhenSyncEmpty` setting is not taken into account in Spring Cloud Eureka server at the beginning. In order to enable the warmup time, set `eureka.server.defaultOpenForTrafficCount=0`.
[[spring-cloud-eureka-server-zones-and-regions]]
=== High Availability, Zones and Regions
The Eureka server does not have a back end store, but the service instances in the registry all have to send heartbeats to keep their registrations up to date (so this can be done in memory).
Clients also have an in-memory cache of Eureka registrations (so they do not have to go to the registry for every request to a service).
By default, every Eureka server is also a Eureka client and requires (at least one) service URL to locate a peer.
If you do not provide it, the service runs and works, but it fills your logs with a lot of noise about not being able to register with the peer.
[[spring-cloud-eureka-server-standalone-mode]]
=== Standalone Mode
The combination of the two caches (client and server) and the heartbeats make a standalone Eureka server fairly resilient to failure, as long as there is some sort of monitor or elastic runtime (such as Cloud Foundry) keeping it alive.
In standalone mode, you might prefer to switch off the client side behavior so that it does not keep trying and failing to reach its peers.
The following example shows how to switch off the client-side behavior:
Notice that the `serviceUrl` is pointing to the same host as the local instance.
[[spring-cloud-eureka-server-peer-awareness]]
=== Peer Awareness
Eureka can be made even more resilient and available by running multiple instances and asking them to register with each other.
In fact, this is the default behavior, so all you need to do to make it work is add a valid `serviceUrl` to a peer, as shown in the following example:
.application.yml (Two Peer Aware Eureka Servers)
----
---
spring:
profiles: peer1
eureka:
instance:
hostname: peer1
client:
serviceUrl:
defaultZone: https://peer2/eureka/
---
spring:
profiles: peer2
eureka:
instance:
hostname: peer2
client:
serviceUrl:
defaultZone: https://peer1/eureka/
----
In the preceding example, we have a YAML file that can be used to run the same server on two hosts (`peer1` and `peer2`) by running it in different Spring profiles.
You could use this configuration to test the peer awareness on a single host (there is not much value in doing that in production) by manipulating `/etc/hosts` to resolve the host names.
In fact, the `eureka.instance.hostname` is not needed if you are running on a machine that knows its own hostname (by default, it is looked up by using `java.net.InetAddress`).
You can add multiple peers to a system, and, as long as they are all connected to each other by at least one edge, they synchronize
the registrations amongst themselves.
If the peers are physically separated (inside a data center or between multiple data centers), then the system can, in principle, survive "`split-brain`" type failures.
You can add multiple peers to a system, and as long as they are all
directly connected to each other, they will synchronize
For more information on CSRF see the https://docs.spring.io/spring-security/site/docs/current/reference/htmlsingle/#csrf[Spring Security documentation].
A demo Eureka Server can be found in the Spring Cloud Samples https://github.com/spring-cloud-samples/eureka/tree/Eureka-With-Security-4.x[repo].
=== JDK 11 Support
The JAXB modules which the Eureka server depends upon were removed in JDK 11. If you intend to use JDK 11
when running a Eureka server you must include these dependencies in your POM or Gradle file.
[source,xml,indent=0]
----
<dependency>
<groupId>org.glassfish.jaxb</groupId>
<artifactId>jaxb-runtime</artifactId>
</dependency>
----
=== AOT and Native Image Support
Spring Cloud Netflix Eureka Server does not support Spring AOT transformations or native images.
=== Metrics
`EurekaInstanceMonitor` listens to events related to Eureka instance registration and creates/updates `Gauge`s for Eureka instance information in Micrometer's `MeterRegistry`. By default, this behavior is disabled. If you want to enable it, you need to set `eureka.server.metrics.enabled` to `true`.
By default, the `Gauge`s are named `eureka.server.instances` and have the following tags:
|eureka.client.allow-redirects | `+++false+++` | Indicates whether server can redirect a client request to a backup server/cluster. If set to false, the server will handle the request directly, If set to true, it may send HTTP redirect to the client, with a new server location.
|eureka.client.availability-zones | | Gets the list of availability zones (used in AWS data centers) for the region in which this instance resides. The changes are effective at runtime at the next registry fetch cycle as specified by registryFetchIntervalSeconds.
|eureka.client.backup-registry-impl | | Gets the name of the implementation which implements BackupRegistry to fetch the registry information as a fallback option for only the first time when the eureka client starts. This may be needed for applications which needs additional resiliency for registry information without which it cannot operate.
|eureka.client.cache-refresh-executor-exponential-back-off-bound | `+++10+++` | Cache refresh executor exponential back off related property. It is a maximum multiplier value for retry delay, in case where a sequence of timeouts occurred.
|eureka.client.cache-refresh-executor-thread-pool-size | `+++2+++` | The thread pool size for the cacheRefreshExecutor to initialise with.
|eureka.client.client-data-accept | | EurekaAccept name for client data accept.
|eureka.client.decoder-name | | This is a transient config and once the latest codecs are stable, can be removed (as there will only be one).
|eureka.client.disable-delta | `+++false+++` | Indicates whether the eureka client should disable fetching of delta and should rather resort to getting the full registry information. Note that the delta fetches can reduce the traffic tremendously, because the rate of change with the eureka server is normally much lower than the rate of fetches. The changes are effective at runtime at the next registry fetch cycle as specified by registryFetchIntervalSeconds
|eureka.client.dollar-replacement | `+++_-+++` | Get a replacement string for Dollar sign <code>$</code> during serializing/deserializing information in eureka server.
|eureka.client.enabled | `+++true+++` | Flag to indicate that the Eureka client is enabled.
|eureka.client.encoder-name | | This is a transient config and once the latest codecs are stable, can be removed (as there will only be one).
|eureka.client.escape-char-replacement | `+++__+++` | Get a replacement string for underscore sign <code>_</code> during serializing/ deserializing information in eureka server.
|eureka.client.eureka-connection-idle-timeout-seconds | `+++30+++` | Indicates how much time (in seconds) that the HTTP connections to eureka server can stay idle before it can be closed. In the AWS environment, it is recommended that the values is 30 seconds or less, since the firewall cleans up the connection information after a few mins leaving the connection hanging in limbo.
|eureka.client.eureka-server-connect-timeout-seconds | `+++5+++` | Indicates how long to wait (in seconds) before a connection to eureka server needs to timeout. Note that the connections in the client are pooled by {@link HttpClient} and this setting affects the actual connection creation and also the wait time to get the connection from the pool.
|eureka.client.eureka-server-d-n-s-name | | Gets the DNS name to be queried to get the list of eureka servers.This information is not required if the contract returns the service urls by implementing serviceUrls. The DNS mechanism is used when useDnsForFetchingServiceUrls is set to true and the eureka client expects the DNS to configured a certain way so that it can fetch changing eureka servers dynamically. The changes are effective at runtime.
|eureka.client.eureka-server-port | | Gets the port to be used to construct the service url to contact eureka server when the list of eureka servers come from the DNS.This information is not required if the contract returns the service urls eurekaServerServiceUrls(String). The DNS mechanism is used when useDnsForFetchingServiceUrls is set to true and the eureka client expects the DNS to configured a certain way so that it can fetch changing eureka servers dynamically. The changes are effective at runtime.
|eureka.client.eureka-server-read-timeout-seconds | `+++8+++` | Indicates how long to wait (in seconds) before a read from eureka server needs to timeout.
|eureka.client.eureka-server-total-connections | `+++200+++` | Gets the total number of connections that is allowed from eureka client to all eureka servers.
|eureka.client.eureka-server-total-connections-per-host | `+++50+++` | Gets the total number of connections that is allowed from eureka client to a eureka server host.
|eureka.client.eureka-server-u-r-l-context | | Gets the URL context to be used to construct the service url to contact eureka server when the list of eureka servers come from the DNS. This information is not required if the contract returns the service urls from eurekaServerServiceUrls. The DNS mechanism is used when useDnsForFetchingServiceUrls is set to true and the eureka client expects the DNS to configured a certain way so that it can fetch changing eureka servers dynamically. The changes are effective at runtime.
|eureka.client.eureka-service-url-poll-interval-seconds | `+++300+++` | Indicates how often(in seconds) to poll for changes to eureka server information. Eureka servers could be added or removed and this setting controls how soon the eureka clients should know about it.
|eureka.client.fetch-registry | `+++true+++` | Indicates whether this client should fetch eureka registry information from eureka server.
|eureka.client.fetch-remote-regions-registry | | Comma separated list of regions for which the eureka registry information will be fetched. It is mandatory to define the availability zones for each of these regions as returned by availabilityZones. Failing to do so, will result in failure of discovery client startup.
|eureka.client.filter-only-up-instances | `+++true+++` | Indicates whether to get the applications after filtering the applications for instances with only InstanceStatus UP states.
|eureka.client.g-zip-content | `+++true+++` | Indicates whether the content fetched from eureka server has to be compressed whenever it is supported by the server. The registry information from the eureka server is compressed for optimum network traffic.
|eureka.client.healthcheck.enabled | `+++true+++` | Enables the Eureka health check handler.
|eureka.client.heartbeat-executor-exponential-back-off-bound | `+++10+++` | Heartbeat executor exponential back off related property. It is a maximum multiplier value for retry delay, in case where a sequence of timeouts occurred.
|eureka.client.heartbeat-executor-thread-pool-size | `+++2+++` | The thread pool size for the heartbeatExecutor to initialise with.
|eureka.client.initial-instance-info-replication-interval-seconds | `+++40+++` | Indicates how long initially (in seconds) to replicate instance info to the eureka server.
|eureka.client.instance-info-replication-interval-seconds | `+++30+++` | Indicates how often(in seconds) to replicate instance changes to be replicated to the eureka server.
|eureka.client.jersey.enabled | `+++true+++` | Enables the use of JerseyClient for Eureka HTTP Client.
|eureka.client.log-delta-diff | `+++false+++` | Indicates whether to log differences between the eureka server and the eureka client in terms of registry information. Eureka client tries to retrieve only delta changes from eureka server to minimize network traffic. After receiving the deltas, eureka client reconciles the information from the server to verify it has not missed out some information. Reconciliation failures could happen when the client has had network issues communicating to server.If the reconciliation fails, eureka client gets the full registry information. While getting the full registry information, the eureka client can log the differences between the client and the server and this setting controls that. The changes are effective at runtime at the next registry fetch cycle as specified by registryFetchIntervalSecondsr
|eureka.client.on-demand-update-status-change | `+++true+++` | If set to true, local status updates via ApplicationInfoManager will trigger on-demand (but rate limited) register/updates to remote eureka servers.
|eureka.client.order | `+++0+++` | Order of the discovery client used by `CompositeDiscoveryClient` for sorting available clients.
|eureka.client.prefer-same-zone-eureka | `+++true+++` | Indicates whether or not this instance should try to use the eureka server in the same zone for latency and/or other reason. Ideally eureka clients are configured to talk to servers in the same zone The changes are effective at runtime at the next registry fetch cycle as specified by registryFetchIntervalSeconds
|eureka.client.property-resolver | |
|eureka.client.proxy-host | | Gets the proxy host to eureka server if any.
|eureka.client.proxy-password | | Gets the proxy password if any.
|eureka.client.proxy-port | | Gets the proxy port to eureka server if any.
|eureka.client.proxy-user-name | | Gets the proxy user name if any.
|eureka.client.refresh.enable | `+++true+++` | Determines whether the EurekaClient instance can be refreshed or not(If disabled none of the Eureka client properties will be refreshable).
|eureka.client.region | `+++us-east-1+++` | Gets the region (used in AWS datacenters) where this instance resides.
|eureka.client.register-with-eureka | `+++true+++` | Indicates whether or not this instance should register its information with eureka server for discovery by others. In some cases, you do not want your instances to be discovered whereas you just want do discover other instances.
|eureka.client.registry-fetch-interval-seconds | `+++30+++` | Indicates how often(in seconds) to fetch the registry information from the eureka server.
|eureka.client.registry-refresh-single-vip-address | | Indicates whether the client is only interested in the registry information for a single VIP.
|eureka.client.rest-template-timeout.connect-timeout | `+++180000+++` | Default values are set to 180000, in keeping with {@link RequestConfig} and {@link SocketConfig} defaults.
|eureka.client.service-url | | Map of availability zone to list of fully qualified URLs to communicate with eureka server. Each value can be a single URL or a comma separated list of alternative locations. Typically the eureka server URLs carry protocol,host,port,context and version information if any. Example: https://ec2-256-156-243-129.compute-1.amazonaws.com:7001/eureka/ The changes are effective at runtime at the next service url refresh cycle as specified by eurekaServiceUrlPollIntervalSeconds.
|eureka.client.should-enforce-registration-at-init | `+++false+++` | Indicates whether the client should enforce registration during initialization. Defaults to false.
|eureka.client.should-unregister-on-shutdown | `+++true+++` | Indicates whether the client should explicitly unregister itself from the remote server on client shutdown.
|eureka.client.tls.enabled | |
|eureka.client.tls.key-password | |
|eureka.client.tls.key-store | |
|eureka.client.tls.key-store-password | |
|eureka.client.tls.key-store-type | |
|eureka.client.tls.trust-store | |
|eureka.client.tls.trust-store-password | |
|eureka.client.tls.trust-store-type | |
|eureka.client.use-dns-for-fetching-service-urls | `+++false+++` | Indicates whether the eureka client should use the DNS mechanism to fetch a list of eureka servers to talk to. When the DNS name is updated to have additional servers, that information is used immediately after the eureka client polls for that information as specified in eurekaServiceUrlPollIntervalSeconds. Alternatively, the service urls can be returned serviceUrls, but the users should implement their own mechanism to return the updated list in case of changes. The changes are effective at runtime.
|eureka.client.webclient.enabled | `+++false+++` | Enables the use of WebClient for Eureka HTTP Client.
|eureka.dashboard.enabled | `+++true+++` | Flag to enable the Eureka dashboard. Default true.
|eureka.dashboard.path | `+++/+++` | The path to the Eureka dashboard (relative to the servlet path). Defaults to "/".
|eureka.datacenter | `+++default+++` | Eureka datacenter. Defaults to "default".
|eureka.environment | `+++test+++` | Eureka environment. Defaults to "test".
|eureka.instance.a-s-g-name | | Gets the AWS autoscaling group name associated with this instance. This information is specifically used in an AWS environment to automatically put an instance out of service after the instance is launched and it has been disabled for traffic..
|eureka.instance.app-group-name | | Get the name of the application group to be registered with eureka.
|eureka.instance.appname | `+++unknown+++` | Get the name of the application to be registered with eureka.
|eureka.instance.async-client-initialization | `+++false+++` | If true the EurekaClient will be initialized asynchronously when the InstanceRegistry bean is created.
|eureka.instance.data-center-info | | Returns the data center this instance is deployed. This information is used to get some AWS specific instance information if the instance is deployed in AWS.
|eureka.instance.health-check-url | | Gets the absolute health check page URL for this instance. The users can provide the healthCheckUrlPath if the health check page resides in the same instance talking to eureka, else in the cases where the instance is a proxy for some other server, users can provide the full URL. If the full URL is provided it takes precedence. <p> It is normally used for making educated decisions based on the health of the instance - for example, it can be used to determine whether to proceed deployments to an entire farm or stop the deployments without causing further damage. The full URL should follow the format http://${eureka.hostname}:7001/ where the value ${eureka.hostname} is replaced at runtime.
|eureka.instance.health-check-url-path | | Gets the relative health check URL path for this instance. The health check page URL is then constructed out of the hostname and the type of communication - secure or unsecure as specified in securePort and nonSecurePort. It is normally used for making educated decisions based on the health of the instance - for example, it can be used to determine whether to proceed deployments to an entire farm or stop the deployments without causing further damage.
|eureka.instance.home-page-url | | Gets the absolute home page URL for this instance. The users can provide the homePageUrlPath if the home page resides in the same instance talking to eureka, else in the cases where the instance is a proxy for some other server, users can provide the full URL. If the full URL is provided it takes precedence. It is normally used for informational purposes for other services to use it as a landing page. The full URL should follow the format http://${eureka.hostname}:7001/ where the value ${eureka.hostname} is replaced at runtime.
|eureka.instance.home-page-url-path | `+++/+++` | Gets the relative home page URL Path for this instance. The home page URL is then constructed out of the hostName and the type of communication - secure or unsecure. It is normally used for informational purposes for other services to use it as a landing page.
|eureka.instance.hostname | | The hostname if it can be determined at configuration time (otherwise it will be guessed from OS primitives).
|eureka.instance.initial-status | | Initial status to register with remote Eureka server.
|eureka.instance.instance-enabled-onit | `+++false+++` | Indicates whether the instance should be enabled for taking traffic as soon as it is registered with eureka. Sometimes the application might need to do some pre-processing before it is ready to take traffic.
|eureka.instance.instance-id | | Get the unique Id (within the scope of the appName) of this instance to be registered with eureka.
|eureka.instance.ip-address | | Get the IPAdress of the instance. This information is for academic purposes only as the communication from other instances primarily happen using the information supplied in {@link #getHostName(boolean)}.
|eureka.instance.lease-expiration-duration-in-seconds | `+++90+++` | Indicates the time in seconds that the eureka server waits since it received the last heartbeat before it can remove this instance from its view and there by disallowing traffic to this instance. Setting this value too long could mean that the traffic could be routed to the instance even though the instance is not alive. Setting this value too small could mean, the instance may be taken out of traffic because of temporary network glitches.This value to be set to atleast higher than the value specified in leaseRenewalIntervalInSeconds.
|eureka.instance.lease-renewal-interval-in-seconds | `+++30+++` | Indicates how often (in seconds) the eureka client needs to send heartbeats to eureka server to indicate that it is still alive. If the heartbeats are not received for the period specified in leaseExpirationDurationInSeconds, eureka server will remove the instance from its view, there by disallowing traffic to this instance. Note that the instance could still not take traffic if it implements HealthCheckCallback and then decides to make itself unavailable.
|eureka.instance.metadata-map | | Gets the metadata name/value pairs associated with this instance. This information is sent to eureka server and can be used by other instances.
|eureka.instance.metadata-map.weight | `+++1+++` | The weight of service instance for weighted load balancing.
|eureka.instance.namespace | `+++eureka+++` | Get the namespace used to find properties. Ignored in Spring Cloud.
|eureka.instance.non-secure-port | `+++80+++` | Get the non-secure port on which the instance should receive traffic.
|eureka.instance.non-secure-port-enabled | `+++true+++` | Indicates whether the non-secure port should be enabled for traffic or not.
|eureka.instance.prefer-ip-address | `+++false+++` | Flag to say that, when guessing a hostname, the IP address of the server should be used in preference to the hostname reported by the OS.
|eureka.instance.registry.default-open-for-traffic-count | `+++1+++` | Value used in determining when leases are cancelled, default to 1 for standalone. Should be set to 0 for peer replicated eurekas
|eureka.instance.secure-health-check-url | | Gets the absolute secure health check page URL for this instance. The users can provide the secureHealthCheckUrl if the health check page resides in the same instance talking to eureka, else in the cases where the instance is a proxy for some other server, users can provide the full URL. If the full URL is provided it takes precedence. <p> It is normally used for making educated decisions based on the health of the instance - for example, it can be used to determine whether to proceed deployments to an entire farm or stop the deployments without causing further damage. The full URL should follow the format http://${eureka.hostname}:7001/ where the value ${eureka.hostname} is replaced at runtime.
|eureka.instance.secure-port | `+++443+++` | Get the Secure port on which the instance should receive traffic.
|eureka.instance.secure-port-enabled | `+++false+++` | Indicates whether the secure port should be enabled for traffic or not.
|eureka.instance.secure-virtual-host-name | `+++unknown+++` | Gets the secure virtual host name defined for this instance. This is typically the way other instance would find this instance by using the secure virtual host name.Think of this as similar to the fully qualified domain name, that the users of your services will need to find this instance.
|eureka.instance.status-page-url | | Gets the absolute status page URL path for this instance. The users can provide the statusPageUrlPath if the status page resides in the same instance talking to eureka, else in the cases where the instance is a proxy for some other server, users can provide the full URL. If the full URL is provided it takes precedence. It is normally used for informational purposes for other services to find about the status of this instance. Users can provide a simple HTML indicating what is the current status of the instance.
|eureka.instance.status-page-url-path | | Gets the relative status page URL path for this instance. The status page URL is then constructed out of the hostName and the type of communication - secure or unsecure as specified in securePort and nonSecurePort. It is normally used for informational purposes for other services to find about the status of this instance. Users can provide a simple HTML indicating what is the current status of the instance.
|eureka.instance.virtual-host-name | `+++unknown+++` | Gets the virtual host name defined for this instance. This is typically the way other instance would find this instance by using the virtual host name.Think of this as similar to the fully qualified domain name, that the users of your services will need to find this instance.
|spring.cloud.compatibility-verifier.compatible-boot-versions | | Default accepted versions for the Spring Boot dependency. You can set {@code x} for the patch version if you don't want to specify a concrete value. Example: {@code 3.4.x}
|spring.cloud.compatibility-verifier.enabled | `+++false+++` | Enables creation of Spring Cloud compatibility verification.
|spring.cloud.config.allow-override | `+++true+++` | Flag to indicate that {@link #isOverrideSystemProperties() systemPropertiesOverride} can be used. Set to false to prevent users from changing the default accidentally. Default true.
|spring.cloud.config.initialize-on-context-refresh | `+++false+++` | Flag to initialize bootstrap configuration on context refresh event. Default false.
|spring.cloud.config.override-none | `+++false+++` | Flag to indicate that when {@link #setAllowOverride(boolean) allowOverride} is true, external properties should take lowest priority and should not override any existing property sources (including local config files). Default false. This will only have an effect when using config first bootstrap.
|spring.cloud.config.override-system-properties | `+++true+++` | Flag to indicate that the external properties should override system properties. Default true.
|spring.cloud.decrypt-environment-post-processor.enabled | `+++true+++` | Enable the DecryptEnvironmentPostProcessor.
|spring.cloud.discovery.client.composite-indicator.enabled | `+++true+++` | Enables discovery client composite health indicator.
|spring.cloud.discovery.client.health-indicator.use-services-query | `+++true+++` | Whether or not the indicator should use {@link DiscoveryClient#getServices} to check its health. When set to {@code false} the indicator instead uses the lighter {@link DiscoveryClient#probe()}. This can be helpful in large deployments where the number of services returned makes the operation unnecessarily heavy.
|spring.cloud.inetutils.default-hostname | `+++localhost+++` | The default hostname. Used in case of errors.
|spring.cloud.inetutils.default-ip-address | `+++127.0.0.1+++` | The default IP address. Used in case of errors.
|spring.cloud.inetutils.ignored-interfaces | | List of Java regular expressions for network interfaces that will be ignored.
|spring.cloud.inetutils.preferred-networks | | List of Java regular expressions for network addresses that will be preferred.
|spring.cloud.inetutils.timeout-seconds | `+++1+++` | Timeout, in seconds, for calculating hostname.
|spring.cloud.inetutils.use-only-site-local-interfaces | `+++false+++` | Whether to use only interfaces with site local addresses. See {@link InetAddress#isSiteLocalAddress()} for more details.
|spring.cloud.loadbalancer.cache.caffeine.spec | | The spec to use to create caches. See CaffeineSpec for more details on the spec format.
|spring.cloud.loadbalancer.cache.capacity | `+++256+++` | Initial cache capacity expressed as int.
|spring.cloud.loadbalancer.cache.enabled | `+++true+++` | Enables Spring Cloud LoadBalancer caching mechanism.
|spring.cloud.loadbalancer.cache.ttl | `+++35s+++` | Time To Live - time counted from writing of the record, after which cache entries are expired, expressed as a {@link Duration}. The property {@link String} has to be in keeping with the appropriate syntax as specified in Spring Boot <code>StringToDurationConverter</code>. @see <a href= "https://github.com/spring-projects/spring-boot/blob/master/spring-boot-project/spring-boot/src/main/java/org/springframework/boot/convert/StringToDurationConverter.java">StringToDurationConverter.java</a>
|spring.cloud.loadbalancer.call-get-with-request-on-delegates | `+++true+++` | If this flag is set to {@code true}, {@code ServiceInstanceListSupplier#get(Request request)} method will be implemented to call {@code delegate.get(request)} in classes assignable from {@code DelegatingServiceInstanceListSupplier} that don't already implement that method, with the exclusion of {@code CachingServiceInstanceListSupplier} and {@code HealthCheckServiceInstanceListSupplier}, which should be placed in the instance supplier hierarchy directly after the supplier performing instance retrieval over the network, before any request-based filtering is done, {@code true} by default.
|spring.cloud.loadbalancer.clients | |
|spring.cloud.loadbalancer.configurations | `+++default+++` | Enables a predefined LoadBalancer configuration.
|spring.cloud.loadbalancer.eager-load.clients | | Names of the clients.
|spring.cloud.loadbalancer.enabled | `+++true+++` | Enables Spring Cloud LoadBalancer.
|spring.cloud.loadbalancer.eureka.approximate-zone-from-hostname | `+++false+++` | Used to determine whether we should try to get the `zone` value from host name.
|spring.cloud.loadbalancer.health-check.initial-delay | `+++0+++` | Initial delay value for the HealthCheck scheduler.
|spring.cloud.loadbalancer.health-check.interval | `+++25s+++` | Interval for rerunning the HealthCheck scheduler.
|spring.cloud.loadbalancer.health-check.interval | `+++25s+++` | Interval for rerunning the HealthCheck scheduler.
|spring.cloud.loadbalancer.health-check.path | | Path at which the health-check request should be made. Can be set up per `serviceId`. A `default` value can be set up as well. If none is set up, `/actuator/health` will be used.
|spring.cloud.loadbalancer.health-check.port | | Path at which the health-check request should be made. If none is set, the port under which the requested service is available at the service instance.
|spring.cloud.loadbalancer.health-check.refetch-instances | `+++false+++` | Indicates whether the instances should be refetched by the `HealthCheckServiceInstanceListSupplier`. This can be used if the instances can be updated and the underlying delegate does not provide an ongoing flux.
|spring.cloud.loadbalancer.health-check.refetch-instances-interval | `+++25s+++` | Interval for refetching available service instances.
|spring.cloud.loadbalancer.health-check.repeat-health-check | `+++true+++` | Indicates whether health checks should keep repeating. It might be useful to set it to `false` if periodically refetching the instances, as every refetch will also trigger a healthcheck.
|spring.cloud.loadbalancer.health-check.update-results-list | `+++true+++` | Indicates whether the {@code healthCheckFlux} should emit on each alive {@link ServiceInstance} that has been retrieved. If set to {@code false}, the entire alive instances sequence is first collected into a list and only then emitted.
|spring.cloud.loadbalancer.hint | | Allows setting the value of <code>hint</code> that is passed on to the LoadBalancer request and can subsequently be used in {@link ReactiveLoadBalancer} implementations.
|spring.cloud.loadbalancer.hint-header-name | `+++X-SC-LB-Hint+++` | Allows setting the name of the header used for passing the hint for hint-based service instance filtering.
|spring.cloud.loadbalancer.retry.avoid-previous-instance | `+++true+++` | Enables wrapping ServiceInstanceListSupplier beans with `RetryAwareServiceInstanceListSupplier` if Spring-Retry is in the classpath.
|spring.cloud.loadbalancer.retry.backoff.enabled | `+++false+++` | Indicates whether Reactor Retry backoffs should be applied.
|spring.cloud.loadbalancer.retry.backoff.jitter | `+++0.5+++` | Used to set `RetryBackoffSpec.jitter`.
|spring.cloud.loadbalancer.retry.backoff.max-backoff | `+++Long.MAX ms+++` | Used to set `RetryBackoffSpec.maxBackoff`.
|spring.cloud.loadbalancer.retry.backoff.min-backoff | `+++5 ms+++` | Used to set `RetryBackoffSpec#minBackoff`.
|spring.cloud.loadbalancer.retry.max-retries-on-next-service-instance | `+++1+++` | Number of retries to be executed on the next `ServiceInstance`. A `ServiceInstance` is chosen before each retry call.
|spring.cloud.loadbalancer.retry.max-retries-on-same-service-instance | `+++0+++` | Number of retries to be executed on the same `ServiceInstance`.
|spring.cloud.loadbalancer.retry.retry-on-all-exceptions | `+++false+++` | Indicates retries should be attempted for all exceptions, not only those specified in `retryableExceptions`.
|spring.cloud.loadbalancer.retry.retry-on-all-operations | `+++false+++` | Indicates retries should be attempted on operations other than `HttpMethod.GET`.
|spring.cloud.loadbalancer.retry.retryable-exceptions | `+++{}+++` | A `Set` of `Throwable` classes that should trigger a retry.
|spring.cloud.loadbalancer.retry.retryable-status-codes | `+++{}+++` | A `Set` of status codes that should trigger a retry.
|spring.cloud.loadbalancer.service-discovery.timeout | | String representation of Duration of the timeout for calls to service discovery.
|spring.cloud.loadbalancer.stats.micrometer.enabled | `+++false+++` | Enables Spring Cloud LoadBalancer Micrometer stats.
|spring.cloud.loadbalancer.sticky-session.add-service-instance-cookie | `+++false+++` | Indicates whether a cookie with the newly selected instance should be added by LoadBalancer.
|spring.cloud.loadbalancer.sticky-session.instance-id-cookie-name | `+++sc-lb-instance-id+++` | The name of the cookie holding the preferred instance id.
|spring.cloud.loadbalancer.subset.instance-id | | Instance id of deterministic subsetting. If not set, {@link IdUtils#getDefaultInstanceId(PropertyResolver)} will be used.
|spring.cloud.loadbalancer.subset.size | `+++100+++` | Max subset size of deterministic subsetting.
|spring.cloud.loadbalancer.x-forwarded.enabled | `+++false+++` | To Enable X-Forwarded Headers.
|spring.cloud.loadbalancer.zone | | Spring Cloud LoadBalancer zone.
|spring.cloud.refresh.additional-property-sources-to-retain | | Additional property sources to retain during a refresh. Typically only system property sources are retained. This property allows property sources, such as property sources created by EnvironmentPostProcessors to be retained as well.
|spring.cloud.refresh.enabled | `+++true+++` | Enables autoconfiguration for the refresh scope and associated features.
|spring.cloud.refresh.extra-refreshable | `+++true+++` | Additional class names for beans to post process into refresh scope.
|spring.cloud.refresh.never-refreshable | `+++true+++` | Comma separated list of class names for beans to never be refreshed or rebound.
|spring.cloud.refresh.on-restart.enabled | `+++true+++` | Enable refreshing context on start.
|spring.cloud.service-registry.auto-registration.enabled | `+++true+++` | Whether service auto-registration is enabled. Defaults to true.
|spring.cloud.service-registry.auto-registration.fail-fast | `+++false+++` | Whether startup fails if there is no AutoServiceRegistration. Defaults to false.
|spring.cloud.service-registry.auto-registration.register-management | `+++true+++` | Whether to register the management as a service. Defaults to true.
|spring.cloud.util.enabled | `+++true+++` | Enables creation of Spring Cloud utility beans.
* Service Discovery: Eureka instances can be registered and clients can discover the instances using Spring-managed beans
* Service Discovery: an embedded Eureka server can be created with declarative Java configuration
* Circuit Breaker: Hystrix clients can be built with a simple annotation-driven method decorator
* Circuit Breaker: embedded Hystrix dashboard with declarative Java configuration
* Declarative REST Client: Feign creates a dynamic implementation of an interface decorated with JAX-RS or Spring MVC annotations
* Client Side Load Balancer: Ribbon
* External Configuration: a bridge from the Sprnig Environment to Archaius (enables native configuration of Netflix components using Spring Boot conventions)
* Router and Filter: automatic regsitration of Zuul filters, and a simple convention over configuration approach to reverse proxy creation
Spring Cloud Netflix provides Netflix OSS 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 battle-tested Netflix components. The patterns provided include Service Discovery (Eureka).
## Features
Spring Cloud Netflix features:
* Service Discovery: Eureka instances can be registered and clients can discover the instances using Spring-managed beans
* Service Discovery: an embedded Eureka server can be created with declarative Java configuration
## Getting Started
As long as Spring Cloud Netflix and Eureka Core are on the
classpath any Spring Boot application with `spring-cloud-starter-netflix-eureka-client` in dependencies will try to contact a Eureka
server on `http://localhost:8761` (the default value of
`eureka.client.serviceUrl.defaultZone`):
```java
@SpringBootApplication
@RestController
public class Application {
@RequestMapping("/")
public String home() {
return "Hello World";
}
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
```
To run your own server use the `spring-cloud-starter-netflix-eureka-server` dependency and `@EnableEurekaServer`.
## Contributing
We welcome contributions. You can read more on how to contribute to the project https://github.com/spring-cloud/spring-cloud-netflix#contributing[here].
## Community Support
* You can report issues through https://github.com/spring-cloud/spring-cloud-netflix/issues[Github].
* We monitor https://stackoverflow.com/[StackOverflow] for questions with the `spring-cloud-netflix` tag.
* You can contact our team at https://gitter.im/spring-cloud/spring-cloud[Gitter].
## Commercial Support
Commercial Support is provided as part of the https://spring.io/support[VMware Spring Runtime] offering.
Service Discovery is one of the key tenets of a microservice based architecture. Trying to hand configure each client or some form of convention can be very difficult to do and can be very brittle. Eureka is the Netflix Service Discovery Server and Client. The server can be configured and deployed to be highly available, with each server replicating state about the registered services to the others.
=== Registering with Eureka
When a client registers with Eureka, it provide meta-data about itself
such as host and port, health indicator URL, home page etc. Eureka
receives heartbeat messages from each instance belonging to a service.
If the heartbeat fails over a configurable timetable, the instance is
normally removed from the registry.
Example eureka client:
[source,java,indent=0]
----
@Configuration
@ComponentScan
@EnableAutoConfiguration
@EnableEurekaClient
@RestController
public class Application {
@RequestMapping("/")
public String home() {
return "Hello world";
}
public static void main(String[] args) {
new SpringApplicationBuilder(Application.class).web(true).run(args);
}
}
----
(i.e. utterly normal Spring Boot app). In this example we use
`@EnableEurekaClient` explicitly, but with only Eureka available you
could also use `@EnableDiscoveryClient`. Configuration is required to
locate the Eureka server. Example:
.application.yml
----
eureka:
client:
serviceUrl:
defaultZone: http://localhost:8761/eureka/
----
where "defaultZone" is a magic string fallback value that provides the
service URL for any client that doesn't express a preference
(i.e. it's a useful default).
The default application name (service ID), virtual host and non-secure
port, taken from the `Environment`, are `${spring.application.name}`,
`${spring.application.name}` and `${server.port}` respectively.
`@EnableEurekaClient` makes the app into both a Eureka "instance"
(i.e. it registers itself) and a "client" (i.e. it can query the
registry to locate other services). The instance behaviour is driven
by `eureka.instance.*` configuration keys, but the defaults will be
fine if you ensure that your application has a
`spring.application.name` (this is the default for the Eureka service
ID, or VIP).
See {github-code}/spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka/EurekaInstanceConfigBean.java[EurekaInstanceConfigBean] and {github-code}/spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka/EurekaClientConfigBean.java[EurekaClientConfigBean] for more details of the configurable options.
=== Status Page and Health Indicator
The status page and health indicators for a Eureka instance default to
"/info" and "/health" respectively, which are the default locations of
useful endpoints in a Spring Boot Actuator application. You need to
change these, even for an Actuator application if you use a
non-default context path or servlet path
(e.g. `server.servletPath=/foo`) or management endpoint path
These links show up in the metadata that is consumers by clients, and
used in some scenarios to decide whether to send requests to your
application, so it's helpful if they are accurate.
=== Eureka Metadata for Instances and Clients
It's worth spending a bit of time understanding how the Eureka metadata works, so you can use it in a way that makes sense in your platform. There is standard metadata for things like hostname, IP address, port numbers, status page and health check. These are published in the service registry and used by clients to contact the services in a straightforward way. Additional metadata can be added to the instance registration in the `eureka.instance.metadataMap`, and this will be accessible in the remote clients, but in general will not change the behaviour of the client, unless it is made aware of the meaning of the metadata. There are a couple of special cases described below where Spring Cloud already assigns meaning to the metadata map.
==== Using Eureka on Cloudfoundry
Cloudfoundry has a global router so that all instances of the same app have the same hostname (it's the same in other PaaS solutions with a similar architecture). This isn't necessarily a barrier to using Eureka, but if you use the router (recommended, or even mandatory depending on the way your platform was set up), you need to explicitly set the hostname and port numbers (secure or non-secure) so that they use the router. You might also want to use instance metadata so you can distinguish between the instances on the client (e.g. in a custom load balancer). For example:
Depending on the way the security rules are set up in your Cloudfoundry instance, you might be able to register and use the IP address of the host VM for direct service-to-service calls. This feature is not (yet) available on Pivotal Web Services (https://run.pivotal.io[PWS]).
==== Making the Eureka Instance ID Unique
By default a eureka instance is registered with an ID that is equal to its host name (i.e. only one service per host). Using Spring Cloud you can override this by providing a unique identifier in `eureka.instance.metadataMap.instanceId`. For example:
Don't use the `DiscoveryClient` in `@PostConstruct` method or in a
`@Scheduled` method (or anywhere where the `ApplicationContext` might
not be started yet). It is initialized in a `SmartLifecycle` (with
`phase=0`) so the earliest you can rely on it being available is in
another `SmartLifecycle` with higher phase.
====
=== Alternatives to the DiscoveryClient
You don't have to use the raw Netflix `DiscoveryClient` and usually it
is more convenient to use it behind a wrapper of some sort. Spring
Cloud has support for <<spring-cloud-feign, Feign>> (a REST client
builder) and also <<spring-cloud-ribbon, Spring `RestTemplate`>> using
the logical Eureka service identifiers (VIPs) instead of physical
URLs. To configure Ribbon with a fixed list of physical servers you
can simply set `<client>.ribbon.listOfServers` to a comma-separated
list of physical addresses (or hostnames), where `<client>` is the ID
of the client.
=== Why is it so Slow to Register a Service?
Being an instance also involves a periodic heartbeat to the registry
(via the client's `serviceUrl`) with default duration 30 seconds. A
service is not available for discovery by clients until the instance,
the server and the client all have the same metadata in their local
cache (so it could take 3 hearbeats). You can change the period using
`eureka.instance.leaseRenewalIntervalInSeconds` and this will speed up
the process of getting clients connected to other services. In
production it's probably better to stick with the default because
there are some computations internally in the server that make
assumptions about the lease renewal period.
[[spring-cloud-eureka-server]]
== Service Discovery: Eureka Server
Example eureka server:
[source,java,indent=0]
----
@Configuration
@EnableAutoConfiguration
@EnableEurekaServer
public class Application {
public static void main(String[] args) {
new SpringApplicationBuilder(Application.class).web(true).run(args);
}
}
----
The server has a home page with a UI, and HTTP API endpoints per the
normal Eureka functionality under `/eureka/*`.
Eureka background reading: see https://github.com/cfregly/fluxcapacitor/wiki/NetflixOSS-FAQ#eureka-service-discovery-load-balancer[flux capacitor] and https://groups.google.com/forum/?fromgroups#!topic/eureka_netflix/g3p2r7gHnN0[google group discussion].
[TIP]
====
You can run the Eureka server as an executable JAR (or WAR) using the
Notice that the `serviceUrl` is pointing to the same host as the local
instance.
=== Peer Awareness
Eureka can be made even more resilient and available by running
multiple instances and asking them to register with each other. In
fact, this is the default behaviour, so all you need to do to make it
work is add a valid `serviceUrl` to a peer, e.g.
.application.yml (Two Peer Aware Eureka Servers)
----
---
spring:
profiles: peer1
eureka:
instance:
hostname: peer1
client:
serviceUrl:
defaultZone: http://peer2/eureka/
---
spring:
profiles: peer2
eureka:
instance:
hostname: peer2
client:
serviceUrl:
defaultZone: http://peer1/eureka/
----
In this example we have a YAML file that can be used to run the same
server on 2 hosts (peer1 and peer2), by running it in different
Spring profiles. You could use this configuration to test the peer
awareness on a single host (there's not much value in doing that in
production) by manipulating `/etc/hosts` to resolve the host names. In
fact, the `eureka.instance.hostname` is not needed if you are running
on a machine that knows its own hostname (it is looked up using
`java.net.InetAddress` by default).
You can add multiple peers to a system, and as long as they are all
connected to each other by at least one edge, they will synchronize
the registrations amongst themselves. If the peers are physically
separated (inside a data centre or between multiple data centres) then
the system can in principle survive split-brain type failures.
=== Prefer IP Address
In some cases, it is preferable for Eureka to advertise the IP Adresses
of services rather than the hostname. Set `eureka.instance.preferIpAddress`
to `true` and when the application registers with eureka, it will use its
IP Address rather than its hostname.
== Circuit Breaker: Hystrix Clients
Netflix has created a library called https://github.com/Netflix/Hystrix[Hystrix] that implements the http://martinfowler.com/bliki/CircuitBreaker.html[circuit breaker pattern]. In a microservice architecture it is common to have multiple layers of service calls.
.Microservice Graph
image::HystrixGraph.png[]
A service failure in the lower level of services can cause cascading failure all the way up to the user. When calls to a particular service reach a certain threshold (20 failures in 5 seconds is the default in Hystrix), the circuit opens and the call is not made. In cases of error and an open circuit a fallback can be provided by the developer.
.Hystrix fallback prevents cascading failures
image::HystrixFallback.png[]
Having an open circuit stops cascading failures and allows overwhelmed or failing services time to heal. The fallback can be another Hystrix protected call, static data or a sane empty value. Fallbacks may be chained so the first fallback makes some other business call which in turn falls back to static data.
Example boot app:
----
@Configuration
@EnableAutoConfiguration
@EnableHystrix
public class Application {
public static void main(String[] args) {
new SpringApplicationBuilder(Application.class).web(true).run(args);
}
}
@Component
public class StoreIntegration {
@HystrixCommand(fallbackMethod = "defaultStores")
public Object getStores(Map<String, Object> parameters) {
//do stuff that might fail
}
public Object defaultStores(Map<String, Object> parameters) {
return /* something useful */;
}
}
----
The `@HystrixCommand` is provided by a Netflix contrib library called
for more details. See the https://github.com/Netflix/Hystrix/wiki/Configuration[Hystrix wiki]
for details on the properties available.
The state of the connected circuit breakers are also exposed in the
`/health` endpoint of the calling application.
[source,json,indent=0]
----
{
"hystrix": {
"openCircuitBreakers": [
"StoreIntegration::getStoresByLocationLink"
],
"status": "CIRCUIT_OPEN"
},
"status": "UP"
}
----
=== Hystrix Metrics Stream
To enable the Hystrix metrics stream include a dependency on `spring-boot-starter-actuator`. This will expose the `/hystrix.stream` as a management endpoint.
One of the main benefits of Hystrix is the set of metrics it gathers about each HystrixCommand. The Hystrix Dashboard displays the health of each circuit breaker in an efficient manner.
.Hystrix Dashboard
image::Hystrix.png[]
To run the Hystrix Dashboard annotate your Spring Boot main class with `@EnableHystrixDashboard`. You then visit `/hystrix` and point the dashboard to an individual instances `/hystrix.stream` endpoint in a Hystrix client application.
=== Turbine
Looking at an individual instances Hystrix data is not very useful in terms of the overall health of the system. https://github.com/Netflix/Turbine[Turbine] is an application that aggregates all of the relevant `/hystrix.stream` endpoints into a combined `/turbine.stream` for use in the Hystrix Dashboard. Individual instances are located via Eureka. Running Turbine is as simple as annotating your main class with the `@EnableTurbine` annotation. All of the documented configuration properties from https://github.com/Netflix/Turbine/wiki/Configuration-(1.x)[the Turbine 1 wiki] apply. The only difference is that the `turbine.instanceUrlSuffix` does not need the port prepended as this is handled automatically unless `turbine.instanceInsertPort=false`.
Configuration key `turbine.appConfig` is a list of eureka serviceId's that turbine will use to lookup instances. The turbine stream is then used in the Hystrix dashboard using a url that looks like: `http://my.turbine.sever:8080/turbine.stream?cluster=<CLUSTERNAME>` (the cluster parameter can be omitted if the name is "default"). The `cluster` parameter must match an entry in `turbine.aggregator.clusterConfig`. Value returned from eureka are uppercase, thus we expect this example to work if there is an app registered with Eureka called "customers":
----
turbine:
aggregator:
clusterConfig: CUSTOMERS
appConfig: customers
----
The `clusterName` can be customized by a SPEL expression in `turbine.clusterNameExpression`. For example, `turbine.clusterNameExpression=aSGName` would get the cluster name from the AWS ASG name. To use the "default" cluster for all apps you need a string literal expression (with single quotes):
----
turbine:
appConfig: customers,stores
clusterNameExpression: 'default'
----
Spring Cloud provides a `spring-cloud-starter-turbine` that has all the dependencies you need to get a Turbine server running. Just create a Spring Boot application and annotate it with `@EnableTurbine`.
=== Turbine AMQP
In some environments (e.g. in a PaaS setting), the classic Turbine model of pulling metrics from all the distributed Hystrix commands doesn't work. In that case you might want to have your Hystrix commands push metrics to Turbine, and Spring Cloud enables that with AMQP messaging. All you need to do on the client is add a dependency to `spring-cloud-netflix-hystrix-amqp` and make sure there is a Rabbit broker available (see Spring Boot documentation for details on how to configure the client credentials, but it should work out of the box for a local broker or in Cloud Foundry).
On the server side Just create a Spring Boot application and annotate it with `@EnableTurbineAmqp` and by default it will come up on port 8989 (point your Hystrix dashboard to that port, any path). You can customize the port using either `server.port` or `turbine.amqp.port`. If you have `spring-boot-starter-web` and `spring-boot-starter-actuator` on the classpath as well, then you can open up the Actuator endpoints on a separate port (with Tomcat by default) by providing a `management.port` which is different.
You can then point the Hystrix Dashboard to the Turbine AMQP Server instead of individual Hystrix streams. If Turbine AMQP is running on port 8989 on myhost, then put `http://myhost:8989` in the stream input field in the Hystrix Dashboard. Circuits will be prefixed by their respective serviceId, followed by a dot, then the circuit name.
Spring Cloud provides a `spring-cloud-starter-turbine-amqp` that has all the dependencies you need to get a Turbine AMQP server running. You need Java 8 to run the app because it is Netty-based.
== Customizing the AMQP ConnectionFactory
If you are using AMQP there needs to be a `ConnectionFactory` (from
Spring Rabbit) in the application context. If there is a single
`ConnectionFactory` it will be used, or if there is a one qualified as
`@HystrixConnectionFactory` (on the client) and
`@TurbineConnectionFactory` (on the server) it will be preferred over
others, otherwise the `@Primary` one will be used. If there are
multiple unqualified connection factories there will be an error.
Note that Spring Boot (as of 1.2.2) creates a `ConnectionFactory` that
is _not_ `@Primary`, so if you want to use one connection factory for
the bus and another for business messages, you need to create both,
and annotate them `@*ConnectionFactory` and `@Primary` respectively.
[[spring-cloud-ribbon]]
== Client Side Load Balancer: Ribbon
Ribbon is a client side load balancer which gives you a lot of control
over the behaviour of HTTP and TCP clients. Feign already uses Ribbon,
so if you are using `@FeignClient` then this section also applies.
A central concept in Ribbon is that of the named client. Each load
balancer is part of an ensemble of components that work together to
contact a remote server on demend, and the ensemble has a name that
you give it as an application developer (e.g. using the `@FeignClient`
annotation). Spring Cloud creates a new ensemble as an
`ApplicationContext` on demand for each named client using
`RibbonClientConfiguration`. This contains (amongst other things) an
`ILoadBalancer`, a `RestClient`, and a `ServerListFilter`.
=== Customizing the Ribbon Client
You can configure some bits of a Ribbon client using external
properties in `<client>.ribbon.*`, which is no different than using
the Netflix APIs natively, except that you can use Spring Boot
configuration files. The native options can
be inspected as static fields in `CommonClientConfigKey` (part of
ribbon-core).
Spring Cloud also lets you take full control of the client by
declaring additional configuration (on top of the
`RibbonClientConfiguration`) using `@RibbonClient`. Example:
https://github.com/Netflix/feign[Feign] is a declarative web service client. It makes writing web service clients easier. To use Feign create an interface and annotate it. It has pluggable annotation support including Feign annotations and JAX-RS annotations. Feign also supports pluggable encoders and decoders. Spring Cloud adds support for Spring MVC annotations and for using the same `HttpMessageConverters` used by default in Spring Web. Spring Cloud integrates Ribbon and Eureka to provide a load balanced http client when using Feign.
Example spring boot app
[source,java,indent=0]
----
@Configuration
@ComponentScan
@EnableAutoConfiguration
@EnableEurekaClient
@EnableFeignClients
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
----
.StoreClient.java
[source,java,indent=0]
----
@FeignClient("stores")
public interface StoreClient {
@RequestMapping(method = RequestMethod.GET, value = "/stores")
List<Store> getStores();
@RequestMapping(method = RequestMethod.POST, value = "/stores/{storeId}", consumes = "application/json")
Store update(@PathParameter("storeId") Long storeId, Store store);
}
----
In the `@FeignClient` annotation the String value ("stores" above) is
an arbitrary client name, which is used to create a Ribbon load
balancer (see <<spring-cloud-ribbon,below for details of Ribbon
support>>). You can also specify a URL using the `url` attribute
(absolute value or just a hostname).
The Ribbon client above will want to discover the physical addresses
for the "stores" service. If your application is a Eureka client then
it will resolve the service in the Eureka service registry. If you
don't want to use Eureka, you can simply configure a list of servers
in your external configuration (see
<<spring-cloud-ribbon-without-eureka,above for example>>).
== External Configuration: Archaius
https://github.com/Netflix/archaius[Archaius] is the Netflix client side configuration library. It is the library used by all of the Netflix OSS components for configuration. Archaius is an extension of the http://commons.apache.org/proper/commons-configuration[Apache Commons Configuration] project. It allows updates to configuration by either polling a source for changes or for a source to push changes to the client. Archaius uses Dynamic<Type>Property classes as handles to properties.
Archaius has its own set of configuration files and loading priorities. Spring applications should generally not use Archaius directly., but the need to configure the Netflix tools natively remains. Spring Cloud has a Spring Environment Bridge so Archaius can read properties from the Spring Environment. This allows Spring Boot projects to use the normal configuration toolchain, while allowing them to configure the Netflix tools, for the most part, as documented.
== Router and Filter: Zuul
Routing in an integral part of a microservice architecture. For example, `/` may be mapped to your web application, `/api/users` is mapped to the user service and `/api/shop` is mapped to the shop service. https://github.com/Netflix/zuul[Zuul] is a JVM based router and server side load balancer by Netflix.
http://www.slideshare.net/MikeyCohen1/edge-architecture-ieee-international-conference-on-cloud-engineering-32240146/27[Netflix uses Zuul] for the following:
* Authentication
* Insights
* Stress Testing
* Canary Testing
* Dynamic Routing
* Service Migration
* Load Shedding
* Security
* Static Response handling
* Active/Active traffic management
Zuul's rule engine allows rules and filters to be written in essentially any JVM language, with built in support for Java and Groovy.
[[netflix-zuul-reverse-proxy]]
=== Embedded Zuul Reverse Proxy
Spring Cloud has created an embedded Zuul proxy to ease the
development of a very common use case where a UI application wants to
proxy calls to one or more back end services. This feature is useful
for a user interface to proxy to the backend services it requires,
avoiding the need to manage CORS and authentication concerns
independently for all the backends.
To enable it, annotate a Spring Boot main class with
`@EnableZuulProxy`, and this forwards local calls to the appropriate
service. By convention, a service with the Eureka ID "users", will
receive requests from the proxy located at `/users` (with the prefix
stripped). The proxy uses Ribbon to locate an instance to forward to
via Eureka, and all requests are executed in a hystrix command, so
failures will show up in Hystrix metrics, and once the circuit is open
the proxy will not try to contact the service.
To skip having a service automatically added, set
`zuul.ignored-services` to a list of service id patterns. If a service
matches a pattern that is ignored, but also included in the explicitly
configured routes map, then it will be unignored. Example:
.application.yml
[source,yaml]
----
zuul:
ignoredServices: *
routes:
users: /myusers/**
----
In this example, all services are ignored *except* "users".
To augment or change
the proxy routes, you can add external configuration like the
following:
.application.yml
[source,yaml]
----
zuul:
routes:
users: /myusers/**
----
This means that http calls to "/myusers" get forwarded to the "users"
service (for example "/myusers/101" is forwarded to "/101").
To get more fine-grained control over a route you can specify the path
and the serviceId independently:
.application.yml
[source,yaml]
----
zuul:
routes:
users:
path: /myusers/**
serviceId: users_service
----
This means that http calls to "/myusers" get forwarded to the
"users_service" service. The route has to have a "path" which can be
specified as an ant-style pattern, so "/myusers/*" only matches one
level, but "/myusers/**" matches hierarchically.
The location of the backend can be specified as either a "serviceId"
(for a Eureka service) or a "url" (for a physical location), e.g.
.application.yml
[source,yaml]
----
zuul:
routes:
users:
path: /myusers/**
url: http://example.com/users_service
----
To add a prefix to all mappings, set `zuul.prefix` to a value, such as
`/api`. The proxy prefix is stripped from the request before the
request is forwarded by default (switch this behaviour off with
`zuul.stripPrefix=false`). You can also switch off the stripping of
the service-specific prefix from individual routes, e.g.
.application.yml
[source,yaml]
----
zuul:
routes:
users:
path: /myusers/**
stripPrefix: false
----
In this example requests to "/myusers/101" will be forwarded to "/myusers/101" on the "users" service.
The `zuul.routes` entries actually bind to an object of type `ProxyRouteLocator`. If you
look at the properties of that object you will see that it also has a "retryable" flag.
Set that flag to "true" to have the Ribbon client automatically retry failed requests
(and if you need to you can modify the parameters of the retry operations using
the Ribbon client configuration).
The `X-Forwarded-Host` header added to the forwarded requests by
default. To turn it off set `zuul.addProxyHeaders = false`. The
prefix path is stripped by default, and the request to the backend
picks up a header "X-Forwarded-Prefix" ("/myusers" in the examples
above).
An application with the `@EnableZuulProxy` could act as a standalone
server if you set a default route ("/"), for example `zuul.route.home:
/` would route all traffic (i.e. "/**") to the "home" service.
=== Plain Embedded Zuul
You can also run a Zuul server without the proxying, or switch on parts of the proxying platform selectively, if you
use `@EnableZuulServer` (instead of `@EnableZuulProxy`). Any beans that you add to the application of type `ZuulFilter`
will be installed automatically.
In this case the routes into the Zuul server are
still specified by configuring "zuul.routes.*", but there is no service discovery and no proxying, so the
"serviceId" and "url" settings are ignored. For example:
.application.yml
[source,yaml]
----
zuul:
routes:
api: /api/**
----
maps all paths in "/api/**" to the Zuul filter chain.
=== Polyglot support with Sidecar
Do you have non-jvm languages you want to take advantage of Eureka, Ribbon and
Config Server? The Spring Cloud Netflix Sidecar was inspired by
https://github.com/Netflix/Prana[Netflix Prana]. It includes a simple http api
to get all of the instances (ie host and port) for a given service. You can
also proxy service calls through an embedded Zuul proxy which gets its route
entries from Eureka. The Spring Cloud Config Server can be accessed directly
via host lookup or through the Zuul Proxy. The non-jvm app should implement
a health check so the Sidecar can report to eureka if the app is up or down.
To enable the Sidecar, create a Spring Boot application with `@EnableSidecar`.
This annotation includes `@EnableCircuitBreaker`, `@EnableDiscoveryClient`,
and `@EnableZuulProxy`. Run the resulting application on the same host as the
non-jvm application.
To configure the side car add `sidecar.port` and `sidecar.health-uri` to `application.yml`.
The `sidecar.port` property is the port the non-jvm app is listening on. This
is so the Sidecar can properly register the app with Eureka. The `sidecar.health-uri`
is a uri accessible on the non-jvm app that mimicks a Spring Boot health
indicator. It should return a json document like the following:
.health-uri-document
[source,json]
----
{
"status":"UP"
}
----
Here is an example application.yml for a Sidecar application:
.application.yml
[source,yaml]
----
server:
port: 5678
spring:
application:
name: sidecar
sidecar:
port: 8000
health-uri: http://localhost:8000/health.json
----
The api for the `DiscoveryClient.getInstances()` method is `/hosts/{serviceId}`.
Here is an example response for `/hosts/customers` that returns two instances on
different hosts. This api is accessible to the non-jvm app (if the sidecar is
on port 5678) at `http://localhost:5678/hosts/{serviceId}`.
./hosts/customers
[source,json]
----
[
{
"host": "myhost",
"port": 9000,
"uri": "http://myhost:9000",
"serviceId": "CUSTOMERS",
"secure": false
},
{
"host": "myhost2",
"port": 9000,
"uri": "http://myhost2:9000",
"serviceId": "CUSTOMERS",
"secure": false
}
]
----
The Zuul proxy automatically adds routes for each service known in eureka to
`/<serviceId>`, so the customers service is available at `/customers`. The
Non-jvm app can access the customer service via `http://localhost:5678/customers`
(assuming the sidecar is listening on port 5678).
If the Config Server is registered with Eureka, non-jvm application can access
it via the Zuul proxy. If the serviceId of the ConfigServer is `configserver`
and the Sidecar is on port 5678, then it can be accessed at
http://localhost:5678/configserver
Non-jvm app can take advantage of the Config Server's ability to return YAML
documents. For example, a call to http://sidecar.local.spring.io:5678/configserver/default-master.yml
might result in a YAML document like the following
# Remove '\r' from value to allow usage on windows as IFS does not consider '\r' as a separator ( considers space, tab, new line ('\n'), and custom '=' )
safeValue=$(echo "$value" | tr -d '\r')
case "$key" in (wrapperUrl) wrapperUrl="$safeValue"; break ;;
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
spring-builds
Oleg Zhurakousky
Olga Maciaszek-Sharma
Olga Maciaszek-Sharma
dependabot[bot]
Plastic Hat
_NewAge
Kaiyao Ke
Ryan Baxter
WonChul Heo
Ryan Baxter
Puppy4C
ZIRAKrezovic
RobertBleyl
spencergibb
Nasser Al-den Ghassan Shareef Khaled
Olga Maciaszek-Sharma
G1
jizhuozhi
Spencer Gibb
Vilius Šumskas
Weix Sun
Marcin Grzejszczak
alceil
Koki Igarashi
TAN ZHENG
MI-cool
Kaveh Shamsi
Robert McNees
Robert McNees
spencergibb
maniotie
Jay Bryant
buildmaster
Kevin Kroner
Felipe Adorno
Theo Sun
hrksingh
larosek
joyita07
dependabot-preview[bot]
Haytham Mohamed
JiaLin
Samuel Renier
MadeInChina
Rafael Renan Pacheco
Haytham Mohamed
XiaoZiShan
Eduard Wirch
Dmitrii_Priporov
Flora KALISA
Eric Bussieres
OLPMO
Andrew McCallum
LiangYong
fecqs
Deepika Mohan
Ryan Baxter
Dave Syer
Tim Ysewyn
Rafał Żukowski
Denys Ivano
emilnkrastev
Yuxin Bai
Marcin Grzejszczak
Greg Adams
Chris White
PeichengLiu
HeemangHan
Siavash Shaghafi
wenqi.huang
Craig Andrews
Spring Operator
Spring Operator
周立
davids-backbase
Pan Li
Dmitrii Priporov
Zhanwei Wang
ivansjg
bhattankit
ailin zhou
Tim Ysewyn
Stephan Windmüller
Kristine Jetzke
saga
Nastya Smirnova
Fabri Di Napoli
David Liu
Marcin Grzejszczak
Dennis Effing
durigon
Spencer Gibb
kjc14f
chenkunyun
andersenleo
Tomasz Juchniewicz
Patrick Way
John Huang
trickert76
Marcelo Diniz
Bertrand Renuart
AddoZhang
André Schreck
arkin
Taras Danylchuk
Anvy Zhang
Yongsung Yoon
Jawher Moussa
Fahim Farook
Alykoff
ScienJus
OlgaMaciaszek
Mário Buratto
Vikash Tiwari
Bertrand Renuart
CaiJiahe
darkius
Jay Bryant
Eko Kurniawan Khannedy
zaygrzx
Andreas Evers
Igor Suhorukov
Taylor Wicksell
Biju Kunjummen
Toshiaki Maki
reillylm
Guillaume Berche
Igor Kryvenko
Riz Joj
Silas Mahler
Kerwin Bryant
Tomasz Juchniewicz
Craig Rueda
Daniel Lavoie
Daniel Qian
agseijas
Stephane Maldini
JagmohanSharma
Raiyan
mg
Gregor Zurowski
Alex Sartan
Andre Dörnbrack
Matt Bray
spccold
Dominik Mostek
Jin Zhang
Tom Cawley
Olivier Bourgain
Jayanth MP
Daniel Lavoie
Jayanth
Tummala Dhanvi (c0mrad3)
Marco Schulte
Brandon Atkinson
Piotr Mionskowski
André Dörnbrack
Ryan Baxter
pahli
Rico Pahlisch
Roman Rodov
balp
Luke Tornquist
윤용성(Yongsung Yoon)/개발혁신팀/SKP
wuwo
Anastasiia Smirnova
David-V2
gonzalad
Michael Tecourt
Jack Harris
nick-pww
windinn
utsman
Lars
Erik Kringen
Roman Terentiev
Johannes Edmeier
Ben Klein
Eloi
Stefan Bley
Matt Sicker
Trevor Mack
Ondřej Božek
Hung Tran
Arnaud Brunet
Abhijit Sarkar
Rob Worsnop
Julien Hoarau
Thibaud Lepretre
Jacques-Etienne Beaudet
Ahmed Nasir
Rahman Usta
Bart Blommaerts
Robin Stocker
Venil Noronha
Alena
Bartłomiej Słota
Max Ishchenko
Bartłomiej Słota
bpicode
Mathias Düsterhöft
Julien Roy
Niklas Herder
Matthew Jenkins
rockinrimmer
Niklas Herder
Sébastien Nussbaumer
Jon Schneider
Garcia Florian
Stéphane Lagraulet
Stefan Fussenegger
Coramo
Mike Liu
libetl
Scott Oster
Jacques-Etienne Beaudet
Michael Hartle
Denys Kurylenko
Patrick Cornelißen
Will Tran
Jérôme Mirc
Marcos Barbero
Damian Jackson
Ryan W. Moore
Tommy Ludwig
Shivang Shah
Sébastien PERALTA
Nicolas Byl
Andrei Sfat
Andrei Sfat
Matt Reynolds
Pedro Alvarado
Tyler Van Gorder
Adrian Ivan
Tim te Beek
Marc Paquette
Jakub Narloch
Matt Benson
Jean-Eric Cuendet
Andreas Kluth
Brian Harrington
Rafael Zanella
hscholz
Jettro Coenradie
Stéphane Leroy
alexVengrovsk
Greg Liebowitz
Micheal Swiggs
Christian Lohmann
Oreste Luci
Konstantin A. Zolotukhin
boostrack
Andrei Sfat
Forstner Michael
Adrian Cole
Adrian Cole
gandrianakis
Gunnar Hillert
Roy Clarkson
Adrian Cole
Stephen Oakey
Josh Ghiloni
Jon Schneider
andreasevers
Stephen Souness
Jakub Stachowski
Ryan J Baxter
Eric Bottard
Brandon Atkinson
Bertrand Renuart
Justin Walsh
Darek Kaczyński
Chad Jaros
Alexandru Burghelea
Johannes Stelzer
unknown
Peter
Dave Syer
sampengilly
