225 lines
8.3 KiB
Plaintext
225 lines
8.3 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: 'Configuration Entry Kind: Exported Services'
|
|
description: >-
|
|
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.
|
|
---
|
|
|
|
# Exported Services
|
|
|
|
<EnterpriseAlert />
|
|
|
|
This topic describes the `exported-services` configuration entry type. The `exported-services` configuration entry enables Consul to export service instances to other admin partitions from a single file. This enables your services to be networked across admin partitions. See [Admin Partitions](/docs/enterprise/admin-partitions) for additional information.
|
|
|
|
-> **v1.11.0+:** This config entry is supported in Consul Enterprise versions 1.11.0+.
|
|
|
|
## Introduction
|
|
|
|
You can configure Consul to export services contained in an admin partition to one or more additional partitions by declaring the `exported-services` configuration entry in the `kind` field. This enables you to route traffic between services in different clusters that share a single set of Consul servers.
|
|
|
|
You can configure the settings defined in the `exported-services` configuration entry to apply to all namespaces and federated datacenters.
|
|
|
|
## Requirements
|
|
|
|
- A Consul Enterprise binary
|
|
- A corresponding partition that the configuration entry can export to. For example, the `exported-services` configuration entry for a partition named `frontend` requires an existing `frontend` partition.
|
|
|
|
## Usage
|
|
|
|
1. Verify that your datacenter meets the conditions specified in the [Requirements](#requirements).
|
|
1. Specify the `exported-services` configuration in the agent configuration file (see [`config_entries`](/docs/agent/config/config-files#config_entries)) as described in [Configuration](#configuration).
|
|
1. Apply the configuration using one of the following methods:
|
|
- Kubernetes CRD: Refer to the [Custom Resource Definitions](/docs/k8s/crds) documentation for details.
|
|
- Issue the `consul config write` command: Refer to the [Consul Config Write](/commands/config/write) documentation for details.
|
|
|
|
## Configuration
|
|
|
|
Configure the following parameters to define a `exported-services` configuration entry:
|
|
|
|
<CodeTabs heading="Exported services configuration syntax" tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
<CodeBlockConfig>
|
|
|
|
```hcl
|
|
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 will dial the exported service>"
|
|
},
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
<CodeBlockConfig>
|
|
|
|
```yaml
|
|
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 will dial the exported service>
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
<CodeBlockConfig>
|
|
|
|
```json
|
|
"Kind": "exported-services",
|
|
"Partition": "<partition containing services to export>",
|
|
"Name": "<partition containing services to export>",
|
|
"Services": [
|
|
{
|
|
"Consumers": [
|
|
{
|
|
"Partition": "<name of partition that will dial the exported service>"
|
|
}
|
|
],
|
|
"Name": "<name of service to export>",
|
|
"Namespace": "<namespace in the partition containing the service to export>"
|
|
}
|
|
]
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
</CodeTabs>
|
|
|
|
### 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` | 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. | Required | None |
|
|
| `Services` | List of objects that specify which services to export. See [`Services`](#services) for details. | Required | None |
|
|
| `Meta` | Object that defines a map of the max 64 key/value pairs. | Optional | None |
|
|
|
|
### Services
|
|
|
|
The `Services` parameter contains one or more lists of parameters that specify which services to export, which namespaces the services reside, and the destination partition for the exported services. Each list in the `Services` block must contain the following parameters:
|
|
|
|
- `Name`: Specifies the name of the service to export. You can use a asterisk wildcard (`*`) to include all services in the namespace.
|
|
- `Namespace`: Specifies the namespace containing the services to export. You can use a asterisk wildcard (`*`) to include all namespaces in the partition.
|
|
- `Consumers`: Specifies one ore more objects that identify a destination partition for the exported services.
|
|
|
|
## Example
|
|
|
|
The following example configures the agent to export the `billing` service from the `default` namespace of the `finance` admin partition to the `frontend` and `backend` partitions. Additionally, all services in all namespaces within the `finance` partition will be exported to the `monitoring` partition.
|
|
|
|
<CodeTabs heading="" tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
<CodeBlockConfig>
|
|
|
|
```hcl
|
|
Kind = "exported-services"
|
|
Partition = "finance"
|
|
Name = "finance"
|
|
|
|
Services = [
|
|
{
|
|
Name = "billing"
|
|
Namespace = "default"
|
|
Consumers = [
|
|
{
|
|
Partition = "frontend"
|
|
},
|
|
{
|
|
Partition = "backend"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
Name = "*"
|
|
Namespace = "*"
|
|
Consumers = [
|
|
{
|
|
Partition = "monitoring"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
<CodeBlockConfig>
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
Kind: ExportedServices
|
|
metadata:
|
|
name: finance
|
|
spec:
|
|
services:
|
|
- name: mesh-gateway
|
|
namespace: default
|
|
consumers:
|
|
- partition: default
|
|
- name: billing
|
|
namespace: default
|
|
consumers:
|
|
- partition: frontend
|
|
- partition: backend
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
<CodeBlockConfig>
|
|
|
|
```json
|
|
"Kind": "exported-services",
|
|
"Partition": "finance",
|
|
"Name": "finance",
|
|
"Services": [
|
|
{
|
|
"Consumers": [
|
|
{
|
|
"Partition": "frontend"
|
|
},
|
|
{
|
|
"Partition": "backend"
|
|
}
|
|
],
|
|
"Name": "billing",
|
|
"Namespace": "default"
|
|
},
|
|
{
|
|
"Consumers": [
|
|
{
|
|
"Partition": "monitoring"
|
|
}
|
|
],
|
|
"Name": "*",
|
|
"Namespace": "*"
|
|
}
|
|
]
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
</CodeTabs>
|
|
|
|
## Reading Services
|
|
|
|
When an exported service has been imported to another partition, you can use the `health` REST API endpoint to query the service on the consumer partition. The following example queries the `finance` partition for the imported `billing` service:
|
|
|
|
```shell-session
|
|
$ curl 'localhost:8500/v1/health/connect/billing?partition=finance'
|
|
```
|
|
|
|
An ACL token with `service:write` permissions is required for the partition from which the query is made. If the call in the previous example is made from a service named `web` in a partition named `frontend`, then the request will require a token with `write` permissions to `web` in the `frontend` partition.
|
|
|
|
Exports are available to all services in the consumer partition. In the previous example, any service with `write` permissions for the `frontend` partition will be able to read exports.
|
|
|
|
See [Health HTTP Endpoint](/api-docs/health) for additional information.
|