From 5511f1771970dd976f5e2016904ca6c8c49a3f39 Mon Sep 17 00:00:00 2001 From: Paul Banks Date: Fri, 13 Jul 2018 23:08:26 +0100 Subject: [PATCH] Add notes about hostname gotchas to Connect HTTPClient docs --- website/source/docs/connect/native/go.html.md | 27 ++++++++++++++++--- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/website/source/docs/connect/native/go.html.md b/website/source/docs/connect/native/go.html.md index 467390699..e2e453583 100644 --- a/website/source/docs/connect/native/go.html.md +++ b/website/source/docs/connect/native/go.html.md @@ -157,14 +157,33 @@ The HTTP client configuration automatically sends the correct client certificate, verifies the server certificate, and manages background goroutines for updating our certificates as necessary. --> **Important:** The HTTP client _requires_ the hostname is a Consul -DNS name. Static IP addresses and external DNS cannot be used with the -HTTP client. For these values, please use `svc.Dial` directly. - If the application already uses a manually constructed `*http.Client`, the `svc.HTTPDialTLS` function can be used to configure the `http.Transport.DialTLS` field to achieve equivalent behavior. +### Hostname Requirements + +The hostname used in the request URL is used to identify the logical service +discovery mechanism for the target. **It's not actually resolved via DNS** but +used as a logical identifier for a Consul service discovery mechanism. It has +the following specific limitations: + + * The sheme must be `https://`. + * It must be a Consul DNS name in one of the following forms: + * `.service[.].consul` to discover a healthy service + instance for a given service. + * `.query[.].consul` to discover an instance via + [Prepared Query](/api/query.html). + * The top-level domain _must_ be `.consul` even if your cluster has a custom + `domain` configured for it's DNS interface. This might be relaxed in the + future. + * Tag filters for services are not currently supported (i.e. + `tag1.web.service.consul`) however the same behaviour can be acheived using a + prepared query. + * External DNS names, raw IP addresses and so on will cause an error and should + be fetched using a separate `HTTPClient`. + + ## Raw TLS Connection For a raw `net.Conn` TLS connection, the `svc.Dial` function can be used.