added Alternative Domain section to dns page in docs #11458
Conversation
|
🤔 This PR has changes in the |
|
Thanks for putting this up, @kbabuadze. I'll get back to you by end of week! I'll also check with the docs team to see if they need to take a look, too. |
Co-authored-by: Evan Culver <eculver@users.noreply.github.com>
|
Hi @kbabuadze - sorry for the late response, I had something come up outside of work that caused this to fall off my radar. I'll take a pass at this before tomorrow and then ping the docs team. |
There was a problem hiding this comment.
@kbabuadze : looks good - thanks for writing this up! I suggested a few small changes. After those are addressed, I'll ping the docs team!
Co-authored-by: Jared Kirschner <85913323+jkirschner-hashicorp@users.noreply.github.com>
Co-authored-by: Jared Kirschner <85913323+jkirschner-hashicorp@users.noreply.github.com>
Co-authored-by: Jared Kirschner <85913323+jkirschner-hashicorp@users.noreply.github.com>
|
Hi @jkirschner-hashicorp, |
jkirschner-hashicorp
added
type/docs
|
@hashicorp/consul-docs : ready for your review! |
| By default, Consul responds to DNS queries only for its configured | ||
| [`domain`](/docs/agent/options#domain). | ||
|
|
||
| Some use cases require responding to queries for more than one domain, | ||
| such as during a DNS migration or to distinguish between internal and | ||
| external queries by using different domains. | ||
|
|
||
| Consul can be configured to respond to DNS queries on an alternative domain | ||
| through the [`alt_domain`](/docs/agent/options#alt_domain) agent configuration | ||
| option. Consul's DNS response will use the same domain as was used in the query. | ||
| For example, if `test-domain` is configured as the alternative domain, the following query: |
There was a problem hiding this comment.
| By default, Consul responds to DNS queries only for its configured | |
| [`domain`](/docs/agent/options#domain). | |
| Some use cases require responding to queries for more than one domain, | |
| such as during a DNS migration or to distinguish between internal and | |
| external queries by using different domains. | |
| Consul can be configured to respond to DNS queries on an alternative domain | |
| through the [`alt_domain`](/docs/agent/options#alt_domain) agent configuration | |
| option. Consul's DNS response will use the same domain as was used in the query. | |
| For example, if `test-domain` is configured as the alternative domain, the following query: | |
| By default, Consul responds to DNS queries in the `consul` domain, but you can set a specific domain for responding to DNS queries by configuring the [`domain`](/docs/agent/options#domain) parameter. | |
| You can specify an alternative domain for DNS queries in the `alt_domain` parameter. Configuring the [`alt_domain`](/docs/agent/options#alt_domain) agent parameter enables Consul to respond to DNS queries to the specified domain. | |
| In the following example, the `alt_domain` parameter is set to `test-domain`: | |
| <CodeTabs heading="agent.hcl"> | |
| <CodeBlockConfig> | |
| ```hcl | |
| alt_domain = "test-domain" |
"alt_domain" : "test-domain"The configuration enables the following test-domain query to run successfully:
I was just trying out some alternate wording to see if I could make it smoother. Please ignore if it doesn't seem like an improvement.
I also wanted to show an example of the `alt_domain` configuration. This is because it wasn't clear from looking at the entry in the reference whether the option took a Boolean value to enable alt domains or if you have to specify the actual domain as a string.
There was a problem hiding this comment.
My personal opinion is that the new wording leaves out some important information (e.g., why someone might want to use an alternative domain, what domain is used in the response). I personally prefer the previous wording.
However, it is problematic if the alt_domain configuration explanation doesn't make its use clear.
@trujillo-adam : Does it make more sense to update the description on the agent configuration option page to make its use more obvious (and perhaps include an example)? Or perhaps provide the configuration example here as you suggested, but also link to this "Alternative Domain" section on the DNS page from the alt_domain agent config option description?
There was a problem hiding this comment.
Ah, that's because I accidentally left a paragraph out that I planned on putting back in at line 102:
"In some instances, Consul may need to respond to queries in more than one domain, such as during a DNS migration or to distinguish between internal and external queries. "
As far as updating the alt_domain reference, yes, we should update it so include at least the data type and default. As far as cross-linking, we should probably think about it a little more. We ca either put 0 guidance in the reference and link internal pages for usage or vice versa. We're currently a little inconsistent. For now I think just adding a little more detail to the reference section is good enough.
There was a problem hiding this comment.
@kbabuadze - can you add the HCL configuration example @trujillo-adam suggested?
There was a problem hiding this comment.
@kbabuadze : two small comments regarding which Consul versions the alternative domain behaviors described apply to. Let me know what you think. Sorry I didn't catch these on my first review!
kisunji
added
the
waiting-reply
Co-authored-by: Jared Kirschner <85913323+jkirschner-hashicorp@users.noreply.github.com>
Co-authored-by: Jared Kirschner <85913323+jkirschner-hashicorp@users.noreply.github.com>
Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
|
@kbabuadze: I saw your recent commits. Have you made all the changes you wanted to make? If so, I can give a quick final read and then merge. Thanks! |
github-actions
bot
removed
the
waiting-reply
|
Hello @jkirschner-hashicorp, I've committed your suggestions. Thanks. |
Been there :) same thing happened to me when I needed to perform the first review! I'll take a look tomorrow (I want to load this up locally for a final check rather than just read the markdown). |
|
It looks like @trujillo-adam took a second look before me and agrees it looks good, so I'll go ahead and merge! Thanks for seeing this through, @kbabuadze! |
|
🍒 If backport labels were added before merging, cherry-picking will start automatically. To retroactively trigger a backport after merging, add backport labels and re-run https://circleci.com/gh/hashicorp/consul/516697. |
|
🍒✅ Cherry pick of commit eb90c7f onto |
added Alternative Domain section to dns page in docs
|
🍒✅ Cherry pick of commit eb90c7f onto |
added Alternative Domain section to dns page in docs
|
Just realized now that this is live that the section was placed above "Service Lookups", but should instead be after it. It doesn't make sense to have "Node Lookups", then "Alternative Domain", then "Service Lookups". I can fix that sometime next week. That was the original intent in our discussion here: #11348 (comment) Just didn't remember to check that when looking at the PR markdown... |
|
Oh boy, I missed that one too. I can do it if you want, that's just cutting the paragraph and pasting it just before the Caching. |
|
I think since it's merged already it would have to be a separate branch. You're welcome to do it :) I was actually going to use this as an excuse to try editing something directly in Github rather than making the changes locally, since as you said it's just a cut/paste that shouldn't require any previewing. |
|
@kbabuadze : I put up a PR for it: #11770 |
Hello @jkirschner-hashicorp ,
As promised here is a doc change PR adding alternative domain section to dns.mdx.
Please let me know if there are any change you would like me to make.
Thanks.