Exported services configuration entry reference

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.

Introduction

To configure Consul to export services contained in a Consul Enterprise admin partition or Consul CE 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

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 (refer to 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 = [
      {
        Peer = "<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:
        - peer: <name of the peered cluster that dials the exported service>

{
  "Kind": "exported-services",
  "Name": "default",
  "Services": [
    {
      "Name": "<name of service to export>",
      "Consumers": [
        {
          "Peer": "<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 = [
      {
        Peer = "<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:
        - peer: <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": [
        {
          "Peer": "<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>"
        }
      ]
    }
  ]
}

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 = [
      {
        SamenessGroup = "<name of the sameness group 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:
        - samenessGroup: <name of the sameness group 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": [
        {
          "SamenessGroup": "<name of the sameness group 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 CE.	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:

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

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 = [
        {
            Peer  = "web-shop"
        },
    ]
  },
  {
    Name      = "refunds"
    Consumers = [
        {
            Peer = "web-shop"
        }
    ]
  }
]

apiVersion: consul.hashicorp.com/v1alpha1
kind: ExportedServices
metadata:
  name: default
spec:
  services:
    - name: payments
      consumers:
        - peer: web-shop
    - name: refunds
      consumers:
        - peer: web-shop

{
  "Kind": "exported-services",
  "Name": "default",
  "Services": [
    {
      "Name": "payments",
      "Consumers": [
        {
          "Peer": "web-shop"
        }
      ]
    },
    {
      "Name": "refunds",
      "Consumers": [
        {
          "Peer": "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 = [
        {
            Peer  = "web-shop"
        },
    ]
  },
  {
    Name      = "refunds"
    Namespace = "billing"
    Consumers = [
        {
            Peer = "web-shop"
        }
    ]
  }
]

apiVersion: consul.hashicorp.com/v1alpha1
kind: ExportedServices
metadata:
  name: finance
spec:
  services:
    - name: payments
      namespace: billing
      consumers:
        - peer: web-shop
    - name: refunds
      namespace: billing
      consumers:
        - peer: web-shop

{
  "Kind": "exported-services",
  "Partition": "finance",
  "Name": "finance",
  "Services": [
    {
      "Name": "payments",
      "Namespace": "billing",
      "Consumers": [
        {
          "Peer": "web-shop"
        }
      ]
    },
    {
      "Name": "refunds",
      "Namespace": "billing",
      "Consumers": [
        {
          "Peer": "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 a service to a sameness group

The following example configures Consul to export a service named api to a defined group of partitions that belong to a separately defined sameness group named monitoring.

Kind = "exported-services"
Name = "default"

Services = [
  {
    Name      = "api"
    Consumers = [
        {
            SamenessGroup  = "monitoring"
        }
    ]
  }
]

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 = [
        {
            Peer  = "monitoring"
        },
        {
            Peer  = "platform"
        }
    ]
  }
]

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

apiVersion: consul.hashicorp.com/v1alpha1
kind: ExportedServices
metadata:
  name: finance
spec:
  services:
    - name: *
      namespace: *
      consumers:
        - peer: monitoring
        - peer: platform

{
  "Kind": "exported-services",
  "Partition": "finance",
  "Name": "finance",
  "Services": [
    {
      "Name": "*",
      "Namespace": "*",
      "Consumers": [
        {
          "Peer": "monitoring"
        },
        {
          "Peer": "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"
        }
      ]
    }
  ]S
}

If you experience errors using the wildcard to export services on Consul on Kubernetes, make sure the service token is attached to a policy that grants read access to all namespaces:

partition "default" {
  namespace "default" {
    query_prefix "" {
      policy = "read"
    }
  }
}

partition_prefix "" {
  namespace_prefix "" {
    node_prefix "" {
      policy = "read"
    }
    service_prefix "" {
      policy = "read"
    }
   }
}

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 either of the following permissions is required in the cluster where the query is made:

service:write permissions for any service.
service:read and node:read for all services and nodes, respectively.

If the call in the previous example is made from a service named web, then the request requires either:

A token with service:write permissions to web.
A token with service:read and node:read to all names in the datacenter.

Example ACL rules for reading imported services in Consul CE

service "web" {
    policy = "write"
}

# OR

service_prefix "" {
    policy = "read"
}
node_prefix "" {
    policy = "read"
}

{
  "service": {
    "web": {
      "policy": "write"
    }
  }
}

## OR

{
  "service_prefix": {
    "": {
      "policy": "read"
    }
  },
  "node_prefix": {
    "": {
      "policy": "read"
    }
  }
}

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 either of the following permissions is required in the cluster where the query is made:

service:write permissions for any service in the partition where the query is made.
service:read and node:read for all services and nodes, respectively, in any namespace and the exact partition where 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 requires either:

A token with service:write permissions to web in the frontend partition.
A token with service:read and node:read to all names in the frontend partition, for any namespace.

Example ACL rules for reading imported services from a partition in Consul Enterprise

partition "frontend" {
    namespace "dev" { # This could be any namespace
        service "web" {
            policy = "write"
        }
    }
}

# OR

partition "frontend" {
    namespace "dev" { # This could be any namespace
        service_prefix "" {
            policy = "read"
        }
        node_prefix "" {
            policy = "read"
        }
    }
}

{
  "partition": {
    "frontend": {
      "namespace": {
        ## The following could be any namespace
        "dev": {
          "service": {
            "web": {
              "policy": "write"
            }
          }
        }
      }
    }
  }
}


## OR

{
  "partition": {
    "frontend": {
      "namespace": {
        ## The following could be any namespace
        "dev": {
          "service_prefix": {
            "": {
              "policy": "read"
            }
          },
          "node_prefix": {
            "": {
              "policy": "read"
            }
          }
        }
      }
    }
  }
}

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 either of the following permissions is required in the cluster where the query is made:

service:write permissions for any service in the partition where the query is made.
service:read and node:read for all services and nodes, respectively, in any namespace and the exact partition where 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 requires either:

A token with service:write permissions to web in the frontend partition.
A token with service:read and node:read to all names in the frontend partition, for any namespace.

Example ACL rules for reading imported services from a peer in Consul Enterprise

partition "frontend" {
    namespace "dev" { # This could be any namespace
        service "web" {
            policy = "write"
        }
    }
}

# OR

partition "frontend" {
    namespace "dev" { # This could be any namespace
        service_prefix "" {
            policy = "read"
        }
        node_prefix "" {
            policy = "read"
        }
    }
}

{
  "partition": {
    "frontend": {
      "namespace": {
        ## The following could be any namespace
        "dev": {
          "service": {
            "web": {
              "policy": "write"
            }
          }
        }
      }
    }
  }
}

## OR

{
  "partition": {
    "frontend": {
      "namespace": {
        ## The following could be any namespace
        "dev": {
          "service_prefix": {
            "": {
              "policy": "read"
            }
          },
          "node_prefix": {
            "": {
              "policy": "read"
            }
          }
        }
      }
    }
  }
}

For additional information, refer to Health HTTP Endpoint.