Service Discovery

The following section provides information on the use of using the Consul service registry for service discovery and also how you can deploy an API with Consul service catalog-based services.


In a microservice environment, usually the running service endpoints are not static. A service may have multiple upstream endpoints. Therefore, a service discovery mechanism is required for services to locate other services' upstream endpoints.

A service mesh is deployed when services want to communicate with each other with zero trust. Consul is a service mesh solution, which has been developed by HashiCorp. It solves the following problems that occur in microservice environments:

  • Service Discovery - through a centralized service registry.
  • Access control - through Intentions, and ACL
  • Configuration Management

WSO2 Choreo Connect can be used as an ingress gateway in an environment that uses Consul as a service mesh so that the APIs or services can be exposed to developers or API consumers while providing security, rate limiting, and other QoS.

Therefore, WSO2 Choreo Connect supports service discovery using the Consul so that upstream services can be discovered automatically. WSO2 Choreo Connect supports service discovery by connecting to Consul service registry and discover upstream services automatically.

Configure Choreo Connect with Consul

Add the following configuration under the Adapter section to the main configuration file of Choreo Connect (config.toml file).

  enabled = true
  url = ""
  pollInterval = 5
  ACLToken = "d3a2a719-4221-8c65-5212-58d4727427ac"
  mgwServiceName = "choreo-connect"
  serviceMeshEnabled = true
  caCertFile = "/home/wso2/security/truststore/consul/consul-agent-ca.pem"
  certFile = "/home/wso2/security/truststore/consul/local-dc-client-consul-0.pem"
  keyFile = "/home/wso2/security/truststore/consul/local-dc-client-consul-0-key.pem"

The following table describes above configuration.

enable Set this to true to enable Consul service discovery.
url The URL of the Consul HTTP API.
pollInterval The time interval (in seconds) in which the Choreo Connect should fetch updates from the Consul service catalog.
ACLToken Access Control Token generated using Consul. You should grant read access to services when creating the token
mgwServiceName Choreo Connect natively integrates with Consul service mesh. Therefore a service name is required to be defined in order to grant access to other services in mesh.
serviceMeshEnabled Set this to true if service mesh is enabled in Consul
caFile CaFile is the optional path to the CA certificate used for Consul communication, defaults to the system bundle if not specified.
certFile CertFile is the optional path to the certificate for Consul communication. If this is set, then you need to also set keyFile.
keyFile KeyFile is the optional path to the private key for Consul communication. If this is set, then you need to also set certFile.


  • mgwServiceName only need to be defined if service mesh enabled in Consul.
  • caFile, certFile, and keyFile are optional and needed when you need to override the Adapter's default CA, certificate, and private key.

  • If Consul agent's verify_incoming configuration is set to true, the certificate and private key have to be signed by the same CA that the Consul agents' certificates are signed.

Defining the endpoints

Syntax for defining the Consul upstream endpoints

You can define the Consul upstream endpoints by using the following syntax:

Example 1:


Example 2:
If you want more fine-grained access to your Consul services, you can limit the access to the upstream services by providing the datacenters and tags


Define the upstream endpoints to the Consul service catalog based services using one of the following methods.

  • Use WSO2 API Manager
  • Manually editing the Open API definition(when using APICTL)

Define Consul service catalog based services in WSO2 API Manager

Define the upstream endpoints to the Consul service catalog based services in WSO2 API Manager using the syntax described above via the WSO2 API Manger publisher portal.
You have to define the service using the above mentioned syntax and put it in the Production endpoint, the Sandbox endpoint or both.

Define Consul service catalog based services in an Open API definition (when using APICTL)

Define the upstream endpoints to the Consul service catalog based services directly in the OpenAPI definition file using the syntax explained above.
The definition should go under the urls section of x-wso2-production-endpoints or x-wso2-sandbox-endpoints (or both).

    - consul(<service_name>,<default_host>)
  type: load_balance
        - consul(pet,
      type: load_balance
        - application/json
        - application/xml
      description: ""
      operationId: addPet
        - description: Pet object that needs to be added to the store
          in: body
          name: body
          required: true
            $ref: '#/definitions/Pet'


  • Choreo Connect takes one pollInterval amount of time to update the upstreams' configuration after being updated in Consul service catalog.
  • At the initial start of the Adapter component, the requests that come to the Choreo Connect during are served via the default_host until the Adapter gets configuration from a Consul client.
  • Choreo Connect supports both API level and Resource level endpoints for Consul service discovery.
  • If multiple upstreams are discovered through Consul for the same service name, requests are Load Balanced to the upstreams.