• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Consul
  • Install
  • Tutorials
  • Documentation
  • API
  • CLI
  • Try Cloud(opens in new tab)
  • Sign up
Consul Home

Documentation

Skip to main contentOverview
  • What is Consul?


    • Overview
    • How Service Mesh Works
    • Configuration
      • Overview
      • Ingress Gateway
      • Mesh
      • Exported Services
      • Proxy Defaults
      • Service Defaults
      • Service Intentions
      • Service Resolver
      • Service Router
      • Service Splitter
      • Terminating Gateway
    • Service-to-service permissions - Intentions
    • Service-to-service permissions - Intentions (Legacy Mode)
    • Transparent Proxy
    • Connectivity Tasks
    • Distributed Tracing
    • Nomad
    • Kubernetes
    • Develop and Debug


  • HCP Consul


  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Consul
  3. Documentation
  4. Service Mesh
  5. Configuration Entries
  6. Exported Services
  • Consul
  • v1.13.x
  • v1.12.x
  • v1.11.x
  • v1.10.x
  • v1.9.x
  • v1.8.x

»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

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

ParameterDescriptionRequiredDefault
KindString value that enables the configuration entry. The value should always be exported-services (HCL and JSON) or ExportedServices (YAML)RequiredNone
Partition
Enterprise
String value that specifies the name of the partition that contains the services you want to export.
RequiredNone
NameString value that specifies the name of the partition that contains the services you want to export. Must be default in Consul OSS.RequiredNone
ServicesList of objects that specify which services to export. For details, refer to Services.RequiredNone
MetaObject that defines a map of the max 64 key/value pairs.OptionalNone

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.

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 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"
        }
    ]
  }
]
apiVersion: consul.hashicorp.com/v1alpha1
Kind: ExportedServices
metadata:
  name: default
spec:
  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"
        }
      ]
    }
  ]

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 OSS
Example ACL rules for reading imported services in Consul OSS
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
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
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.

Edit this page on GitHub

On this page

  1. Exported Services Configuration Entry
  2. Introduction
  3. Requirements
  4. Usage
  5. Configuration
  6. Examples
  7. Reading Services
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)