Consul
Since Camel 2.18
Both producer and consumer are supported
The Consul component is a component for integrating your application with Hashicorp Consul.
Maven users will need to add the following dependency to their pom.xml for this component:
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-consul</artifactId>
<version>${camel-version}</version>
</dependency>Configuring Options
Camel components are configured on two separate levels:
-
component level
-
endpoint level
Configuring Component Options
The component level is the highest level which holds general and common configurations that are inherited by the endpoints. For example a component may have security settings, credentials for authentication, urls for network connection and so forth.
Some components only have a few options, and others may have many. Because components typically have pre configured defaults that are commonly used, then you may often only need to configure a few options on a component; or none at all.
Configuring components can be done with the Component DSL, in a configuration file (application.properties|yaml), or directly with Java code.
Configuring Endpoint Options
Where you find yourself configuring the most is on endpoints, as endpoints often have many options, which allows you to configure what you need the endpoint to do. The options are also categorized into whether the endpoint is used as consumer (from) or as a producer (to), or used for both.
Configuring endpoints is most often done directly in the endpoint URI as path and query parameters. You can also use the Endpoint DSL as a type safe way of configuring endpoints.
A good practice when configuring options is to use Property Placeholders, which allows to not hardcode urls, port numbers, sensitive information, and other settings. In other words placeholders allows to externalize the configuration from your code, and gives more flexibility and reuse.
The following two sections lists all the options, firstly for the component followed by the endpoint.
Component Options
The Consul component supports 29 options, which are listed below.
| Name | Description | Default | Type |
|---|---|---|---|
connectTimeout (common) |
Connect timeout for OkHttpClient. |
Duration |
|
connectTimeoutMillis (common) |
Deprecated Connect timeout for OkHttpClient. Deprecation note: Use connectTimeout instead. |
Long |
|
consulClient (common) |
Reference to a com.orbitz.consul.Consul in the registry. |
Consul |
|
key (common) |
The default key. Can be overridden by CamelConsulKey. |
String |
|
pingInstance (common) |
Configure if the AgentClient should attempt a ping before returning the Consul instance. |
true |
boolean |
readTimeout (common) |
Read timeout for OkHttpClient. |
Duration |
|
readTimeoutMillis (common) |
Deprecated Read timeout for OkHttpClient. Deprecation note: Use readTimeout instead. |
Long |
|
tags (common) |
Set tags. You can separate multiple tags by comma. |
String |
|
url (common) |
The Consul agent URL. |
String |
|
writeTimeout (common) |
Write timeout for OkHttpClient. |
Duration |
|
writeTimeoutMillis (common) |
Deprecated Write timeout for OkHttpClient. Deprecation note: Use writeTimeout instead. |
Long |
|
bridgeErrorHandler (consumer) |
Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. |
boolean |
|
action (producer) |
The default action. Can be overridden by CamelConsulAction. |
String |
|
lazyStartProducer (producer) |
Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. |
boolean |
|
valueAsString (producer) |
Default to transform values retrieved from Consul i.e. on KV endpoint to string. |
boolean |
|
autowiredEnabled (advanced) |
Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc. |
true |
boolean |
configuration (advanced) |
Consul configuration. |
ConsulConfiguration |
|
consistencyMode (advanced) |
The consistencyMode used for queries, default ConsistencyMode.DEFAULT. Enum values:
|
DEFAULT |
ConsistencyMode |
datacenter (advanced) |
The data center. |
String |
|
nearNode (advanced) |
The near node to use for queries. |
String |
|
nodeMeta (advanced) |
The note meta-data to use for queries. |
List |
|
aclToken (security) |
Sets the ACL token to be used with Consul. |
String |
|
password (security) |
Sets the password to be used for basic authentication. |
String |
|
sslContextParameters (security) |
SSL configuration using an org.apache.camel.support.jsse.SSLContextParameters instance. |
SSLContextParameters |
|
useGlobalSslContextParameters (security) |
Enable usage of global SSL context parameters. |
boolean |
|
userName (security) |
Sets the username to be used for basic authentication. |
String |
|
blockSeconds (watch) |
The second to wait for a watch event, default 10 seconds. |
10 |
Integer |
firstIndex (watch) |
The first index for watch for, default 0. |
0 |
BigInteger |
recursive (watch) |
Recursively watch, default false. |
boolean |
Endpoint Options
The Consul endpoint is configured using URI syntax:
consul:apiEndpoint
with the following path and query parameters:
Path Parameters (1 parameters)
| Name | Description | Default | Type |
|---|---|---|---|
apiEndpoint (common) |
Required The API endpoint. |
String |
Query Parameters (28 parameters)
| Name | Description | Default | Type |
|---|---|---|---|
connectTimeout (common) |
Connect timeout for OkHttpClient. |
Duration |
|
connectTimeoutMillis (common) |
Deprecated Connect timeout for OkHttpClient. Deprecation note: Use connectTimeout instead. |
Long |
|
consulClient (common) |
Reference to a com.orbitz.consul.Consul in the registry. |
Consul |
|
key (common) |
The default key. Can be overridden by CamelConsulKey. |
String |
|
pingInstance (common) |
Configure if the AgentClient should attempt a ping before returning the Consul instance. |
true |
boolean |
readTimeout (common) |
Read timeout for OkHttpClient. |
Duration |
|
readTimeoutMillis (common) |
Deprecated Read timeout for OkHttpClient. Deprecation note: Use readTimeout instead. |
Long |
|
tags (common) |
Set tags. You can separate multiple tags by comma. |
String |
|
url (common) |
The Consul agent URL. |
String |
|
writeTimeout (common) |
Write timeout for OkHttpClient. |
Duration |
|
writeTimeoutMillis (common) |
Deprecated Write timeout for OkHttpClient. Deprecation note: Use writeTimeout instead. |
Long |
|
bridgeErrorHandler (consumer) |
Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. |
boolean |
|
exceptionHandler (consumer (advanced)) |
To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this option is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored. |
ExceptionHandler |
|
exchangePattern (consumer (advanced)) |
Sets the exchange pattern when the consumer creates an exchange. Enum values:
|
ExchangePattern |
|
action (producer) |
The default action. Can be overridden by CamelConsulAction. |
String |
|
lazyStartProducer (producer) |
Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. |
boolean |
|
valueAsString (producer) |
Default to transform values retrieved from Consul i.e. on KV endpoint to string. |
boolean |
|
consistencyMode (advanced) |
The consistencyMode used for queries, default ConsistencyMode.DEFAULT. Enum values:
|
DEFAULT |
ConsistencyMode |
datacenter (advanced) |
The data center. |
String |
|
nearNode (advanced) |
The near node to use for queries. |
String |
|
nodeMeta (advanced) |
The note meta-data to use for queries. |
List |
|
aclToken (security) |
Sets the ACL token to be used with Consul. |
String |
|
password (security) |
Sets the password to be used for basic authentication. |
String |
|
sslContextParameters (security) |
SSL configuration using an org.apache.camel.support.jsse.SSLContextParameters instance. |
SSLContextParameters |
|
userName (security) |
Sets the username to be used for basic authentication. |
String |
|
blockSeconds (watch) |
The second to wait for a watch event, default 10 seconds. |
10 |
Integer |
firstIndex (watch) |
The first index for watch for, default 0. |
0 |
BigInteger |
recursive (watch) |
Recursively watch, default false. |
boolean |
Headers
| Name | Type | Description |
|---|---|---|
CamelConsulAction |
String |
The Producer action |
CamelConsulKey |
String |
The Key on which the action should applied |
CamelConsulEventId |
String |
The event id (consumer only) |
CamelConsulEventName |
String |
The event name (consumer only) |
CamelConsulEventLTime |
Long |
The event LTime |
CamelConsulNodeFilter |
String |
The Node filter |
CamelConsulTagFilter |
String |
The tag filter |
CamelConsulSessionFilter |
String |
The session filter |
CamelConsulVersion |
int |
The data version |
CamelConsulFlags |
Long |
Flags associated with a value |
CamelConsulCreateIndex |
Long |
The internal index value that represents when the entry was created |
CamelConsulLockIndex |
Long |
The number of times this key has successfully been acquired in a lock |
CamelConsulModifyIndex |
Long |
The last index that modified this key |
CamelConsulOptions |
Object |
Options associated to the request |
CamelConsulResult |
boolean |
true if the response has a result |
CamelConsulSession |
String |
The session id |
CamelConsulValueAsString |
boolean |
To transform values retrieved from Consul i.e. on KV endpoint to string. |
CamelConsulServiceId |
String |
The service id for agent deregistration |
Api Endpoint
The apiEndpoint denotes the type of consul api which should be addressed.
| Domain | Producer | Consumer |
|---|---|---|
kv |
ConsulKeyValueProducer |
ConsulKeyValueConsumer |
event |
ConsulEventProducer |
ConsulEventConsumer |
agent |
ConsulAgentProducer |
- |
coordinates |
ConsulCoordinatesProducer |
- |
health |
ConsulHealthProducer |
- |
status |
ConsulStatusProducer |
- |
preparedQuery |
ConsulPreparedQueryProducer |
- |
catalog |
ConsulCatalogProducer |
- |
session |
ConsulSessionProducer |
- |
Producer Examples
As an example, we will show how to use the ConsulAgentProducer to register a service by means of the Consul agent api.
Registering and deregistering are examples for possible actions against the Consul agent api.
The desired action can be defined by setting the header ConsulConstants.CONSUL_ACTION to a value from the ConsulXXXActions interface of the respective Consul api. E.g. ConsulAgentActions contains the actions for the agent api.
If you set CONSUL_ACTION to ConsulAgentActions.REGISTER, the agent action REGISTER will be executed.
Which producer action invokes which consul api is defined by the respective producer.
E.g. the ConsulAgentProducer maps ConsulAgentActions.REGISTER to an invocation of AgentClient.register.
|
from("direct:registerFooService")
.setBody().constant(ImmutableRegistration.builder()
.id("foo-1")
.name("foo")
.address("localhost")
.port(80)
.build())
.setHeader(ConsulConstants.CONSUL_ACTION, constant(ConsulAgentActions.REGISTER))
.to("consul:agent");It is also possible to set a default action on the consul endpoint and do without the header:
consul:agent?action=REGISTER
Registering Camel Routes with Consul
You can employ a ServiceRegistrationRoutePolicy to register Camel routes as services with Consul automatically.
from("jetty:http://0.0.0.0:8080/service/endpoint").routeId("foo-1")
.routeProperty(ServiceDefinition.SERVICE_META_ID, "foo-1")
.routeProperty(ServiceDefinition.SERVICE_META_NAME, "foo")
.routePolicy(new ServiceRegistrationRoutePolicy())
...Spring Boot Auto-Configuration
When using consul with Spring Boot make sure to use the following Maven dependency to have support for auto configuration:
<dependency>
<groupId>org.apache.camel.springboot</groupId>
<artifactId>camel-consul-starter</artifactId>
<version>x.x.x</version>
<!-- use the same version as your Camel core version -->
</dependency>The component supports 90 options, which are listed below.
| Name | Description | Default | Type |
|---|---|---|---|
camel.cloud.consul.acl-token |
Sets the ACL token to be used with Consul |
String |
|
camel.cloud.consul.attributes |
Custom service attributes. |
Map |
|
camel.cloud.consul.block-seconds |
The time (in seconds) to wait for a watch event, default 10 seconds |
10 |
Integer |
camel.cloud.consul.check-interval |
How often (in seconds) a service has to be marked as healthy if its check is TTL or how often the check should run. Default is 5 seconds. |
5 |
Integer |
camel.cloud.consul.check-ttl |
The time (in seconds) to live for TTL checks. Default is 1 minute. |
60 |
Integer |
camel.cloud.consul.connect-timeout |
Connect timeout for OkHttpClient |
Duration |
|
camel.cloud.consul.connect-timeout-millis |
Use connectTimeout instead |
Long |
|
camel.cloud.consul.consistency-mode |
The consistencyMode used for queries, default ConsistencyMode.DEFAULT |
ConsistencyMode |
|
camel.cloud.consul.datacenter |
The data center |
String |
|
camel.cloud.consul.deregister-after |
How long (in seconds) to wait to deregister a service in case of unclean shutdown. Default is 1 hour. |
3600 |
Integer |
camel.cloud.consul.deregister-services-on-stop |
Should we remove all the registered services know by this registry on stop? |
true |
Boolean |
camel.cloud.consul.enabled |
Sets if the consul service registry should be enabled or not, default is false. |
false |
Boolean |
camel.cloud.consul.first-index |
The first index for watch for, default 0 |
0 |
BigInteger |
camel.cloud.consul.id |
Service Registry ID |
String |
|
camel.cloud.consul.near-node |
The near node to use for queries. |
String |
|
camel.cloud.consul.node-meta |
The note meta-data to use for queries. |
List |
|
camel.cloud.consul.order |
Service lookup order/priority. |
Integer |
|
camel.cloud.consul.override-service-host |
Should we override the service host if given ? |
true |
Boolean |
camel.cloud.consul.password |
Sets the password to be used for basic authentication |
String |
|
camel.cloud.consul.ping-instance |
Configure if the AgentClient should attempt a ping before returning the Consul instance |
true |
Boolean |
camel.cloud.consul.read-timeout |
Read timeout for OkHttpClient |
Duration |
|
camel.cloud.consul.read-timeout-millis |
Use readTimeout instead. |
Long |
|
camel.cloud.consul.recursive |
Recursively watch, default false |
false |
Boolean |
camel.cloud.consul.service-host |
Service host. |
String |
|
camel.cloud.consul.ssl-context-parameters |
SSL configuration using an org.apache.camel.support.jsse.SSLContextParameters instance. |
SSLContextParameters |
|
camel.cloud.consul.tags |
Set tags. You can separate multiple tags by comma. |
Set |
|
camel.cloud.consul.url |
The Consul agent URL |
String |
|
camel.cloud.consul.user-name |
Sets the username to be used for basic authentication |
String |
|
camel.cloud.consul.write-timeout |
Write timeout for OkHttpClient |
Duration |
|
camel.cloud.consul.write-timeout-millis |
Use writeTimeout instead. |
Long |
|
camel.cluster.consul.acl-token |
Sets the ACL token to be used with Consul |
String |
|
camel.cluster.consul.attributes |
Custom service attributes. |
Map |
|
camel.cluster.consul.block-seconds |
The time (in seconds) to wait for a watch event, default 10 seconds |
10 |
Integer |
camel.cluster.consul.connect-timeout |
Connect timeout for OkHttpClient |
Duration |
|
camel.cluster.consul.connect-timeout-millis |
Use connectTimeout instead |
Long |
|
camel.cluster.consul.consistency-mode |
The consistencyMode used for queries, default ConsistencyMode.DEFAULT |
ConsistencyMode |
|
camel.cluster.consul.datacenter |
The data center |
String |
|
camel.cluster.consul.enabled |
Sets if the consul cluster service should be enabled or not, default is false. |
false |
Boolean |
camel.cluster.consul.first-index |
The first index for watch for, default 0 |
0 |
BigInteger |
camel.cluster.consul.id |
Cluster Service ID |
String |
|
camel.cluster.consul.near-node |
The near node to use for queries. |
String |
|
camel.cluster.consul.node-meta |
The note meta-data to use for queries. |
List |
|
camel.cluster.consul.order |
Service lookup order/priority. |
Integer |
|
camel.cluster.consul.password |
Sets the password to be used for basic authentication |
String |
|
camel.cluster.consul.ping-instance |
Configure if the AgentClient should attempt a ping before returning the Consul instance |
true |
Boolean |
camel.cluster.consul.read-timeout |
Read timeout for OkHttpClient |
Duration |
|
camel.cluster.consul.read-timeout-millis |
Use readTimeout instead. |
Long |
|
camel.cluster.consul.recursive |
Recursively watch, default false |
false |
Boolean |
camel.cluster.consul.root-path |
Consul root path |
/camel |
String |
camel.cluster.consul.session-lock-delay |
The value for lockDelay |
5 |
Integer |
camel.cluster.consul.session-refresh-interval |
The value of wait attribute |
5 |
Integer |
camel.cluster.consul.session-ttl |
The value of TTL |
60 |
Integer |
camel.cluster.consul.ssl-context-parameters |
SSL configuration using an org.apache.camel.support.jsse.SSLContextParameters instance. |
SSLContextParameters |
|
camel.cluster.consul.tags |
Set tags. You can separate multiple tags by comma. |
Set |
|
camel.cluster.consul.url |
The Consul agent URL |
String |
|
camel.cluster.consul.user-name |
Sets the username to be used for basic authentication |
String |
|
camel.cluster.consul.write-timeout |
Write timeout for OkHttpClient |
Duration |
|
camel.cluster.consul.write-timeout-millis |
Use writeTimeout instead. |
Long |
|
camel.component.consul.acl-token |
Sets the ACL token to be used with Consul |
String |
|
camel.component.consul.action |
The default action. Can be overridden by CamelConsulAction |
String |
|
camel.component.consul.autowired-enabled |
Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc. |
true |
Boolean |
camel.component.consul.block-seconds |
The second to wait for a watch event, default 10 seconds |
10 |
Integer |
camel.component.consul.bridge-error-handler |
Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. |
false |
Boolean |
camel.component.consul.configuration |
Consul configuration. The option is a org.apache.camel.component.consul.ConsulConfiguration type. |
ConsulConfiguration |
|
camel.component.consul.connect-timeout |
Connect timeout for OkHttpClient. The option is a java.time.Duration type. |
Duration |
|
camel.component.consul.consistency-mode |
The consistencyMode used for queries, default ConsistencyMode.DEFAULT |
ConsistencyMode |
|
camel.component.consul.consul-client |
Reference to a com.orbitz.consul.Consul in the registry. The option is a com.orbitz.consul.Consul type. |
Consul |
|
camel.component.consul.datacenter |
The data center |
String |
|
camel.component.consul.enabled |
Whether to enable auto configuration of the consul component. This is enabled by default. |
Boolean |
|
camel.component.consul.first-index |
The first index for watch for, default 0. The option is a java.math.BigInteger type. |
BigInteger |
|
camel.component.consul.key |
The default key. Can be overridden by CamelConsulKey |
String |
|
camel.component.consul.lazy-start-producer |
Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. |
false |
Boolean |
camel.component.consul.near-node |
The near node to use for queries. |
String |
|
camel.component.consul.node-meta |
The note meta-data to use for queries. |
List |
|
camel.component.consul.password |
Sets the password to be used for basic authentication |
String |
|
camel.component.consul.ping-instance |
Configure if the AgentClient should attempt a ping before returning the Consul instance |
true |
Boolean |
camel.component.consul.read-timeout |
Read timeout for OkHttpClient. The option is a java.time.Duration type. |
Duration |
|
camel.component.consul.recursive |
Recursively watch, default false |
false |
Boolean |
camel.component.consul.ssl-context-parameters |
SSL configuration using an org.apache.camel.support.jsse.SSLContextParameters instance. The option is a org.apache.camel.support.jsse.SSLContextParameters type. |
SSLContextParameters |
|
camel.component.consul.tags |
Set tags. You can separate multiple tags by comma. |
String |
|
camel.component.consul.url |
The Consul agent URL |
String |
|
camel.component.consul.use-global-ssl-context-parameters |
Enable usage of global SSL context parameters. |
false |
Boolean |
camel.component.consul.user-name |
Sets the username to be used for basic authentication |
String |
|
camel.component.consul.value-as-string |
Default to transform values retrieved from Consul i.e. on KV endpoint to string. |
false |
Boolean |
camel.component.consul.write-timeout |
Write timeout for OkHttpClient. The option is a java.time.Duration type. |
Duration |
|
camel.cloud.consul.dc |
Deprecated Use datacenter instead |
String |
|
camel.cluster.consul.dc |
Deprecated Use datacenter instead |
String |
|
camel.component.consul.connect-timeout-millis |
Deprecated Connect timeout for OkHttpClient. Deprecation note: Use connectTimeout instead |
Long |
|
camel.component.consul.read-timeout-millis |
Deprecated Read timeout for OkHttpClient. Deprecation note: Use readTimeout instead |
Long |
|
camel.component.consul.write-timeout-millis |
Deprecated Write timeout for OkHttpClient. Deprecation note: Use writeTimeout instead. The option is a java.lang.Long type. |
Long |