layout | page_title | description |
---|---|---|
docs |
Configuration Entry Kind: Exported Services |
The exported-services configuration entry enables you to export services from a single file. Settings in this configuration entry can apply to services in any namespace of the specified partition. Write access to the mesh resource is required. |
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.
-> v1.11.0+: This config entry is supported in Consul versions 1.11.0+.
To configure Consul to export services contained in a Consul Enterprise admin partition or Consul OSS 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.
- A 1.11.0+ Consul Enterprise binary or a 1.13.0+ Consul OSS binary.
- 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.
- 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.
Configure the following parameters to define a exported-services
configuration entry:
Kind = "exported-services"
Name = "default"
Services = [
{
Name = "<name of service to export>"
Consumers = [
{
PeerName = "<name of the peered cluster that dials the exported service>"
}
]
}
]
apiVersion: consul.hashicorp.com/v1alpha1
kind: ExportedServices
metadata:
name: default
spec:
services:
- name: <name of service to export>
consumers:
- peerName: <name of the peered cluster that dials the exported service>
"Kind": "exported-services",
"Name": "default",
"Services": [
{
"Name": "<name of service to export>",
"Consumers": [
{
"PeerName": "<name of the peered cluster that dials the exported service>"
}
]
}
]
Kind = "exported-services"
Partition = "<partition containing services to export>"
Name = "<partition containing services to export>"
Services = [
{
Name = "<name of service to export>"
Namespace = "<namespace in the partition containing the service to export>"
Consumers = [
{
PeerName = "<name of the peered cluster that dials the exported service>"
}
]
}
]
apiVersion: consul.hashicorp.com/v1alpha1
kind: ExportedServices
metadata:
name: <partition containing services to export>
spec:
services:
- name: <name of service to export>
namespace: <namespace in the partition containing the service to export>
consumers:
- peerName: <name of the peered cluster that dials the exported service>
"Kind": "exported-services",
"Partition": "<partition containing services to export>",
"Name": "<partition containing services to export>",
"Services": [
{
"Name": "<name of service to export>",
"Namespace": "<namespace in the partition containing the service to export>"
"Consumers": [
{
"PeerName": "<name of the peered cluster that dials the exported service>"
}
]
}
]
Kind = "exported-services"
Partition = "<partition containing services to export>"
Name = "<partition containing services to export>"
Services = [
{
Name = "<name of service to export>"
Namespace = "<namespace in the partition containing the service to export>"
Consumers = [
{
Partition = "<name of the partition that dials the exported service>"
}
]
}
]
apiVersion: consul.hashicorp.com/v1alpha1
kind: ExportedServices
metadata:
name: <partition containing services to export>
spec:
services:
- name: <name of service to export>
namespace: <namespace in the partition containing the service to export>
consumers:
- partition: <name of the partition that dials the exported service>
"Kind": "exported-services",
"Partition": "<partition containing services to export>",
"Name": "<partition containing services to export>",
"Services": [
{
"Name": "<name of service to export>",
"Namespace": "<namespace in the partition containing the service to export>"
"Consumers": [
{
"Partition": "<name of partition that dials the exported service>"
}
]
}
]
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 |
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 OSS. |
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 |
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
: 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.
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:
PeerName
: Specifies the name of the peered cluster to export the service to. A asterisk wildcard (*
) cannot be specified as thePeerName
. Added in Consul 1.13.0.Partition
: Specifies an admin partition in the datacenter to export the service to. A asterisk wildcard (*
) cannot be specified as thePartition
.
The following example configures Consul to export the payments
and refunds
services to the peered web-shop
cluster.
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
Kind = "exported-services"
Name = "default"
Services = [
{
Name = "payments"
Consumers = [
{
PeerName = "web-shop"
},
]
},
{
Name = "refunds"
Consumers = [
{
PeerName = "web-shop"
}
]
}
]
apiVersion: consul.hashicorp.com/v1alpha1
Kind: ExportedServices
metadata:
name: default
spec:
services:
- name: payments
consumers:
- peerName: web-shop
- name: refunds
consumers:
- peerName: web-shop
"Kind": "exported-services",
"Name": "default",
"Services": [
{
"Name": "payments",
"Consumers": [
{
"PeerName": "web-shop"
},
],
},
{
"Name": "refunds",
"Consumers": [
{
"PeerName": "web-shop"
}
]
}
]
The following example configures Consul to export the payments
and refunds
services from the billing
namespace of the finance
admin partition to the web-shop
peer.
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
Kind = "exported-services"
Partition = "finance"
Name = "finance"
Services = [
{
Name = "payments"
Namespace = "billing"
Consumers = [
{
PeerName = "web-shop"
},
]
},
{
Name = "refunds"
Namespace = "billing"
Consumers = [
{
PeerName = "web-shop"
}
]
}
]
apiVersion: consul.hashicorp.com/v1alpha1
Kind: ExportedServices
metadata:
name: finance
spec:
services:
- name: payments
namespace: billing
consumers:
- peerName: web-shop
- name: refunds
namespace: billing
consumers:
- peerName: web-shop
"Kind": "exported-services",
"Partition": "finance",
"Name": "finance",
"Services": [
{
"Name": "payments",
"Namespace": "billing"
"Consumers": [
{
"PeerName": "web-shop"
},
],
},
{
"Name": "refunds",
"Namespace": "billing",
"Consumers": [
{
"PeerName": "web-shop"
}
]
}
]
The following example configures Consul to export the payments
and refunds
services from the billing
namespace of the finance
admin partition to the web-shop
partition.
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
Kind = "exported-services"
Partition = "finance"
Name = "finance"
Services = [
{
Name = "payments"
Namespace = "billing"
Consumers = [
{
Partition = "web-shop"
},
]
},
{
Name = "refunds"
Namespace = "billing"
Consumers = [
{
Partition = "web-shop"
}
]
}
]
apiVersion: consul.hashicorp.com/v1alpha1
Kind: ExportedServices
metadata:
name: finance
spec:
services:
- name: payments
namespace: billing
consumers:
- partition: web-shop
- name: refunds
namespace: billing
consumers:
- partition: web-shop
"Kind": "exported-services",
"Partition": "finance",
"Name": "finance",
"Services": [
{
"Name": "payments",
"Namespace": "billing"
"Consumers": [
{
"Partition": "web-shop"
},
],
},
{
"Name": "refunds",
"Namespace": "billing",
"Consumers": [
{
"Partition": "web-shop"
}
]
}
]
The following example configures Consul to export all services in the datacenter to the peered monitoring
and platform
clusters.
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
Kind = "exported-services"
Name = "default"
Services = [
{
Name = "*"
Consumers = [
{
PeerName = "monitoring"
},
{
PeerName = "platform"
}
]
}
]
apiVersion: consul.hashicorp.com/v1alpha1
Kind: ExportedServices
metadata:
name: default
spec:
services:
- name: *
consumers:
- peerName: monitoring
- peerName: platform
"Kind": "exported-services",
"Name": "default",
"Services": [
{
"Name": "*",
"Namespace": "*"
"Consumers": [
{
"PeerName": "monitoring"
},
{
"PeerName": "platform"
}
]
}
]
The following example configures Consul to export all services in all namespaces of the finance
partition to the peered monitoring
and platform
clusters.
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
Kind = "exported-services"
Partition = "finance"
Name = "finance"
Services = [
{
Name = "*"
Namespace = "*"
Consumers = [
{
PeerName = "monitoring"
},
{
PeerName = "platform"
}
]
}
]
apiVersion: consul.hashicorp.com/v1alpha1
Kind: ExportedServices
metadata:
name: finance
spec:
services:
- name: *
namespace: *
consumers:
- peerName: monitoring
- peerName: platform
"Kind": "exported-services",
"Partition": "finance",
"Name": "finance",
"Services": [
{
"Name": "*",
"Namespace": "*"
"Consumers": [
{
"PeerName": "monitoring"
},
{
"PeerName": "platform"
}
]
}
]
The following example configures Consul to export all services in all namespaces of the finance
partition to the monitoring
and platform
partitions.
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
Kind = "exported-services"
Partition = "finance"
Name = "finance"
Services = [
{
Name = "*"
Namespace = "*"
Consumers = [
{
Partition = "monitoring"
},
{
Partition = "platform"
}
]
}
]
apiVersion: consul.hashicorp.com/v1alpha1
Kind: ExportedServices
metadata:
name: finance
spec:
services:
- name: *
namespace: *
consumers:
- partition: monitoring
- partition: platform
"Kind": "exported-services",
"Partition": "finance",
"Name": "finance",
"Services": [
{
"Name": "*",
"Namespace": "*"
"Consumers": [
{
"Partition": "monitoring"
},
{
"Partition": "platform"
}
]
}
]
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:
$ curl 'localhost:8500/v1/health/service/payments?peer=finance'
The following example queries the finance
partition for the imported payments
service:
$ curl 'localhost:8500/v1/health/service/payments?partition=finance'
An ACL token with service:write
permissions is required for the cluster the query is made from. If the call in the previous example is made from a service named web
in a partition named frontend
, then the request requires a token with write
permissions to web
in the frontend
partition.
Exports are available to all services in the consumer cluster. In the previous example, any service with write
permissions for the frontend
partition can read exports.
For additional information, refer to Health HTTP Endpoint.