= Consul Component
:doctitle: Consul
:shortname: consul
:artifactid: camel-consul
:description: Integrate with Consul service discovery and configuration store.
:since: 2.18
:supportlevel: Stable
:component-header: Both producer and consumer are supported
//Manually maintained attributes
:camel-spring-boot-name: consul

*Since Camel {since}*

*{component-header}*

The Consul component is a component for integrating your application with https://www.consul.io/[Hashicorp Consul].

Maven users will need to add the following dependency to their pom.xml
for this component:

[source,java]
-------------------------------------------------
    <dependency>
        <groupId>org.apache.camel</groupId>
        <artifactId>camel-consul</artifactId>
        <version>${camel-version}</version>
    </dependency>
-------------------------------------------------

== URI format

---------------------------------------
consul://domain?[options]
---------------------------------------

// component-configure options: START

// component-configure options: END

// component options: START
include::partial$component-configure-options.adoc[]
include::partial$component-endpoint-options.adoc[]
// component options: END

// endpoint options: START

// endpoint options: END



== Headers

[width="100%",options="header"]
|=======================================================================
|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 https://www.consul.io/api-docs[consul api] which should be addressed.

[width="100%",options="header"]
|===
| 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.

TIP: 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`.

[source,java]
----
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.

[source,java]
----
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())
...
----


include::spring-boot:partial$starter.adoc[]
