search

theforeman / foreman-documentation

Documentation for the Foreman Project and its ecosystem
https://docs.theforeman.org
Creative Commons Attribution Share Alike 4.0 International
15 stars 87 forks source link

Introduce a Foreman & DNS guide #2957

Open ekohl opened 3 months ago

ekohl commented 3 months ago

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. https://github.com/theforeman/foreman-documentation/pull/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

asteflova commented 3 months ago

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 (DNS, Installation, Deployment, Server, Proxy, ...) and then composing guides based on these tags (Server Installation guide = guide that includes all assemblies tagged with Server and Installation; DNS guide = guide that simply includes all assemblies tagged with DNS; ...).

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? :)

ekohl commented 3 months ago

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.

apinnick commented 3 months ago

@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.

apinnick commented 3 months ago

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..?

@asteflova I might be wrong but I see DNS and DHCP as part of planning/installation.

ekohl commented 3 months ago

This sounds like a networking guide.

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.

I might be wrong but I see DNS and DHCP as part of planning/installation.

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?).

apinnick commented 3 months ago

This sounds like a networking guide.

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.

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.

I might be wrong but I see DNS and DHCP as part of planning/installation.

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?).

True. But even if they are optional, I think they would still be part of planning/installation. I need to think about this.

ekohl commented 3 months ago

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.

We can debate titles and naming is hard. I'd argue DNS integration guide could be a good candidate.

True. But even if they are optional, I think they would still be part of planning/installation. I need to think about this.

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.

apinnick commented 3 months ago

Ewoud and I discussed possible titles. We both liked "Managing DNS and DHCP". Does that sound OK?

ekohl commented 3 months ago

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:

https://github.com/theforeman/foreman/blob/bf03a259a7e6fd65207b9a40639bb99e0e507dd8/app/views/domains/welcome.html.erb#L9

That links to https://theforeman.org/manuals/nightly/index.html#4.4.7Networking. Satellite then maps this:

https://github.com/RedHatSatellite/foreman_theme_satellite/blob/2b21579600aa37ac5d3abc4f3df6666b078be0df/lib/foreman_theme_satellite/documentation.rb#L34

Which is https://docs.theforeman.org/nightly/Provisioning_Hosts/index-katello.html#Adding_a_Subnet_to_Server_provisioning.

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.