Exported Services

Enterprise

This feature requires Consul Enterprise.

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 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.
2. Specify the exported-services configuration in the agent configuration file (see config_entries) as described in Configuration.
3. 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

Exported services configuration syntax

HCL

• HCL
• Kubernetes YAML
• JSON

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

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>

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

Configuration Parameters

The following table describes the parameters associated with the exported-services configuration entry.

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.

HCL

• HCL
• Kubernetes YAML
• JSON

Kind = "exported-services"
Partition = "finance"
Name = "finance"
Services = [
  {
    Name = "billing"
    Namespace = "default"
    Consumers = [
        {
            Partition  = "frontend"
        },
        {
            Partition  = "backend"
        }
    ]
  },
  {
    Name      = "*"
    Namespace = "*"
    Consumers = [
        {
            Partition  = "monitoring"
        }
    ]
  }
]

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

"Kind": "exported-services",
  "Partition": "finance",
  "Name": "finance",
  "Services": [
    {
      "Consumers": [
        {
          "Partition": "frontend"
        },
        {
          "Partition": "backend"
        }
      ],
      "Name": "billing",
      "Namespace": "default"
    },
    {
      "Consumers": [
        {
          "Partition": "monitoring"
        }
      ],
      "Name": "*",
      "Namespace": "*"
    }
  ]

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:

$ 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 for additional information.