luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

docs: destination docs for k8s

This commit is contained in:
DanStough 2022-08-02 14:57:58 -04:00 committed by Dan Stough
parent ca717ced07
commit 9842f046f1
1 changed files with 67 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
website/content/docs/k8s/connect/terminating-gateways.mdx
View File

@ -88,6 +88,58 @@ Registering the external services with Consul is a multi-step process:
### Register external services with Consul
There are two ways to register an external service with Consul:
1. If [`TransparentProxy`](/docs/k8s/helm#v-connectinject-transparentproxy) is enabled, you can declare external endpoints in the [`Destination`](/docs/connect/config-entries/service-defaults#terminating-gateway-destination) field of `service-defaults`.
1. You can add the service as a node in the Consul catalog.
#### Register an external service as a Destination
`Destination` fields allow clients to dial the external service directly and are valid only in [`TransparentProxy`](/docs/k8s/helm#v-connectinject-transparentproxy) mode.
The following table describes traffic behaviors when using `Destination`s to route traffic through a terminating gateway:
| External Services Layer | Client dials | Client uses TLS | Allowed | Notes |
|---|---|---|---|---|
| L4 | Hostname | Yes | Allowed | `CAFiles` are not allowed because traffic is already end-to-end encrypted by the client. |
| L4 | IP | Yes | Allowed | `CAFiles` are not allowed because traffic is already end-to-end encrypted by the client. |
| L4 | Hostname | No | Not allowed | The sidecar is not protocol aware and can not identify traffic going to the external service. |
| L4 | IP | No | Allowed | There are no limitations on dialing IPs without TLS. |
| L7 | Hostname | Yes | Not allowed | Because traffic is already encrypted before the sidecar, it cannot route as L7 traffic. |
| L7 | IP | Yes | Not allowed | Because traffic is already encrypted before the sidecar, it cannot route as L7 traffic. |
| L7 | Hostname | No | Allowed | A `Host` or `:authority` header is required. |
| L7 | IP | No | Allowed | There are no limitations on dialing IPs without TLS. |
You can provide a `caFile` to secure traffic between unencrypted clients that connect to external services through the terminating gateway.
Refer to [Create the configuration entry for the terminating gateway](/docs/k8s/connect/terminating-gateways#create-the-configuration-entry-for-the-terminating-gateway) for details.
Create a `service-defaults` custom resource for the external service:
<CodeBlockConfig filename="service-defaults.yaml">
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
name: example-https
spec:
protocol: tcp
destination:
addresses:
- "example.com"
port: 443
```
</CodeBlockConfig>
Apply the `ServiceDefaults` resource with `kubectl apply`:
```shell-session
$ kubectl apply --filename service-defaults.yaml
```
All other terminating gateway operations can use the name of the `service-defaults` in place of a typical Consul service name.
#### Register an external service as a Catalog Node
-> **Note:** Normal Consul services are registered with the Consul client on the node that
they're running on. Since this is an external service, there is no Consul node
to register it onto. Instead, we will make up a node name and register the
@ -205,15 +257,14 @@ metadata:
spec:
services:
- name: example-https
caFile: /etc/ssl/certs/ca-certificates.crt
```
</CodeBlockConfig>
If TLS is enabled, you must include the `caFile` parameter that points to the system trust store of the terminating gateway container. By default, the trust store is located in the `/etc/ssl/certs/ca-certificates.crt` directory.
-> **NOTE**: If TLS is enabled for external services registered through the Consul catalog, you must include the `caFile` parameter that points to the system trust store of the terminating gateway container.
By default, the trust store is located in the `/etc/ssl/certs/ca-certificates.crt` directory.
Configure the `caFile` parameter to point to the `/etc/ssl/cert.pem` directory if TLS is enabled and you are using one of the following components:
* Consul Helm chart 0.43 or older
* Consul Helm chart 0.43 or older
* Or an Envoy image with an alpine base image
Apply the `TerminatingGateway` resource with `kubectl apply`:
@ -313,6 +364,18 @@ deployment "static-client" successfully rolled out
You can verify connectivity of the static-client and terminating gateway via a curl command:
<CodeBlockConfig heading="External services registered with the Consul catalog">
```shell-session
$ kubectl exec deploy/static-client -- curl -vvvs --header "Host: example-https.com" http://localhost:1234/
```
</CodeBlockConfig>
<CodeBlockConfig heading="External services registered with `service-defaults` destinations">
```shell-session
$ kubectl exec deploy/static-client -- curl -vvvs https://example.com/
```
</CodeBlockConfig>