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
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,15 +0,0 @@
|
||||
: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 Bus
|
||||
@@ -1,14 +0,0 @@
|
||||
|===
|
||||
|Name | Default | Description
|
||||
|
||||
|spring.cloud.bus.ack.destination-service | | Service that wants to listen to acks. By default null (meaning all services).
|
||||
|spring.cloud.bus.ack.enabled | `+++true+++` | Flag to switch off acks (default on).
|
||||
|spring.cloud.bus.content-type | | The bus mime-type.
|
||||
|spring.cloud.bus.destination | | Name of Spring Cloud Stream destination for messages.
|
||||
|spring.cloud.bus.enabled | `+++true+++` | Flag to indicate that the bus is enabled.
|
||||
|spring.cloud.bus.env.enabled | `+++true+++` | Flag to switch off environment change events (default on).
|
||||
|spring.cloud.bus.id | `+++application+++` | The identifier for this application instance.
|
||||
|spring.cloud.bus.refresh.enabled | `+++true+++` | Flag to switch off refresh events (default on).
|
||||
|spring.cloud.bus.trace.enabled | `+++false+++` | Flag to switch on tracing of acks (default off).
|
||||
|
||||
|===
|
||||
@@ -1,14 +0,0 @@
|
||||
: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[]
|
||||
@@ -1 +0,0 @@
|
||||
include::spring-cloud-bus.adoc[]
|
||||
@@ -1,6 +0,0 @@
|
||||
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
|
||||
distributed actuator for a Spring Boot application that is scaled out. However, it can
|
||||
also be used as a communication channel between apps. This project provides starters for
|
||||
either an AMQP broker or Kafka as the transport.
|
||||
@@ -1,28 +0,0 @@
|
||||
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
|
||||
the rest. Make sure the broker (RabbitMQ or Kafka) is available and configured. When
|
||||
running on localhost, you need not do anything. If you run remotely, use Spring Cloud
|
||||
Connectors or Spring Boot conventions to define the broker credentials, as shown in the
|
||||
following example for Rabbit:
|
||||
|
||||
.application.yml
|
||||
----
|
||||
spring:
|
||||
rabbitmq:
|
||||
host: mybroker.com
|
||||
port: 5672
|
||||
username: user
|
||||
password: secret
|
||||
----
|
||||
|
||||
The bus currently supports sending messages to all nodes listening or all nodes for a
|
||||
particular service (as defined by Eureka). The `/bus/*` actuator namespace has some HTTP
|
||||
endpoints. Currently, two are implemented. The first, `/bus/env`, sends key/value pairs to
|
||||
update each node's Spring Environment. The second, `/bus/refresh`, reloads each
|
||||
application's configuration, as though they had all been pinged on their `/refresh`
|
||||
endpoint.
|
||||
|
||||
NOTE: The Spring Cloud Bus starters cover Rabbit and Kafka, because those are the two most
|
||||
common implementations. However, Spring Cloud Stream is quite flexible, and the binder
|
||||
works with `spring-cloud-bus`.
|
||||
@@ -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