From b937934b35de951697d80a8b520b5f4fcd186db0 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 11 Nov 2021 18:43:57 -0800 Subject: [PATCH] first commit for cross-partition support - partition exports section --- .../config-entries/partition-exports.mdx | 208 ++++++++++++++++++ website/data/docs-nav-data.json | 4 + 2 files changed, 212 insertions(+) create mode 100644 website/content/docs/connect/config-entries/partition-exports.mdx diff --git a/website/content/docs/connect/config-entries/partition-exports.mdx b/website/content/docs/connect/config-entries/partition-exports.mdx new file mode 100644 index 000000000..6cca176e9 --- /dev/null +++ b/website/content/docs/connect/config-entries/partition-exports.mdx @@ -0,0 +1,208 @@ +--- +layout: docs +page_title: 'Configuration Entry Kind: Partition Exports' +description: >- + The partition-exports configuration entry enables you to export services from a single file. + Settings in this config entry apply across all namespaces and federated datacenters. + Write access to the mesh resource is required. +--- + +# Partition Exports + +This topic describes the `partition-exports` configuration entry type. The `partition-exports` configuration entry enables Consul to export copies of services to other admin partitions from a single file. This enables your services to be networked across admin partitions. + +-> **v1.11.0+:** This config entry is supported in Consul versions 1.11.0+. + +## Introduction + +You can configure Consul to export services from one admin partition to one or more additional partitions by declaring the `partition-exports` configuration entry in the `kind` field. +Settings defined in the `partition-exports` configuration entry apply across all namespaces and federated datacenters. + +TO DO: More background info and info about the use case(s). + +## Requirements + +The consumer partition must have an `upstream` configuration that specifies the destination for the services. The upstream configuration \. + +Refer to the [Upstream Configuration Reference](/docs/connect/registration/service-registration#upstream-configuration-reference) for information on how to configure the upstream. + +## Usage + +1. Verify that your datacenter meets the conditions specified in the [Requirements](#requirements). +1. Specify the `partition-exports` configuration in the agent configuration file as described in [Configuration](#configuration). +1. Deploy the configuration per your runtime: + * [VM](/docs/install) + * [Kubernetes](/docs/k8s/installation/install) + +## Configuration + +Configure the following parameters to define a `partition-exports` configuration entry: + + + + +```hcl +Kind = "partition-exports" +Partition = "" +Services = [ + { + Name = "" + Namespace = "" + Consumers = [ + { + Partition = "" + }, + ] + } +] +``` + + + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +Kind: PartitionExports +Partition: +Services: +- Consumers: + - Partition: + Name: + Namespace: +``` + + + +```json +"Kind": "partition-exports", +"Partition": "", +"Services": [ + { + "Consumers": [ + { + "Partition": "" + } + ], + "Name": "", + "Namespace": "" + } +] +``` + + + +### Configuration Parameters + +The following table describes the parameters associated with the `partition-exports` configuration entry. + +| Parameter | Description | Required | Default | +| --- | --- | --- | --- | +| `Kind` | String value that enables the configuration entry. The value should always be `partition-exports` (HCL and JSON) or `PartitionExports` (YAML) | Required | None | +| `Partition` | String value that specifies the name of the partition that contains the services you want to export. | Required | None | +| `Services` | List of objects that specify which services to export. See [`Services`](#services) for details. | Required | None| +| `Meta` | Object that defines a map of the max 64 key/value pairs. | Optional | None | + +#### `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 name space 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 +Kind = "partition-exports" +Partition = "finance" + +Services = [ + { + Name = "billing" + Namespace = "default" + Consumers = [ + { + Partition = "frontend" + }, + { + Partition = "backend" + } + ] + }, + { + Name = "*" + Namespace = "*" + Consumers = [ + { + Partition = "monitoring" + } + ] + } +] +``` + + + + +```yaml +Kind: partition-exports +Partition: finance +Services: +- Consumers: + - Partition: frontend + - Partition: backend + Name: billing + Namespace: default +- Consumers: + - Partition: monitoring + Name: '*' + Namespace: '*' +``` + + + + +```json +"Kind": "partition-exports", + "Partition": "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: + +```shell-session +$ curl 'localhost:8500/v1/health/connect/billing?partition=finance' +``` + +See [Health HTTP Endpoing](/api-docs/health) for additional information. \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 86e6efc0a..9b9afb5a9 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -150,6 +150,10 @@ "title": "Mesh", "path": "connect/config-entries/mesh" }, + { + "title": "Partition Exports", + "path": "connect/config-entries/partition-exports" + }, { "title": "Proxy Defaults", "path": "connect/config-entries/proxy-defaults"