Skip to content

Commit

Permalink
Update the service resolver documentation to include cluster peering …
Browse files Browse the repository at this point in the history 
…failover and redirects (hashicorp#14513)

Update the service resolver documentation to include cluster peering failover and redirects
  • Loading branch information
@erichaberkorn
erichaberkorn authored Sep 9, 2022
1 parent 208dd14 commit 45a5f28
Showing 1 changed file with 134 additions and 8 deletions.
142 changes: 134 additions & 8 deletions website/content/docs/connect/config-entries/service-resolver.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,57 @@ spec:

</CodeTabs>

Enable failover to a WAN federated datacenter and then a cluster peer for all
service subsets.

<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>

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

</CodeTabs>

<EnterpriseAlert product="consul">
Failover to another datacenter and namespace for all service subsets.
</EnterpriseAlert>
Expand Down Expand Up @@ -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',
Expand All @@ -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).`,
},
Expand Down Expand Up @@ -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.`,
},
],
},
{
Expand All @@ -489,17 +553,17 @@ spec:
string \`"*"\` is a wildcard that applies to any subset not otherwise
specified here.
<br><br>
\`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.
<br><br>
The map is keyed by the service subset it applies to and the special
string \`"*"\` is a wildcard that applies to any subset not otherwise
specified here.
<br><br>
\`service\`, \`serviceSubset\`, \`namespace\`, and \`datacenters\` cannot all be
empty at once.`,
\`service\`, \`serviceSubset\`, \`namespace\`, \`targets\` and
\`datacenters\` cannot all be empty at once.`,
},
children: [
{
Expand All @@ -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<string>',
description: 'A fixed list of datacenters to try during failover.',
},
{
name: 'Targets',
type: 'array<ServiceResolverFailoverTarget>',
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.`,
},
],
},
],
},
{
Expand Down

0 comments on commit 45a5f28

Please sign in to comment.