add config parameters doc for destination in service-defaults (#13950)

* add config parameters doc for destination in service-defaults

* add destination config example

* add documentations around tgateway config

* Apply suggestions from code review

Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Dan Stough <dan.stough@hashicorp.com>

* fix based on comments

* fix typo

* fix code tab array

* fix yaml description for addresses and port

* do not split yaml and hcl when the description is the same

Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
Co-authored-by: Dan Stough <dan.stough@hashicorp.com>
This commit is contained in:
Dhia Ayachi 2022-08-08 16:28:37 -04:00 committed by GitHub
parent 57afbb58ac
commit 11ec7b1f90
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 74 additions and 5 deletions

View File

@ -236,6 +236,50 @@ spec:
</Tab>
</Tabs>
### Terminating gateway destination
Create a default destination that will be assigned to a terminating gateway. A destination
represents a location outside the Consul cluster. They can be dialed directly when transparent proxy mode is enabled.
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
```hcl
Kind = "service-defaults"
Name = "test-destination"
Protocol = "tcp"
Destination {
Addresses = ["test.com","test.org"]
Port = 443
}
```
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
name: test-destination
spec:
destination:
addresses:
- "test.com"
- "test.org"
port: 443
```
```json
{
"Kind": "service-defaults",
"Name": "test-destination",
"Protocol": "http",
"Destination": {
"Addresses": ["test.com","test.org"],
"Port": 443
}
}
```
</CodeTabs>
## Available Fields
<ConfigEntryReference
@ -625,6 +669,24 @@ spec:
},
],
},
{
name: 'Destination',
type: 'DestinationConfig: <optional>',
description: `Controls configuration specific to destinations through terminating-gateway. Added in v1.13.0.`,
children: [
{
name: 'Addresses',
type: 'array<string>: []',
description:`List of addresses associated with the destination. This can be a hostname or an IP address.
Wildcards are not accepted.`,
},
{
name: 'Port',
type: 'int: 0',
description: `Port number associated with the destination.`,
},
]
},
{
name: 'MeshGateway',
type: 'MeshGatewayConfig: <optional>',

View File

@ -622,11 +622,12 @@ spec:
{
name: 'Services',
type: 'array<LinkedService>: <optional>',
description: `A list of services to link
description: `A list of services or destinations to link
with the gateway. The gateway will proxy traffic to these services. These linked services
must be registered with Consul for the gateway to discover their addresses. They must also
be registered in the same Consul datacenter as the terminating gateway. If Consul ACLs are
enabled, the Terminating Gateway's ACL token must grant <code>service:write</code> for all linked services.`,
be registered in the same Consul datacenter as the terminating gateway.
Destinations are an exception to this requirement, and only need to be defined as a service-defaults configuration entry in the same datacenter.
If Consul ACLs are enabled, the Terminating Gateway's ACL token must grant <code>service:write</code> for all linked services.`,
children: [
{
name: 'Name',

View File

@ -12,7 +12,7 @@ description: >-
-> **1.8.0+:** This feature is available in Consul versions 1.8.0 and newer.
Terminating gateways enable connectivity within your organizational network from services in the Consul service mesh to
services outside the mesh. These gateways effectively act as Connect proxies that can
services and [destinations](/docs/connect/config-entries/service-defaults#terminating-gateway-destination) outside the mesh. These gateways effectively act as Connect proxies that can
represent more than one service. They terminate Connect mTLS connections, enforce intentions,
and forward requests to the appropriate destination.
@ -55,6 +55,7 @@ Each terminating gateway needs:
1. A local Consul client agent to manage its configuration.
2. General network connectivity to services within its local Consul datacenter.
3. General network connectivity to services and destinations outside the mesh that are part of the gateway services list.
Terminating gateways also require that your Consul datacenters are configured correctly:
@ -96,7 +97,7 @@ to terminate mTLS connections on behalf of the linked services and then route th
If the Consul client agent on the gateway's node is not configured to use the default gRPC port, 8502, then the gateway's token
must also provide `agent:read` for its node's name in order to discover the agent's gRPC port. gRPC is used to expose Envoy's xDS API to Envoy proxies.
Linking services to a terminating gateway is done with a `terminating-gateway`
You can link services and destinations to a terminating gateway with a `terminating-gateway`
[configuration entry](/docs/connect/config-entries/terminating-gateway). This config entry can be applied via the
[CLI](/commands/config/write) or [API](/api-docs/config#apply-configuration).
@ -122,5 +123,10 @@ However, ensure that the [node name](/api-docs/catalog#node) for external servic
does not match the node name of any Consul client agent node. If the node name overlaps with the node name of a Consul client agent,
Consul's [anti-entropy sync](/docs/architecture/anti-entropy) will delete the services registered via the `/catalog/register` HTTP API endpoint.
Service-defaults [destinations](/docs/connect/config-entries/service-defaults#destination) let you
define endpoints external to the mesh and routable through a terminating gateway in transparent mode.
After you define a service-defaults configuration entry for each destination, you can use the service-default name as part of the terminating gateway services list.
If a service and a destination service-defaults have the same name, the terminating gateway will use the service.
For a complete example of how to register external services review the
[external services tutorial](https://learn.hashicorp.com/tutorials/consul/service-registration-external-services).