From 45a5f28a603ce366a218d4c399dc7296750591f7 Mon Sep 17 00:00:00 2001 From: Eric Haberkorn Date: Fri, 9 Sep 2022 16:57:23 -0400 Subject: [PATCH] Update the service resolver documentation to include cluster peering failover and redirects (#14513) Update the service resolver documentation to include cluster peering failover and redirects --- .../config-entries/service-resolver.mdx | 142 +++++++++++++++++- 1 file changed, 134 insertions(+), 8 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index 056c7ba024..06d8e02f66 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -174,6 +174,57 @@ spec: +Enable failover to a WAN federated datacenter and then a cluster peer for all +service subsets. + + + +```hcl +Kind = "service-resolver" +Name = "web" +ConnectTimeout = "15s" +Failover = { + "*" = { + Targets = [ + {Datacenter = "dc3"}, + {Peer = "peer-01"} + ] + } +} +``` + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceResolver +metadata: + name: web +spec: + connectTimeout: 15s + failover: + '*': + targets: + - datacenter: "dc3" + - peer: "peer-01" +``` + +```json +{ + "Kind": "service-resolver", + "Name": "web", + "ConnectTimeout": "15s", + "Failover": { + "*": { + "Targets": [ + {"Datacenter": "dc3"}, + {"Peer": "peer-01"} + ] + } + } +} +``` + + + Failover to another datacenter and namespace for all service subsets. @@ -394,7 +445,7 @@ spec: name: 'DefaultSubset', type: 'string: ""', description: - 'The subset to use when no explicit subset is requested. If empty the unnamed subset is used.', + 'The subset to use when no explicit subset is requested. If empty, the unnamed subset is used.', }, { name: 'Subsets', @@ -406,7 +457,7 @@ spec: name: 'Filter', type: 'string: ""', description: `The [filter expression](/api-docs/features/filtering) to be used for selecting - instances of the requested service. If empty all healthy instances are + instances of the requested service. If empty, all healthy instances are returned. This expression can filter on the same selectors as the [Health API endpoint](/api-docs/health#filtering-2).`, }, @@ -476,6 +527,19 @@ spec: description: 'Specifies the destination datacenter to resolve the service from.', }, + { + name: 'Peer', + type: 'string: ""', + description: + `Specifies the destination cluster peer to resolve the target service name from. + Ensure that [intentions are defined](/docs/connect/cluster-peering/create-manage-peering#authorize-services-for-peers) + on the peered cluster to allow the source service to access this redirect target service as an upstream. When + the peer name is specified, Consul uses Envoy'services outlier detection to determine + the health of the redirect target based on whether communication attempts to the + redirect target are generally successful. Service health checks imported from a peer + are not considered in the health of a redirect target because they do not account for service + routers, splitters, and resolvers that may be defined in the peer for the target service.`, + }, ], }, { @@ -489,8 +553,8 @@ spec: string \`"*"\` is a wildcard that applies to any subset not otherwise specified here.

- \`Service\`, \`ServiceSubset\`, \`Namespace\`, and \`Datacenters\` cannot all be - empty at once.`, + \`Service\`, \`ServiceSubset\`, \`Namespace\`, \`Targets\`, and + \`Datacenters\` cannot all be empty at once.`, yaml: `Controls when and how to reroute traffic to an alternate pool of service instances.

@@ -498,8 +562,8 @@ spec: string \`"*"\` is a wildcard that applies to any subset not otherwise specified here.

- \`service\`, \`serviceSubset\`, \`namespace\`, and \`datacenters\` cannot all be - empty at once.`, + \`service\`, \`serviceSubset\`, \`namespace\`, \`targets\` and + \`datacenters\` cannot all be empty at once.`, }, children: [ { @@ -512,20 +576,82 @@ spec: name: 'ServiceSubset', type: 'string: ""', description: - 'The named subset of the requested service to resolve as the failover group of instances. If empty the default subset for the requested service is used.', + 'The named subset of the requested service to resolve as the failover group of instances. If empty, the default subset for the requested service is used.', }, { name: 'Namespace', enterprise: true, type: 'string: ""', description: - 'The namespace to resolve the requested service from to form the failover group of instances. If empty the current namespace is used.', + 'The namespace to resolve the requested service from to form the failover group of instances. If empty, the current namespace is used.', }, { name: 'Datacenters', type: 'array', description: 'A fixed list of datacenters to try during failover.', }, + { + name: 'Targets', + type: 'array', + description: `A fixed list of failover targets to try during + failover. It allows operators to express complicated failover + scenarios such as between cluster peers, WAN federated datacenters, and local admin partitions.`, + children: [ + { + name: 'Service', + type: 'string: ""', + description: + 'The service name to use for the failover target. If empty, the current service name is used.', + }, + { + name: 'ServiceSubset', + type: 'string: ""', + description: + 'The named subset to use for the failover target. If empty, the default subset for the requested service name is used.', + }, + { + name: 'Namespace', + enterprise: true, + type: 'string: ""', + description: + `The namespace to use for the failover target. If empty, the \`default\` namespace is used.`, + }, + { + name: 'Partition', + enterprise: true, + type: 'string: ""', + description: + `The admin partition within the same datacenter to use for the failover target. + If empty, the \`default\` partition is used. + To use an admin partition in a different datacenter for the failover target, + use the \`Peer\` field instead.`, + }, + { + name: 'Datacenter', + type: 'string: ""', + description: + `The WAN federated datacenter to use for the failover target. + If empty, the current datacenter is used. + To use a datacenter for the failover target that is connected + with a cluster peering relationship rather than WAN federation, + use the \`Peer\` field instead.`, + }, + { + name: 'Peer', + type: 'string: ""', + description: + `Specifies the destination cluster peer to resolve the target service name from. + Ensure that [intentions are defined](/docs/connect/cluster-peering/create-manage-peering#authorize-services-for-peers) + on the peered cluster to allow the source service to access this failover target service as an upstream. + When the peer name is specified, Consul uses Envoy's outlier detection + to determine the health of the failover target based on + whether communication attempts to the failover target are generally successful. + Service health checks imported from a peer are not considered in the health + of a failover target because they do not account for service routers, splitters, and resolvers + that may be defined in the peer for the target service.`, + }, + ], + }, ], }, {