From e8b50d80ed885c6f1edf122e844c5a5e6cb320f6 Mon Sep 17 00:00:00 2001 From: Olga Maciaszek-Sharma Date: Fri, 13 Sep 2019 17:09:01 +0200 Subject: [PATCH] Update docs. (#3650) --- docs/README.adoc | 47 ++++++++++++++++++ docs/pom.xml | 49 +++++++++++++++++++ docs/src/main/asciidoc/README.adoc | 2 + docs/src/main/asciidoc/_attributes.adoc | 15 ++++++ docs/src/main/asciidoc/_configprops.adoc | 25 ++++++++++ docs/src/main/asciidoc/appendix.adoc | 14 ++++++ docs/src/main/asciidoc/intro.adoc | 2 + docs/src/main/asciidoc/maintenance-mode.adoc | 1 + docs/src/main/asciidoc/sagan-boot.adoc | 1 + docs/src/main/asciidoc/sagan-index.adoc | 2 + .../spring-cloud-circuitbreaker-hystrix.adoc | 2 + .../main/asciidoc/spring-cloud-netflix.adoc | 14 +++++- 12 files changed, 172 insertions(+), 2 deletions(-) create mode 100644 docs/src/main/asciidoc/_attributes.adoc create mode 100644 docs/src/main/asciidoc/_configprops.adoc create mode 100644 docs/src/main/asciidoc/appendix.adoc diff --git a/docs/README.adoc b/docs/README.adoc index 9bbecde45..a7ac3af67 100644 --- a/docs/README.adoc +++ b/docs/README.adoc @@ -4,11 +4,43 @@ Manual changes to this file will be lost when it is generated again. Edit the files in the src/main/asciidoc/ directory instead. //// +:doctype: book +:idprefix: +:idseparator: - +:toc: left +:toclevels: 4 +:tabsize: 4 +:numbered: +:sectanchors: +:sectnums: +:icons: font +:hide-uri-scheme: +:docinfo: shared,private + +:sc-ext: java +:project-full-name: Spring Cloud Netflix + image::https://circleci.com/gh/spring-cloud/spring-cloud-netflix/tree/master.svg?style=svg["CircleCI", link="https://circleci.com/gh/spring-cloud/spring-cloud-netflix/tree/master"] image::https://codecov.io/gh/spring-cloud/spring-cloud-netflix/branch/master/graph/badge.svg["Codecov", link="https://codecov.io/gh/spring-cloud/spring-cloud-netflix/branch/master"] image::https://api.codacy.com/project/badge/Grade/a6885a06921e4f72a0df0b7aabd6d118["Codacy code quality", link="https://www.codacy.com/app/Spring-Cloud/spring-cloud-netflix?utm_source=github.com&utm_medium=referral&utm_content=spring-cloud/spring-cloud-netflix&utm_campaign=Badge_Grade"] +:doctype: book +:idprefix: +:idseparator: - +:toc: left +:toclevels: 4 +:tabsize: 4 +:numbered: +:sectanchors: +:sectnums: +:icons: font +:hide-uri-scheme: +:docinfo: shared,private + +:sc-ext: java +:project-full-name: Spring Cloud Netflix + 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 @@ -27,6 +59,21 @@ Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon). * External Configuration: a bridge from the Spring Environment to Archaius (enables native configuration of Netflix components using Spring Boot conventions) * Router and Filter: automatic registration of Zuul filters, and a simple convention over configuration approach to reverse proxy creation +:doctype: book +:idprefix: +:idseparator: - +:toc: left +:toclevels: 4 +:tabsize: 4 +:numbered: +:sectanchors: +:sectnums: +:icons: font +:hide-uri-scheme: +:docinfo: shared,private + +:sc-ext: java +:project-full-name: Spring Cloud Netflix == Modules In Maintenance Mode diff --git a/docs/pom.xml b/docs/pom.xml index 8863f6d25..6c173977b 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -14,7 +14,48 @@ spring-cloud-netflix 1.2.x,1.3.x,1.4.x + + .*.eureka.*|.*.hystrix.*|.*.ribbon.*|.*.sidecar.*|.*.turbine.*|.*.zuul.*|.*.archaius.* + + + + ${project.groupId} + spring-cloud-starter-netflix-archaius + + + ${project.groupId} + spring-cloud-starter-netflix-eureka-client + + + ${project.groupId} + spring-cloud-starter-netflix-eureka-server + + + ${project.groupId} + spring-cloud-starter-netflix-hystrix + + + ${project.groupId} + spring-cloud-starter-netflix-hystrix-dashboard + + + ${project.groupId} + spring-cloud-starter-netflix-ribbon + + + ${project.groupId} + spring-cloud-starter-netflix-turbine + + + ${project.groupId} + spring-cloud-starter-netflix-turbine-stream + + + ${project.groupId} + spring-cloud-starter-netflix-zuul + + @@ -30,6 +71,10 @@ docs + + pl.project13.maven + git-commit-id-plugin + org.apache.maven.plugins maven-dependency-plugin @@ -38,6 +83,10 @@ org.apache.maven.plugins maven-resources-plugin + + org.codehaus.mojo + exec-maven-plugin + org.asciidoctor asciidoctor-maven-plugin diff --git a/docs/src/main/asciidoc/README.adoc b/docs/src/main/asciidoc/README.adoc index e538d455b..53716be4c 100644 --- a/docs/src/main/asciidoc/README.adoc +++ b/docs/src/main/asciidoc/README.adoc @@ -1,3 +1,5 @@ +include::_attributes.adoc[] + image::https://circleci.com/gh/spring-cloud/spring-cloud-netflix/tree/master.svg?style=svg["CircleCI", link="https://circleci.com/gh/spring-cloud/spring-cloud-netflix/tree/master"] image::https://codecov.io/gh/spring-cloud/spring-cloud-netflix/branch/master/graph/badge.svg["Codecov", link="https://codecov.io/gh/spring-cloud/spring-cloud-netflix/branch/master"] image::https://api.codacy.com/project/badge/Grade/a6885a06921e4f72a0df0b7aabd6d118["Codacy code quality", link="https://www.codacy.com/app/Spring-Cloud/spring-cloud-netflix?utm_source=github.com&utm_medium=referral&utm_content=spring-cloud/spring-cloud-netflix&utm_campaign=Badge_Grade"] diff --git a/docs/src/main/asciidoc/_attributes.adoc b/docs/src/main/asciidoc/_attributes.adoc new file mode 100644 index 000000000..16af12202 --- /dev/null +++ b/docs/src/main/asciidoc/_attributes.adoc @@ -0,0 +1,15 @@ +:doctype: book +:idprefix: +:idseparator: - +:toc: left +:toclevels: 4 +:tabsize: 4 +:numbered: +:sectanchors: +:sectnums: +:icons: font +:hide-uri-scheme: +:docinfo: shared,private + +:sc-ext: java +:project-full-name: Spring Cloud Netflix \ No newline at end of file diff --git a/docs/src/main/asciidoc/_configprops.adoc b/docs/src/main/asciidoc/_configprops.adoc new file mode 100644 index 000000000..eed5f2784 --- /dev/null +++ b/docs/src/main/asciidoc/_configprops.adoc @@ -0,0 +1,25 @@ +|=== +|Name | Default | Description + +|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 org.apache.http.client.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 | 0 | 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.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.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.server.peer-eureka-nodes-update-interval-ms | 0 | +|eureka.server.peer-eureka-status-refresh-time-interval-ms | 0 | +|management.endpoint.hystrix.config | | Hystrix settings. These are traditionally set using servlet parameters. Refer to the documentation of Hystrix for more details. +|management.endpoint.hystrix.stream.enabled | true | Whether to enable the hystrix.stream endpoint. +|management.metrics.binders.hystrix.enabled | true | Enables creation of OK Http Client factory beans. +|ribbon.eureka.enabled | true | Enables the use of Eureka with Ribbon. +|spring.cloud.loadbalancer.ribbon.enabled | true | Causes `RibbonLoadBalancerClient` to be used by default. +|zuul.ribbon-isolation-strategy | | +|zuul.ribbon.eager-load.enabled | false | Enables eager loading of Ribbon clients on startup. + +|=== diff --git a/docs/src/main/asciidoc/appendix.adoc b/docs/src/main/asciidoc/appendix.adoc new file mode 100644 index 000000000..2c18b8653 --- /dev/null +++ b/docs/src/main/asciidoc/appendix.adoc @@ -0,0 +1,14 @@ +:numbered!: +[appendix] +[[common-application-properties]] +== Common application properties + +include::_attributes.adoc[] + +Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches. +This appendix provides a list of common {project-full-name} properties and references to the underlying classes that consume them. + +NOTE: Property contributions can come from additional jar files on your classpath, so you should not consider this an exhaustive list. +Also, you can define your own properties. + +include::_configprops.adoc[] \ No newline at end of file diff --git a/docs/src/main/asciidoc/intro.adoc b/docs/src/main/asciidoc/intro.adoc index b24256263..6631b3f2c 100644 --- a/docs/src/main/asciidoc/intro.adoc +++ b/docs/src/main/asciidoc/intro.adoc @@ -1,3 +1,5 @@ +include::_attributes.adoc[] + 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 diff --git a/docs/src/main/asciidoc/maintenance-mode.adoc b/docs/src/main/asciidoc/maintenance-mode.adoc index fd5c8907a..f302bcb68 100644 --- a/docs/src/main/asciidoc/maintenance-mode.adoc +++ b/docs/src/main/asciidoc/maintenance-mode.adoc @@ -1,3 +1,4 @@ +include::_attributes.adoc[] == Modules In Maintenance Mode diff --git a/docs/src/main/asciidoc/sagan-boot.adoc b/docs/src/main/asciidoc/sagan-boot.adoc index e69de29bb..ecfa9d90c 100644 --- a/docs/src/main/asciidoc/sagan-boot.adoc +++ b/docs/src/main/asciidoc/sagan-boot.adoc @@ -0,0 +1 @@ +include::_attributes.adoc[] \ No newline at end of file diff --git a/docs/src/main/asciidoc/sagan-index.adoc b/docs/src/main/asciidoc/sagan-index.adoc index b295c2aad..e7a2b50b1 100644 --- a/docs/src/main/asciidoc/sagan-index.adoc +++ b/docs/src/main/asciidoc/sagan-index.adoc @@ -1,3 +1,5 @@ +include::_attributes.adoc[] + 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), Circuit Breaker (Hystrix), Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon).. ## Features diff --git a/docs/src/main/asciidoc/spring-cloud-circuitbreaker-hystrix.adoc b/docs/src/main/asciidoc/spring-cloud-circuitbreaker-hystrix.adoc index 58ff85c52..19245f6dc 100644 --- a/docs/src/main/asciidoc/spring-cloud-circuitbreaker-hystrix.adoc +++ b/docs/src/main/asciidoc/spring-cloud-circuitbreaker-hystrix.adoc @@ -1,3 +1,5 @@ +include::_attributes.adoc[] + === Configuring Hystrix Circuit Breakers ==== Default Configuration diff --git a/docs/src/main/asciidoc/spring-cloud-netflix.adoc b/docs/src/main/asciidoc/spring-cloud-netflix.adoc index 013e7a09f..13ccb3bee 100755 --- a/docs/src/main/asciidoc/spring-cloud-netflix.adoc +++ b/docs/src/main/asciidoc/spring-cloud-netflix.adoc @@ -1,3 +1,6 @@ +include::_attributes.adoc[] + + :github-tag: master :github-repo: spring-cloud/spring-cloud-netflix :github-raw: https://raw.github.com/{github-repo}/{github-tag} @@ -5,6 +8,7 @@ :all: {asterisk}{asterisk} :nofooter: :branch: master + = Spring Cloud Netflix *{spring-cloud-version}* @@ -920,7 +924,7 @@ Creating a bean of one of those type and placing it in a `@RibbonClient` configu [source,java,indent=0] ---- -include::../../../spring-cloud-netflix-ribbon/src/test/java/org/springframework/cloud/netflix/ribbon/RibbonClientsPreprocessorIntegrationTests.java[tags=sample_override_ribbon_config,indent=0] +include::{project-root}/spring-cloud-netflix-ribbon/src/test/java/org/springframework/cloud/netflix/ribbon/RibbonClientsPreprocessorIntegrationTests.java[tags=sample_override_ribbon_config,indent=0] ---- The include statement in the preceding example replaces `NoOpPing` with `PingUrl` and provides a custom `serverListFilter`. @@ -931,7 +935,7 @@ A default configuration can be provided for all Ribbon Clients by using the `@Ri [source,java,indent=0] ---- -include::../../../spring-cloud-netflix-ribbon/src/test/java/org/springframework/cloud/netflix/ribbon/test/RibbonClientDefaultConfigurationTestsConfig.java[tags=sample_default_ribbon_config,indent=0] +include::{project-root}/spring-cloud-netflix-ribbon/src/test/java/org/springframework/cloud/netflix/ribbon/test/RibbonClientDefaultConfigurationTestsConfig.java[tags=sample_default_ribbon_config,indent=0] ---- @@ -2195,3 +2199,9 @@ Doing so improperly can result in resource management issues. include::maintenance-mode.adoc[] +== Configuration properties + +To see the list of all Spring Cloud Netflix related configuration properties please check link:appendix.html[the Appendix page]. + + +