-
Notifications
You must be signed in to change notification settings - Fork 85
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Introduce a Foreman & DNS guide #2957
Comments
Proposals for guides based on features (like DNS) always make me suspicious. I prefer guides based on stages of a product's lifecycle or a user's journey (planning, installation, deployment, maintenance, ...). But maybe we could make both work..? What if we avoid thinking about guides at this point and instead focus on reviewing and polishing assemblies related to DNS? Then, once we have those assemblies, we could decide whether an assembly belongs to, for example, an Installation guide or a dedicated DNS guide... or both (through assembly reuse). One thing that we used to consider for modular docs was adding tags to enable filtering and even building 'custom' guides. That's the way I'm thinking about this: adding hypothetical tags to assemblies ( To clarify: I'm not proposing we actually start using tags in assemblies. Thinking in terms of tags simply illustrates this approach to organizing content into guides. So, am I making things unnecessarily complicated here? :) |
The outline I have written out can be considered a base for an assembly. The steps I had in mind were:
I think you'd mostly have a problem with the last 2 steps. We can also change that into including the assembly in Installing Server too. Something to consider: we include firewalls? I don't like the current HUGE https://docs.theforeman.org/nightly/Installing_Server/index-katello.html#Port_and_firewall_requirements_foreman and would propose we drop port 53 there and instead add a firewall section to the DNS assembly. Once we've done this for DNS, I'd like to do the exact same thing for DHCP. TFTP is another candidate. |
@ekohl This sounds like a networking guide. Is that what you are proposing? RHEL and OpenShift have separate guides because network configuration is a huge and complex subject. |
@asteflova I might be wrong but I see DNS and DHCP as part of planning/installation. |
Networking guide could be an overloaded term, because networking can mean a lot of things. Networking can also mean how you set up networking for individual hosts. Or overall how you set up Foreman and individual Smart Proxies to be networked.
DNS and DHCP can be needed for provisioning, but if you (initially) don't use provisioning there's no reason to follow those steps. Or, if you use image based provisoning then DHCP may not be needed at all. You could still use DNS then. It may also be installed after the fact, when you do start using the features. I see it as an optional feature. That means you probably want to touch on it as part of planning (do you immediately install it or leave it until later?). |
I agree with this in principle. However, I feel some hesitation in using extremely specific terms in titles because, at some point, someone will probably want to add a section that does not quite fit the guide's title. Is there a title that is more specific than "networking" but with enough room to allow similar content? Maybe my concerns are groundless. If you think that we have enough material for this guide and that its contents are not likely to change/expand, then the title is fine.
True. But even if they are optional, I think they would still be part of planning/installation. I need to think about this. |
We can debate titles and naming is hard. I'd argue
Yes, IMHO this is something we should do in general. I'd think that the planning guide lays out the general path so that you, as the reader, can make a plan on how to deploy. So all the optional parts should be touched on. I can imagine we'd also describe other parts, like managing Puppet, Ansible, etc. |
Ewoud and I discussed possible titles. We both liked "Managing DNS and DHCP". Does that sound OK? |
Further tracking relations: in Foreman's navigation go to Infrastructure -> Domains. On that page you can can press help, which shows you the welcome page. It has this documentation button: That links to https://theforeman.org/manuals/nightly/index.html#4.4.7Networking. Satellite then maps this: You can see that both the Foreman manual and new docs don't talk about domains at all. For the old manual I couldn't find a chapter at all. New docs has https://docs.theforeman.org/nightly/Provisioning_Hosts/index-katello.html#Adding_a_Domain_to_Server_provisioning, but I think what I'm proposing here (either guide or a proper chapter) would be much better documentation. This was reported in https://bugzilla.redhat.com/show_bug.cgi?id=1995265. |
Foreman deals with DNS in various ways and I believe it deserves its own guide. Note we already have
guides/common/assembly_managing-dns-on-smart-proxies.adoc
which covers a reasonable part of this. #2933 expands it. The proposal here is to fully upgrade to a standalone guide.The guides that do need it (notably, provisioning) should link to it as a prerequisite.
Note DNS integration can happen both on the ProjectServer and SmartProxyServer. The steps should largely be identical.
Below is the rough outline I have in mind.
Title
Foreman internally tracks domains, which are linked to DNS domains.
Each domain can linked to a Smart Proxy which can manage the DNS records for hosts using the domain.
Typical times these are changed: when a host is created, a hostname is changed or a host is deleted.
You can view the domains by going to Infrastructure -> Domains
In addition to that, subnets can also be linked to a Smart Proxy to manage the reverse DNS records.
Similar blurb like for forward domains here
Setting up DNS integration
For managed domains or subnets, a Smart Proxy with the DNS feature can be chosen.
The Smart Proxy needs to be set up with a specific provider.
Various providers are:
Using Provider 1
For example, dns_nsupdate
Using Provider 2
For example, dns_powerdns
Disabling DNS integration
Include existing procedure to remove DNS integration here
The text was updated successfully, but these errors were encountered: