Exported Services

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.

Requirements

• A 1.11.0+ Consul Enteprise 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.

1. Verify that your datacenter meets the conditions specified in the .
2. Specify the exported-services configuration in the agent configuration file (see config_entries) as described in .
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 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"
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>

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",
"Name": "default",
"Services": [
  {
    "Name": "<name of service to export>",
    "Consumers": [
      {
        "PeerName": "<name of the peered cluster that dials the exported service>"
      }
    ]
  }
]

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

• : 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.

• : 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 the PeerName. Added in Consul 1.13.0.

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

HCL

• 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

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

"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 all services in the datacenter to the peered monitoring and platform clusters.

HCL

• 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

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

"Kind": "exported-services",
  "Name": "default",
  "Services": [
    {
      "Name": "*",
      "Namespace": "*"
      "Consumers": [
        {
          "PeerName": "monitoring"
        },
        {
          "PeerName": "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:

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 permissions for the frontend partition can read exports.