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.

v1.11.0+: This config entry is supported in Consul versions 1.11.0+.

Introduction

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.

Requirements

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 named frontend requires an existing frontend partition.

Usage

Verify that your datacenter meets the conditions specified in the Requirements.
Specify the exported-services configuration in the agent configuration file (see config_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:

Exported services configuration syntax

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>"
      }
    ]
  }
]

Exported services configuration syntax

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>"
      }
    ]
  }
]

Exported services configuration syntax

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>"
      }
    ]
  }
]

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 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

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:

PeerName: Specifies the name of the peered cluster to export the service to. A asterisk wildcard (*) cannot be specified as the PeerName. 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 the Partition.

Examples

Exporting services to peered clusters

The following example configures Consul to export the payments and refunds services to the peered web-shop cluster.

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.

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.

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"
        }
      ]
    }
  ]

Exporting all services

The following example configures Consul to export all services in the datacenter to the peered monitoring and platform clusters.

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.

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.

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"
        }
      ]
    }
  ]

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:

$ curl 'localhost:8500/v1/health/service/payments?peer=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.