Exported Services Configuration Entry
This topic describes the exported-services
configuration entry type. The exported-services
configuration entry enables Consul to export service instances to other clusters from a single file and connect services across clusters. For additional information, refer to Cluster Peering and Admin Partitions.
Introduction
To configure Consul to export services contained in a Consul Enterprise admin partition or Consul CE datacenter to one or more additional clusters, create a new configuration entry and declare exported-services
in the kind
field. This configuration entry enables you to route traffic between services in different clusters.
You can configure the settings defined in the exported-services
configuration entry to apply to all namespaces in a Consul Enterprise admin partition.
Requirements
- Enterprise Only: A corresponding partition that the configuration entry can export from. For example, the
exported-services
configuration entry for a partition namedfrontend
requires an existingfrontend
partition.
Usage
- Verify that your datacenter meets the conditions specified in the Requirements.
- Specify the
exported-services
configuration in the agent configuration file (seeconfig_entries
) as described in Configuration. - Apply the configuration using one of the following methods:
- Kubernetes CRD: Refer to the Custom Resource Definitions documentation for details.
- Issue the
consul config write
command: Refer to the Consul Config Write documentation for details.
Configuration
Configure the following parameters to define a exported-services
configuration entry:
Configuration Parameters
The following table describes the parameters associated with the exported-services
configuration entry.
Parameter | Description | Required | Default |
---|---|---|---|
Kind | String value that enables the configuration entry. The value should always be exported-services (HCL and JSON) or ExportedServices (YAML) | Required | None |
Partition | Enterprise String value that specifies the name of the partition that contains the services you want to export. | Required | None |
Name | String value that specifies the name of the partition that contains the services you want to export. Must be default in Consul CE. | Required | None |
Services | List of objects that specify which services to export. For details, refer to Services . | Required | None |
Meta | Object that defines a map of the max 64 key/value pairs. | Optional | None |
Services
The Services
parameter contains a list of one or more parameters that specify which services to export, which namespaces the services reside, and the destination cluster for the exported services. Each item in the Services
list must contain the following parameters:
Name
: Specifies the name of the service to export. You can use an asterisk wildcard (*
) to include all services in the namespace.Namespace
: Enterprise Specifies the namespace containing the services to export. You can use an asterisk wildcard (*
) to include all namespaces in the partition.Consumers
: Specifies one or more objects that identify a destination cluster for the exported services.
Consumers
The Consumers
parameter contains a list of one or more parameters that specify the destination cluster for
an exported service. Each item in the Consumers
list must contain exactly one of the following parameters:
Peer
: Specifies the name of the peered cluster to export the service to. A asterisk wildcard (*
) cannot be specified as thePeer
. Added in Consul 1.13.0.Partition
: Enterprise Specifies an admin partition in the datacenter to export the service to. A asterisk wildcard (*
) cannot be specified as thePartition
.SamenessGroup
: Enterprise Specifies as sameness group to export the service to. A asterisk wildcard (*
) cannot be specified as theSamenessGroup
.
Examples
Exporting services to peered clusters
The following example configures Consul to export the payments
and refunds
services to the peered web-shop
cluster.
Exporting a service to a sameness group
The following example configures Consul to export a service named api
to a defined group of partitions that belong to a separately defined sameness group named monitoring
.
Exporting all services
The following example configures Consul to export all services in the datacenter to the peered monitoring
and platform
clusters.
Reading Services
When an exported service has been imported to another cluster, you can use the health
REST API endpoint to query the service on the consumer cluster.
The following example queries the finance
peer for the imported payments
service:
An ACL token with either of the following permissions is required in the cluster where the query is made:
service:write
permissions for any service.service:read
andnode:read
for all services and nodes, respectively.
If the call in the previous example is made from a service named web
, then the request requires either:
- A token with
service:write
permissions toweb
. - A token with
service:read
andnode:read
to all names in the datacenter.
For additional information, refer to Health HTTP Endpoint.