Antora migration (#269)
* Migrate Structure * Insert explicit ids for headers * Remove unnecessary asciidoc attributes * Copy default antora files * Fix indentation for all pages * Generate a default navigation * Remove includes * Enable Section Summary TOC for small pages * WIP * Additional antora migration * Additional antora migration --------- Co-authored-by: Marcin Grzejszczak <mgrzejszczak@vmware.com>
This commit is contained in:
Spencer Gibb
38
docs/antora-playbook.yml
Normal file
38
docs/antora-playbook.yml
Normal file
@@ -0,0 +1,38 @@
|
||||
antora:
|
||||
extensions:
|
||||
- '@springio/antora-extensions/partial-build-extension'
|
||||
- require: '@springio/antora-extensions/latest-version-extension'
|
||||
- require: '@springio/antora-extensions/inject-collector-cache-config-extension'
|
||||
- '@antora/collector-extension'
|
||||
- '@antora/atlas-extension'
|
||||
- require: '@springio/antora-extensions/root-component-extension'
|
||||
root_component_name: 'cloud-bus'
|
||||
site:
|
||||
title: Spring Cloud Bus
|
||||
url: https://docs.spring.io/spring-cloud-bus/reference/
|
||||
content:
|
||||
sources:
|
||||
- url: ./..
|
||||
branches: HEAD
|
||||
start_path: docs
|
||||
worktrees: true
|
||||
asciidoc:
|
||||
attributes:
|
||||
page-stackoverflow-url: https://stackoverflow.com/tags/spring-cloud
|
||||
page-pagination: ''
|
||||
hide-uri-scheme: '@'
|
||||
tabs-sync-option: '@'
|
||||
chomp: 'all'
|
||||
extensions:
|
||||
- '@asciidoctor/tabs'
|
||||
- '@springio/asciidoctor-extensions'
|
||||
sourcemap: true
|
||||
urls:
|
||||
latest_version_segment: ''
|
||||
runtime:
|
||||
log:
|
||||
failure_level: warn
|
||||
format: pretty
|
||||
ui:
|
||||
bundle:
|
||||
url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip
|
||||
12
docs/antora.yml
Normal file
12
docs/antora.yml
Normal file
@@ -0,0 +1,12 @@
|
||||
name: cloud-bus
|
||||
version: true
|
||||
title: spring-cloud-bus
|
||||
nav:
|
||||
- modules/ROOT/nav.adoc
|
||||
ext:
|
||||
collector:
|
||||
run:
|
||||
command: ./mvnw --no-transfer-progress -B process-resources -Pdocs -pl docs -Dantora-maven-plugin.phase=none -Dgenerate-docs.phase=none -Dgenerate-readme.phase=none -Dgenerate-cloud-resources.phase=none -Dmaven-dependency-plugin-for-docs.phase=none -Dmaven-dependency-plugin-for-docs-classes.phase=none -DskipTests
|
||||
local: true
|
||||
scan:
|
||||
dir: ./target/classes/antora-resources/
|
||||
8
docs/modules/ROOT/nav.adoc
Normal file
8
docs/modules/ROOT/nav.adoc
Normal file
@@ -0,0 +1,8 @@
|
||||
* xref:index.adoc[]
|
||||
* xref:quickstart.adoc[]
|
||||
* xref:spring-cloud-bus.adoc[]
|
||||
** xref:spring-cloud-bus/bus-endpoints.adoc[]
|
||||
** xref:spring-cloud-bus/addressing.adoc[]
|
||||
** xref:spring-cloud-bus/configuration.adoc[]
|
||||
** xref:spring-cloud-bus/custom-events.adoc[]
|
||||
* xref:appendix.adoc[]
|
||||
@@ -1,8 +1,6 @@
|
||||
:doctype: book
|
||||
:idprefix:
|
||||
:idseparator: -
|
||||
:toc: left
|
||||
:toclevels: 4
|
||||
:tabsize: 4
|
||||
:numbered:
|
||||
:sectanchors:
|
||||
@@ -1,14 +1,14 @@
|
||||
:numbered!:
|
||||
[appendix]
|
||||
[[common-application-properties]]
|
||||
== Common application properties
|
||||
= Common application properties
|
||||
:page-section-summary-toc: 1
|
||||
|
||||
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.
|
||||
This appendix provides a list of common Spring Cloud Bus 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[]
|
||||
include::partial$_configprops.adoc[]
|
||||
6
docs/modules/ROOT/pages/configprops.adoc
Normal file
6
docs/modules/ROOT/pages/configprops.adoc
Normal file
@@ -0,0 +1,6 @@
|
||||
[[configuration-properties]]
|
||||
= Configuration Properties
|
||||
|
||||
Below you can find a list of configuration properties.
|
||||
|
||||
include::partial$_configprops.adoc[]
|
||||
1
docs/modules/ROOT/pages/index.adoc
Executable file
1
docs/modules/ROOT/pages/index.adoc
Executable file
@@ -0,0 +1 @@
|
||||
include::intro.adoc[]
|
||||
@@ -1,3 +1,6 @@
|
||||
[[spring-cloud-bus-intro]]
|
||||
= Introduction
|
||||
|
||||
Spring Cloud Bus links the nodes of a distributed system with a lightweight message
|
||||
broker. This broker can then be used to broadcast state changes (such as configuration
|
||||
changes) or other management instructions. A key idea is that the bus is like a
|
||||
@@ -1,3 +1,6 @@
|
||||
[[spring-cloud-gateway-quickstart]]
|
||||
= Quickstart
|
||||
|
||||
Spring Cloud Bus works by adding Spring Boot autconfiguration if it detects itself on the
|
||||
classpath. To enable the bus, add `spring-cloud-starter-bus-amqp` or
|
||||
`spring-cloud-starter-bus-kafka` to your dependency management. Spring Cloud takes care of
|
||||
5
docs/modules/ROOT/pages/spring-cloud-bus.adoc
Normal file
5
docs/modules/ROOT/pages/spring-cloud-bus.adoc
Normal file
@@ -0,0 +1,5 @@
|
||||
[[spring-cloud-bus]]
|
||||
= Spring Cloud Bus
|
||||
:page-section-summary-toc: 1
|
||||
|
||||
*{spring-cloud-version}*
|
||||
43
docs/modules/ROOT/pages/spring-cloud-bus/addressing.adoc
Normal file
43
docs/modules/ROOT/pages/spring-cloud-bus/addressing.adoc
Normal file
@@ -0,0 +1,43 @@
|
||||
[[addressing]]
|
||||
= Addressing Instances
|
||||
:page-section-summary-toc: 1
|
||||
|
||||
[[addressing-an-instance]]
|
||||
== Addressing an Instance
|
||||
|
||||
Each instance of the application has a service ID, whose value can be set with
|
||||
`spring.cloud.bus.id` and whose value is expected to be a colon-separated list of
|
||||
identifiers, in order from least specific to most specific. The default value is
|
||||
constructed from the environment as a combination of the `spring.application.name` and
|
||||
`server.port` (or `spring.application.index`, if set). The default value of the ID is
|
||||
constructed in the form of `app:index:id`, where:
|
||||
|
||||
* `app` is the `vcap.application.name`, if it exists, or `spring.application.name`
|
||||
* `index` is the `vcap.application.instance_index`, if it exists,
|
||||
`spring.application.index`, `local.server.port`, `server.port`, or `0` (in that order).
|
||||
* `id` is the `vcap.application.instance_id`, if it exists, or a random value.
|
||||
|
||||
The HTTP endpoints accept a "`destination`" path parameter, such as
|
||||
`/busrefresh/customers:9000`, where `destination` is a service ID. If the ID
|
||||
is owned by an instance on the bus, it processes the message, and all other instances
|
||||
ignore it.
|
||||
|
||||
[[addressing-all-instances-of-a-service]]
|
||||
== Addressing All Instances of a Service
|
||||
|
||||
The "`destination`" parameter is used in a Spring `PathMatcher` (with the path separator
|
||||
as a colon -- `:`) to determine if an instance processes the message. Using the example
|
||||
from earlier, `/busenv/customers:**` targets all instances of the
|
||||
"`customers`" service regardless of the rest of the service ID.
|
||||
|
||||
[[service-id-must-be-unique]]
|
||||
== Service ID Must Be Unique
|
||||
|
||||
The bus tries twice to eliminate processing an event -- once from the original
|
||||
`ApplicationEvent` and once from the queue. To do so, it checks the sending service ID
|
||||
against the current service ID. If multiple instances of a service have the same ID,
|
||||
events are not processed. When running on a local machine, each service is on a different
|
||||
port, and that port is part of the ID. Cloud Foundry supplies an index to differentiate.
|
||||
To ensure that the ID is unique outside Cloud Foundry, set `spring.application.index` to
|
||||
something unique for each instance of a service.
|
||||
|
||||
44
docs/modules/ROOT/pages/spring-cloud-bus/bus-endpoints.adoc
Normal file
44
docs/modules/ROOT/pages/spring-cloud-bus/bus-endpoints.adoc
Normal file
@@ -0,0 +1,44 @@
|
||||
[[bus-endpoints]]
|
||||
= Bus Endpoints
|
||||
:page-section-summary-toc: 1
|
||||
|
||||
Spring Cloud Bus provides two endpoints, `/actuator/busrefresh` and `/actuator/busenv`
|
||||
that correspond to individual actuator endpoints in Spring Cloud Commons,
|
||||
`/actuator/refresh` and `/actuator/env` respectively.
|
||||
|
||||
[[bus-refresh-endpoint]]
|
||||
== Bus Refresh Endpoint
|
||||
The `/actuator/busrefresh` endpoint clears the `RefreshScope` cache and rebinds
|
||||
`@ConfigurationProperties`. See the <<refresh-scope,Refresh Scope>> documentation for
|
||||
more information.
|
||||
|
||||
To expose the `/actuator/busrefresh` endpoint, you need to add following configuration to your
|
||||
application:
|
||||
|
||||
[source,properties]
|
||||
----
|
||||
management.endpoints.web.exposure.include=busrefresh
|
||||
----
|
||||
|
||||
[[bus-env-endpoint]]
|
||||
== Bus Env Endpoint
|
||||
The `/actuator/busenv` endpoint updates each instances environment with the specified
|
||||
key/value pair across multiple instances.
|
||||
|
||||
To expose the `/actuator/busenv` endpoint, you need to add following configuration to your
|
||||
application:
|
||||
|
||||
[source,properties]
|
||||
----
|
||||
management.endpoints.web.exposure.include=busenv
|
||||
----
|
||||
|
||||
The `/actuator/busenv` endpoint accepts `POST` requests with the following shape:
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"name": "key1",
|
||||
"value": "value1"
|
||||
}
|
||||
----
|
||||
76
docs/modules/ROOT/pages/spring-cloud-bus/configuration.adoc
Normal file
76
docs/modules/ROOT/pages/spring-cloud-bus/configuration.adoc
Normal file
@@ -0,0 +1,76 @@
|
||||
[[configuration]]
|
||||
= Configuration
|
||||
:page-section-summary-toc: 1
|
||||
|
||||
[[customizing-the-message-broker]]
|
||||
== Customizing the Message Broker
|
||||
|
||||
Spring Cloud Bus uses https://cloud.spring.io/spring-cloud-stream[Spring Cloud Stream] to
|
||||
broadcast the messages. So, to get messages to flow, you need only include the binder
|
||||
implementation of your choice in the classpath. There are convenient starters for the bus
|
||||
with AMQP (RabbitMQ) and Kafka (`spring-cloud-starter-bus-[amqp|kafka]`). Generally
|
||||
speaking, Spring Cloud Stream relies on Spring Boot autoconfiguration conventions for
|
||||
configuring middleware. For instance, the AMQP broker address can be changed with
|
||||
`spring.rabbitmq.{asterisk}` configuration properties. Spring Cloud Bus has a handful of
|
||||
native configuration properties in `spring.cloud.bus.{asterisk}` (for example,
|
||||
`spring.cloud.bus.destination` is the name of the topic to use as the external
|
||||
middleware). Normally, the defaults suffice.
|
||||
|
||||
To learn more about how to customize the message broker settings, consult the Spring Cloud
|
||||
Stream documentation.
|
||||
|
||||
[[tracing-bus-events]]
|
||||
== Tracing Bus Events
|
||||
|
||||
Bus events (subclasses of `RemoteApplicationEvent`) can be traced by setting
|
||||
`spring.cloud.bus.trace.enabled=true`. If you do so, the Spring Boot `TraceRepository`
|
||||
(if it is present) shows each event sent and all the acks from each service instance. The
|
||||
following example comes from the `/trace` endpoint:
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"timestamp": "2015-11-26T10:24:44.411+0000",
|
||||
"info": {
|
||||
"signal": "spring.cloud.bus.ack",
|
||||
"type": "RefreshRemoteApplicationEvent",
|
||||
"id": "c4d374b7-58ea-4928-a312-31984def293b",
|
||||
"origin": "stores:8081",
|
||||
"destination": "*:**"
|
||||
}
|
||||
},
|
||||
{
|
||||
"timestamp": "2015-11-26T10:24:41.864+0000",
|
||||
"info": {
|
||||
"signal": "spring.cloud.bus.sent",
|
||||
"type": "RefreshRemoteApplicationEvent",
|
||||
"id": "c4d374b7-58ea-4928-a312-31984def293b",
|
||||
"origin": "customers:9000",
|
||||
"destination": "*:**"
|
||||
}
|
||||
},
|
||||
{
|
||||
"timestamp": "2015-11-26T10:24:41.862+0000",
|
||||
"info": {
|
||||
"signal": "spring.cloud.bus.ack",
|
||||
"type": "RefreshRemoteApplicationEvent",
|
||||
"id": "c4d374b7-58ea-4928-a312-31984def293b",
|
||||
"origin": "customers:9000",
|
||||
"destination": "*:**"
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
The preceding trace shows that a `RefreshRemoteApplicationEvent` was sent from
|
||||
`customers:9000`, broadcast to all services, and received (acked) by `customers:9000` and
|
||||
`stores:8081`.
|
||||
|
||||
To handle the ack signals yourself, you could add an `@EventListener` for the
|
||||
`AckRemoteApplicationEvent` and `SentApplicationEvent` types to your app (and enable
|
||||
tracing). Alternatively, you could tap into the `TraceRepository` and mine the data from
|
||||
there.
|
||||
|
||||
NOTE: Any Bus application can trace acks. However, sometimes, it is
|
||||
useful to do this in a central service that can do more complex
|
||||
queries on the data or forward it to a specialized tracing service.
|
||||
|
||||
76
docs/modules/ROOT/pages/spring-cloud-bus/custom-events.adoc
Normal file
76
docs/modules/ROOT/pages/spring-cloud-bus/custom-events.adoc
Normal file
@@ -0,0 +1,76 @@
|
||||
[[custom-events]]
|
||||
= Custom Events
|
||||
:page-section-summary-toc: 1
|
||||
|
||||
[[broadcasting-your-own-events]]
|
||||
== Broadcasting Your Own Events
|
||||
|
||||
The Bus can carry any event of type `RemoteApplicationEvent`. The default transport is
|
||||
JSON, and the deserializer needs to know which types are going to be used ahead of time.
|
||||
To register a new type, you must put it in a subpackage of
|
||||
`org.springframework.cloud.bus.event`.
|
||||
|
||||
To customise the event name, you can use `@JsonTypeName` on your custom class or rely on
|
||||
the default strategy, which is to use the simple name of the class.
|
||||
|
||||
NOTE: Both the producer and the consumer need access to the class definition.
|
||||
|
||||
[[registering-events-in-custom-packages]]
|
||||
=== Registering events in custom packages
|
||||
|
||||
If you cannot or do not want to use a subpackage of `org.springframework.cloud.bus.event`
|
||||
for your custom events, you must specify which packages to scan for events of type
|
||||
`RemoteApplicationEvent` by using the `@RemoteApplicationEventScan` annotation. Packages
|
||||
specified with `@RemoteApplicationEventScan` include subpackages.
|
||||
|
||||
For example, consider the following custom event, called `MyEvent`:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
package com.acme;
|
||||
|
||||
public class MyEvent extends RemoteApplicationEvent {
|
||||
...
|
||||
}
|
||||
----
|
||||
|
||||
You can register that event with the deserializer in the following way:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
package com.acme;
|
||||
|
||||
@Configuration
|
||||
@RemoteApplicationEventScan
|
||||
public class BusConfiguration {
|
||||
...
|
||||
}
|
||||
----
|
||||
|
||||
Without specifying a value, the package of the class where `@RemoteApplicationEventScan`
|
||||
is used is registered. In this example, `com.acme` is registered by using the package of
|
||||
`BusConfiguration`.
|
||||
|
||||
You can also explicitly specify the packages to scan by using the `value`, `basePackages`
|
||||
or `basePackageClasses` properties on `@RemoteApplicationEventScan`, as shown in the
|
||||
following example:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
package com.acme;
|
||||
|
||||
@Configuration
|
||||
//@RemoteApplicationEventScan({"com.acme", "foo.bar"})
|
||||
//@RemoteApplicationEventScan(basePackages = {"com.acme", "foo.bar", "fizz.buzz"})
|
||||
@RemoteApplicationEventScan(basePackageClasses = BusConfiguration.class)
|
||||
public class BusConfiguration {
|
||||
...
|
||||
}
|
||||
----
|
||||
|
||||
All of the preceding examples of `@RemoteApplicationEventScan` are equivalent, in that the
|
||||
`com.acme` package is registered by explicitly specifying the packages on
|
||||
`@RemoteApplicationEventScan`.
|
||||
|
||||
NOTE: You can specify multiple base packages to scan.
|
||||
|
||||
27
docs/pom.xml
27
docs/pom.xml
@@ -12,12 +12,13 @@
|
||||
</parent>
|
||||
<packaging>jar</packaging>
|
||||
<name>Spring Cloud Bus Docs</name>
|
||||
<description>Spring Cloud Docs</description>
|
||||
<description>Spring Cloud Bus Docs</description>
|
||||
<properties>
|
||||
<docs.main>spring-cloud-bus</docs.main>
|
||||
<main.basedir>${basedir}/..</main.basedir>
|
||||
<configprops.inclusionPattern>spring.cloud.bus.*</configprops.inclusionPattern>
|
||||
<upload-docs-zip.phase>deploy</upload-docs-zip.phase>
|
||||
<!-- Don't upload docs jar to central / repo.spring.io -->
|
||||
<maven-deploy-plugin-default.phase>none</maven-deploy-plugin-default.phase>
|
||||
</properties>
|
||||
<build>
|
||||
<sourceDirectory>src/main/asciidoc</sourceDirectory>
|
||||
@@ -36,26 +37,32 @@
|
||||
<profile>
|
||||
<id>docs</id>
|
||||
<build>
|
||||
<resources>
|
||||
<resource>
|
||||
<directory>src/main/antora/resources/antora-resources</directory>
|
||||
<filtering>true</filtering>
|
||||
</resource>
|
||||
</resources>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>pl.project13.maven</groupId>
|
||||
<artifactId>git-commit-id-plugin</artifactId>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.codehaus.mojo</groupId>
|
||||
<artifactId>exec-maven-plugin</artifactId>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-dependency-plugin</artifactId>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-resources-plugin</artifactId>
|
||||
<groupId>org.codehaus.mojo</groupId>
|
||||
<artifactId>exec-maven-plugin</artifactId>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.asciidoctor</groupId>
|
||||
<artifactId>asciidoctor-maven-plugin</artifactId>
|
||||
<groupId>io.spring.maven.antora</groupId>
|
||||
<artifactId>antora-component-version-maven-plugin</artifactId>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>io.spring.maven.antora</groupId>
|
||||
<artifactId>antora-maven-plugin</artifactId>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
|
||||
20
docs/src/main/antora/resources/antora-resources/antora.yml
Normal file
20
docs/src/main/antora/resources/antora-resources/antora.yml
Normal file
@@ -0,0 +1,20 @@
|
||||
version: @antora-component.version@
|
||||
prerelease: @antora-component.prerelease@
|
||||
|
||||
asciidoc:
|
||||
attributes:
|
||||
attribute-missing: 'warn'
|
||||
chomp: 'all'
|
||||
project-root: @maven.multiModuleProjectDirectory@
|
||||
github-repo: @docs.main@
|
||||
github-raw: https://raw.githubusercontent.com/spring-cloud/@docs.main@/@github-tag@
|
||||
github-code: https://github.com/spring-cloud/@docs.main@/tree/@github-tag@
|
||||
github-issues: https://github.com/spring-cloud/@docs.main@/issues/
|
||||
github-wiki: https://github.com/spring-cloud/@docs.main@/wiki
|
||||
spring-cloud-version: @project.version@
|
||||
github-tag: @github-tag@
|
||||
version-type: @version-type@
|
||||
docs-url: https://docs.spring.io/@docs.main@/docs/@project.version@
|
||||
raw-docs-url: https://raw.githubusercontent.com/spring-cloud/@docs.main@/@github-tag@
|
||||
project-version: @project.version@
|
||||
project-name: @docs.main@
|
||||
@@ -1,16 +1,18 @@
|
||||
[[spring-cloud-bus]]
|
||||
= Spring Cloud Bus
|
||||
include::_attributes.adoc[]
|
||||
:page-section-summary-toc: 1
|
||||
|
||||
include::intro.adoc[]
|
||||
|
||||
[[quick-start]]
|
||||
== Quick Start
|
||||
|
||||
include::quickstart.adoc[]
|
||||
|
||||
[[building]]
|
||||
== Building
|
||||
|
||||
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/building.adoc[]
|
||||
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/docs/modules/ROOT/partials/contributing.adoc[]
|
||||
|
||||
[[contributing]]
|
||||
== Contributing
|
||||
|
||||
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing.adoc[]
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
include::spring-cloud-bus.adoc[]
|
||||
@@ -1,231 +0,0 @@
|
||||
= Spring Cloud Bus
|
||||
include::_attributes.adoc[]
|
||||
|
||||
include::intro.adoc[]
|
||||
|
||||
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing-docs.adoc[]
|
||||
|
||||
== Quick Start
|
||||
|
||||
include::quickstart.adoc[]
|
||||
|
||||
== Bus Endpoints
|
||||
|
||||
Spring Cloud Bus provides two endpoints, `/actuator/busrefresh` and `/actuator/busenv`
|
||||
that correspond to individual actuator endpoints in Spring Cloud Commons,
|
||||
`/actuator/refresh` and `/actuator/env` respectively.
|
||||
|
||||
=== Bus Refresh Endpoint
|
||||
The `/actuator/busrefresh` endpoint clears the `RefreshScope` cache and rebinds
|
||||
`@ConfigurationProperties`. See the <<refresh-scope,Refresh Scope>> documentation for
|
||||
more information.
|
||||
|
||||
To expose the `/actuator/busrefresh` endpoint, you need to add following configuration to your
|
||||
application:
|
||||
|
||||
[source,properties]
|
||||
----
|
||||
management.endpoints.web.exposure.include=busrefresh
|
||||
----
|
||||
|
||||
=== Bus Env Endpoint
|
||||
The `/actuator/busenv` endpoint updates each instances environment with the specified
|
||||
key/value pair across multiple instances.
|
||||
|
||||
To expose the `/actuator/busenv` endpoint, you need to add following configuration to your
|
||||
application:
|
||||
|
||||
[source,properties]
|
||||
----
|
||||
management.endpoints.web.exposure.include=busenv
|
||||
----
|
||||
|
||||
The `/actuator/busenv` endpoint accepts `POST` requests with the following shape:
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"name": "key1",
|
||||
"value": "value1"
|
||||
}
|
||||
----
|
||||
|
||||
== Addressing an Instance
|
||||
|
||||
Each instance of the application has a service ID, whose value can be set with
|
||||
`spring.cloud.bus.id` and whose value is expected to be a colon-separated list of
|
||||
identifiers, in order from least specific to most specific. The default value is
|
||||
constructed from the environment as a combination of the `spring.application.name` and
|
||||
`server.port` (or `spring.application.index`, if set). The default value of the ID is
|
||||
constructed in the form of `app:index:id`, where:
|
||||
|
||||
* `app` is the `vcap.application.name`, if it exists, or `spring.application.name`
|
||||
* `index` is the `vcap.application.instance_index`, if it exists,
|
||||
`spring.application.index`, `local.server.port`, `server.port`, or `0` (in that order).
|
||||
* `id` is the `vcap.application.instance_id`, if it exists, or a random value.
|
||||
|
||||
The HTTP endpoints accept a "`destination`" path parameter, such as
|
||||
`/busrefresh/customers:9000`, where `destination` is a service ID. If the ID
|
||||
is owned by an instance on the bus, it processes the message, and all other instances
|
||||
ignore it.
|
||||
|
||||
== Addressing All Instances of a Service
|
||||
|
||||
The "`destination`" parameter is used in a Spring `PathMatcher` (with the path separator
|
||||
as a colon -- `:`) to determine if an instance processes the message. Using the example
|
||||
from earlier, `/busenv/customers:**` targets all instances of the
|
||||
"`customers`" service regardless of the rest of the service ID.
|
||||
|
||||
== Service ID Must Be Unique
|
||||
|
||||
The bus tries twice to eliminate processing an event -- once from the original
|
||||
`ApplicationEvent` and once from the queue. To do so, it checks the sending service ID
|
||||
against the current service ID. If multiple instances of a service have the same ID,
|
||||
events are not processed. When running on a local machine, each service is on a different
|
||||
port, and that port is part of the ID. Cloud Foundry supplies an index to differentiate.
|
||||
To ensure that the ID is unique outside Cloud Foundry, set `spring.application.index` to
|
||||
something unique for each instance of a service.
|
||||
|
||||
== Customizing the Message Broker
|
||||
|
||||
Spring Cloud Bus uses https://cloud.spring.io/spring-cloud-stream[Spring Cloud Stream] to
|
||||
broadcast the messages. So, to get messages to flow, you need only include the binder
|
||||
implementation of your choice in the classpath. There are convenient starters for the bus
|
||||
with AMQP (RabbitMQ) and Kafka (`spring-cloud-starter-bus-[amqp|kafka]`). Generally
|
||||
speaking, Spring Cloud Stream relies on Spring Boot autoconfiguration conventions for
|
||||
configuring middleware. For instance, the AMQP broker address can be changed with
|
||||
`spring.rabbitmq.{asterisk}` configuration properties. Spring Cloud Bus has a handful of
|
||||
native configuration properties in `spring.cloud.bus.{asterisk}` (for example,
|
||||
`spring.cloud.bus.destination` is the name of the topic to use as the external
|
||||
middleware). Normally, the defaults suffice.
|
||||
|
||||
To learn more about how to customize the message broker settings, consult the Spring Cloud
|
||||
Stream documentation.
|
||||
|
||||
== Tracing Bus Events
|
||||
|
||||
Bus events (subclasses of `RemoteApplicationEvent`) can be traced by setting
|
||||
`spring.cloud.bus.trace.enabled=true`. If you do so, the Spring Boot `TraceRepository`
|
||||
(if it is present) shows each event sent and all the acks from each service instance. The
|
||||
following example comes from the `/trace` endpoint:
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"timestamp": "2015-11-26T10:24:44.411+0000",
|
||||
"info": {
|
||||
"signal": "spring.cloud.bus.ack",
|
||||
"type": "RefreshRemoteApplicationEvent",
|
||||
"id": "c4d374b7-58ea-4928-a312-31984def293b",
|
||||
"origin": "stores:8081",
|
||||
"destination": "*:**"
|
||||
}
|
||||
},
|
||||
{
|
||||
"timestamp": "2015-11-26T10:24:41.864+0000",
|
||||
"info": {
|
||||
"signal": "spring.cloud.bus.sent",
|
||||
"type": "RefreshRemoteApplicationEvent",
|
||||
"id": "c4d374b7-58ea-4928-a312-31984def293b",
|
||||
"origin": "customers:9000",
|
||||
"destination": "*:**"
|
||||
}
|
||||
},
|
||||
{
|
||||
"timestamp": "2015-11-26T10:24:41.862+0000",
|
||||
"info": {
|
||||
"signal": "spring.cloud.bus.ack",
|
||||
"type": "RefreshRemoteApplicationEvent",
|
||||
"id": "c4d374b7-58ea-4928-a312-31984def293b",
|
||||
"origin": "customers:9000",
|
||||
"destination": "*:**"
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
The preceding trace shows that a `RefreshRemoteApplicationEvent` was sent from
|
||||
`customers:9000`, broadcast to all services, and received (acked) by `customers:9000` and
|
||||
`stores:8081`.
|
||||
|
||||
To handle the ack signals yourself, you could add an `@EventListener` for the
|
||||
`AckRemoteApplicationEvent` and `SentApplicationEvent` types to your app (and enable
|
||||
tracing). Alternatively, you could tap into the `TraceRepository` and mine the data from
|
||||
there.
|
||||
|
||||
NOTE: Any Bus application can trace acks. However, sometimes, it is
|
||||
useful to do this in a central service that can do more complex
|
||||
queries on the data or forward it to a specialized tracing service.
|
||||
|
||||
== Broadcasting Your Own Events
|
||||
|
||||
The Bus can carry any event of type `RemoteApplicationEvent`. The default transport is
|
||||
JSON, and the deserializer needs to know which types are going to be used ahead of time.
|
||||
To register a new type, you must put it in a subpackage of
|
||||
`org.springframework.cloud.bus.event`.
|
||||
|
||||
To customise the event name, you can use `@JsonTypeName` on your custom class or rely on
|
||||
the default strategy, which is to use the simple name of the class.
|
||||
|
||||
NOTE: Both the producer and the consumer need access to the class definition.
|
||||
|
||||
=== Registering events in custom packages
|
||||
|
||||
If you cannot or do not want to use a subpackage of `org.springframework.cloud.bus.event`
|
||||
for your custom events, you must specify which packages to scan for events of type
|
||||
`RemoteApplicationEvent` by using the `@RemoteApplicationEventScan` annotation. Packages
|
||||
specified with `@RemoteApplicationEventScan` include subpackages.
|
||||
|
||||
For example, consider the following custom event, called `MyEvent`:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
package com.acme;
|
||||
|
||||
public class MyEvent extends RemoteApplicationEvent {
|
||||
...
|
||||
}
|
||||
----
|
||||
|
||||
You can register that event with the deserializer in the following way:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
package com.acme;
|
||||
|
||||
@Configuration
|
||||
@RemoteApplicationEventScan
|
||||
public class BusConfiguration {
|
||||
...
|
||||
}
|
||||
----
|
||||
|
||||
Without specifying a value, the package of the class where `@RemoteApplicationEventScan`
|
||||
is used is registered. In this example, `com.acme` is registered by using the package of
|
||||
`BusConfiguration`.
|
||||
|
||||
You can also explicitly specify the packages to scan by using the `value`, `basePackages`
|
||||
or `basePackageClasses` properties on `@RemoteApplicationEventScan`, as shown in the
|
||||
following example:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
package com.acme;
|
||||
|
||||
@Configuration
|
||||
//@RemoteApplicationEventScan({"com.acme", "foo.bar"})
|
||||
//@RemoteApplicationEventScan(basePackages = {"com.acme", "foo.bar", "fizz.buzz"})
|
||||
@RemoteApplicationEventScan(basePackageClasses = BusConfiguration.class)
|
||||
public class BusConfiguration {
|
||||
...
|
||||
}
|
||||
----
|
||||
|
||||
All of the preceding examples of `@RemoteApplicationEventScan` are equivalent, in that the
|
||||
`com.acme` package is registered by explicitly specifying the packages on
|
||||
`@RemoteApplicationEventScan`.
|
||||
|
||||
NOTE: You can specify multiple base packages to scan.
|
||||
|
||||
== Configuration properties
|
||||
|
||||
To see the list of all Bus related configuration properties please check link:appendix.html[the Appendix page].
|
||||
Reference in New Issue
Block a user