Document how to setup external OpenVox server for Smart Proxy

[maximiliankolb]

What changes are you introducing?

• Document installing smart_proxy_request_forwarder plugin
• Document how to setup external OpenVox server for Smart Proxies

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Refs https://theforeman.org/manuals/3.17/index.html#3.5.5FactsandtheENC
Refs #579

Contributor checklists

• I am okay with my commits getting squashed when you merge this PR.
• I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

• Foreman 3.17/Katello 4.19
• Foreman 3.16/Katello 4.18 (Satellite 6.18; orcharhino 7.6)
• Foreman 3.15/Katello 4.17
• Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4; orcharhino 7.5)
• Foreman 3.13/Katello 4.15 (EL9 only)
• Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
• We do not accept PRs for Foreman older than 3.12.

[github-actions]

The PR preview for c6d7040 is available at theforeman-foreman-documentation-preview-pr-4610.surge.sh

The following output files are affected by this PR:

• Managing_Configurations_Puppet/index-foremanctl-katello.html
• Managing_Configurations_Puppet/index-foremanctl-orcharhino.html
• Managing_Configurations_Puppet/index-katello.html
• Managing_Configurations_Puppet/index-orcharhino.html

show diff

show diff as HTML

[Lennonka]

@ekohl Mind taking a look? What to do about this for our downstream? Do we call it OpenVox or Puppet?

[ekohl]

Interesting approach, but architecturally I don't like the request forwarder approach because you're mixing identities.

Normally the Foreman Proxy represents a Puppetserver or OpenVox server somewhere. By default that is on the same machine, but it doesn't have to be. That's why there's a --foreman-proxy-puppet-url parameter.

However, there's a big gap that isn't well covered: the facts and reports are sent directly to Foreman, identified with the Smart Proxy's identity (= certificates). Ideally the Smart Proxy Puppet module would have an endpoint where Puppetserver / OpenVox server can send those and also query the ENC with proper authentication. Inline I've linked to the puppetca_token_whitelisting that already took that path. We just never finished it.

There are a few items inline that I consider blocking, like hiding the guides for anything but katello and orcharhino.

[ekohl]

Perhaps use puppet config set?

# puppet config set --section main reports "logs, foreman"
# puppet config set --section server node_terminus exec
# puppet config set --section server external_nodes "/opt/puppetlabs/puppet/bin/ruby /etc/puppetlabs/puppet/node.rb"

Though I'd strongly advise against including logs in reports because it fills up your disks. There is no rotation set up by default.

[ekohl]

IMHO we should never document manual steps to install Smart Proxy plugins and config files outside of the installer, which is why I'm tempted to hide all these steps in the katello build.

[ekohl]

It would be better if the puppetca_token_whitelisting provider was used. https://theforeman.org/manuals/3.17/index.html#puppetca_token_whitelisting describes how to do it manually. There are installer options for this, but you need manual steps on your OpenVox server too.

I think you need:

--foreman-proxy-puppetca-provider puppetca_token_whitelisting \
--foreman-proxy-puppet-url https://openvox.example.com:8140

And possibly configure the right certificate locations.

Then on the OpenVox server you need to install https://github.com/theforeman/smart-proxy/blob/develop/extra/puppet_sign.rb and configure the authentication.

[ekohl]

Why don't you configure the Smart Proxy to query the remote OpenVox server? As noted above, --foreman-proxy-puppet-url https://openvox.example.com:8140 provided you have set up authentication on the OpenVox server side.

[ekohl]

Please always use the installer to modify this because the installer will revert it. It should have a --foreman-proxy-trusted-hosts flag but note we also have some default values for that. Passing 1 value clears the others. The default is itself on Foreman and Foreman + itself on Smart Proxies.

[maximiliankolb]

Thanks Ewoud for your input; I appreciate it. I will convert this to draft until I get some more insights downstream too.

I applied some suggestions already and rebased it to HEAD of "master".

[jtruestedt]

Thanks for the feedback Ewoud.
So maybe to explain the origin of the request-forwarder idea:
We have several customers using puppet/openvox but they use it with r10k and do not want to configure it via orcharhino/foreman but do that in there git repository with a dedicated hiera-structure. However, as they want to have a dashboard and overview if everything is fine with the puppet configuration, they want to have there facts/reports available in orcharhino/foreman. So instead of installing a full blown smart proxy and configuring a full ENC they just want to send reports/facts.
Like you mentioned currently this endpoint is only available on the central instance - but with big networks this instance is not always reachable (directly) why they want to send it to the proxy. Previously, the proxies had 8443 as reverse proxy to the main instance to work around this, but since this was removed, we got requests, that they still need something to send their reports to the proxy so that they are forwarded to the main-instance - and they still did not want to install a smart proxy on their puppetservers to avoid additional load there (mainly - in some cases there where also some network-architecture related discussions), so we came up with the approach to have an endpoint on the proxy where those reports can be sent too.
So the important part is to have something on proxies where reports/facts can be sent too and then are somehow forwarded to the main instance. And this connection usually is meant to be only in one direction: puppetserver sending to the proxy (which then forwards it).

I think the detailed comments to the documentation are valid points.

[ekohl]

Thanks for the feedback. I'll need to get back to a longer reply, but I want to leave theforeman/puppet-puppetserver_foreman#69 (review) here. There I laid out a lot of context of how to have a more native integration in OpenVox. What isn't explicitly called out there, but something to consider: include all the integration bits in OpenVox itself so you only need to change configuration. If you then use https://github.com/OpenVoxProject/container-openvoxserver it should be fairly straight forward with environment variables.

Note those are just general thoughts. The exact implementation details could be different.

[maximiliankolb]

Thanks Jonas and Ewoud for your input. I spoke with @knoppi about it. We will need to spend more time on yet. I will keep this upstream PR as is for now and apply changes later on.

[ekohl]

This design is certainly something that with my downstream hat on is interesting. About a year or 2 ago I spent quite a bit of time thinking about it but never got around to implementing it properly. In light of containerization I think we should revisit that again.

Right now it's a very busy period for me, but when it settles down a bit I can try to dig up my notes and share them in something that's readable/understandable for others. If I forget then please remind me.