From 45dead0f51920357726ffcec0ded56721a988b59 Mon Sep 17 00:00:00 2001 From: "Eric D. Helms" Date: Fri, 30 Aug 2024 12:22:41 -0400 Subject: [PATCH 1/2] Rely on official documentation for how to perform operations with the installer --- KATELLO.md | 218 ----------------------------------------------------- README.md | 104 ++----------------------- 2 files changed, 7 insertions(+), 315 deletions(-) delete mode 100644 KATELLO.md diff --git a/KATELLO.md b/KATELLO.md deleted file mode 100644 index 041b0223..00000000 --- a/KATELLO.md +++ /dev/null @@ -1,218 +0,0 @@ -# Katello Installer - -A set of tools to properly configure Katello with Foreman in production and development. - -## Production Usage - -``` -$ yum install -y foreman-installer-katello - -# install Katello with Foreman and smart proxy with Puppet and Puppetca -$ foreman-installer --scenario katello -``` - -### Production Examples - -``` -# Install also provisioning-related services - -foreman-installer --scenario "katello"\ - --foreman-proxy-dns "true"\ - --foreman-proxy-dns-forwarders "8.8.8.8"\ - --foreman-proxy-dns-forwarders "8.8.4.4"\ - --foreman-proxy-dns-interface "virbr1"\ - --foreman-proxy-dns-zone "example.com"\ - --foreman-proxy-dhcp "true"\ - --foreman-proxy-dhcp-interface "virbr1"\ - --foreman-proxy-tftp "true"\ - --foreman-proxy-content-puppet "true"\ - --foreman-proxy-puppetca "true" - -# Install only DNS with smart proxy - -foreman-installer --scenario "katello"\ - --foreman-proxy-dns "true"\ - --foreman-proxy-dns-forwarders "8.8.8.8" - --foreman-proxy-dns-forwarders "8.8.4.4"\ - --foreman-proxy-dns-interface "virbr1"\ - --foreman-proxy-dns-zone "example.com"\ - --foreman-proxy-content-puppet "false"\ - --foreman-proxy-puppetca "false" - -# Generate certificates for installing Foreman proxy on another system -foreman-proxy-certs-generate --foreman-proxy-fqdn "myforeman-proxy-content.example.com"\ - --certs-tar ~/myforeman-proxy-content.example.com-certs.tar - -# Copy the ~/myforeman-proxy.example.com-certs.tar to the foreman-proxy system -# register the system to Katello and run: -foreman-installer --scenario "foreman-proxy-content"\ - --foreman-proxy-register-in-foreman "true"\ - --foreman-proxy-foreman-base-url "https://master.example.com"\ - --foreman-proxy-trusted-hosts "master.example.com"\ - --foreman-proxy-trusted-hosts "myforeman-proxy.example.com"\ - --foreman-proxy-oauth-consumer-key "foreman_oauth_key"\ - --foreman-proxy-oauth-consumer-secret "foreman_oauth_secret"\ - --foreman-proxy-content-pulp-oauth-secret "pulp_oauth_secret"\ - --foreman-proxy-content-certs-tar "/root/myforeman-proxy-content.example.com-certs.tar"\ - --foreman-proxy-content-puppet "true"\ - --foreman-proxy-puppetca "true"\ - --foreman-proxy-dns "true"\ - --foreman-proxy-dns-forwarders "8.8.8.8"\ - --foreman-proxy-dns-forwarders "8.8.4.4"\ - --foreman-proxy-dns-interface "virbr1"\ - --foreman-proxy-dns-zone "example.com"\ - --foreman-proxy-dhcp "true"\ - --foreman-proxy-dhcp-interface "virbr1"\ - --foreman-proxy-tftp "true" -``` - -## Data Reset - -If you run into an error during the initial installation or wish to reset your installation entirely, the installer provides a reset option. To reset the database and all subsystems: - -``` -foreman-installer --scenario katello --reset -``` - -To clear all of your on disk Pulp content: - -``` -foreman-installer --scenario katello --clear-pulp-content -``` - -To clear all Puppet environments on disk: - -``` -foreman-installer --scenario katello --clear-puppet-environments -``` - -### From Git - -If you're working off the master branch, use Librarian to pull in all the modules to your local checkout: - -``` -$ git clone https://github.com/Katello/katello-installer.git -$ bundle install -$ librarian-puppet install --path modules/ -$ bin/katello-installer -``` - -### Certificates - -Katello installer comes with a default CA used both for the server SSL -certificates as well as the client certificates used for -authentication of the subservices (pulp, foreman-proxy, -subscription-manager etc.). - -#### Custom Server Certificates - -Katello-installer runs a validation script for passed input -certificate files. One can run it manually as follows: - -``` -katello-certs-check -c ~/path/to/server.crt\ - -r ~/path/to/server.crt.req\ - -k ~/path/to/server.key\ - -b ~/path/to/cacert.crt -``` - -The check is performed also as part of the installer script. In case -the script marked the certs as invalid incorrectly, one can skip this -check by passing `--certs-skip-check` to the installer. - -**When running the installer for the first time:** - -``` -foreman-installer --scenario katello\ - --certs-server-cert ~/path/to/server.crt\ - --certs-server-cert-req ~/path/to/server.crt.req\ - --certs-server-key ~/path/to/server.key\ - --certs-server-ca-cert ~/path/to/cacert.crt -``` - -Where the `--certs-server-ca-cert` is the CA used for issuing the -server certs (this CA gets distributed to the consumers and Foreman proxies). - -For the Foreman proxy, these options are passed as part of the -`foreman-proxy-certs-generate` script: - -``` -foreman-proxy-certs-generate --foreman-proxy-fqdn "$FOREMAN_PROXY"\ - --certs-tar ~/$FOREMAN_PROXY-certs.tar\ - --server-cert ~/path/to/server.crt\ - --server-cert-req ~/path/to/server.crt.req\ - --server-key ~/path/to/server.key\ - --server-ca-cert ~/cacert.crt -``` - -The rest of the procedure is identical to the default CA setup. - -**Setting custom certificates after 'foreman-installer --scenario katello' -was already run.** - -The first run of `foreman-installer --scenario katello` uses the default -CA for both server and client certificates. To enforce the custom -certificates to be deployed, on needs to set `--certs-update-server` for -updating the CA certificate and `--certs-update-server-ca` because the -server CA changed as well (and new katello-ca-consumer rpm needs to be -regenerated): - -``` -foreman-installer --scenario katello\ - --certs-server-cert ~/path/to/server.crt\ - --certs-server-cert-req ~/path/to/server.crt.req\ - --certs-server-key ~/path/to/server.key\ - --certs-server-ca-cert ~/path/to/cacert.crt\ - --certs-update-server --certs-update-server-ca -``` - -After the server CA changes, the new version of the -consumer-ca-consumer rpm needs to be installed on the consumers, as -well as: - -``` -rpm -Uvh http://katello.example.com/pub/katello-ca-consumer-latest.noarch.rpm -``` - -When using the custom server CA, the CA needs to be used for -the server certificates on the Foreman proxies as well. The certificates for -the Foreman proxy are deployed to the Foreman proxy through the use of the -`foreman-proxy-certs-generate` script (followed by copying the certs tar to -the Foreman proxy and running the 'foreman-installer --scenario foreman-proxy-content' -to refresh the certificates).: - -``` -foreman-proxy-certs-generate --foreman-proxy-fqdn "$FOREMAN_PROXY_CONTENT"\ - --certs-tar ~/$FOREMAN_PROXY_CONTENT-certs.tar\ - --server-cert ~/path/to/server.crt\ - --server-cert-req ~/path/to/server.crt.req\ - --server-key ~/path/to/server.key\ - --server-ca-cert ~/cacert.crt\ - --certs-update-server -``` - -#### Updating Certificates - -**On a server** - -To regenerate the server certificates when using the default CA or -enforce deploying new certificates for the custom server CA run -the 'foreman-installer --scenario katello' with `--certs-update-server` -option: - -``` -foreman-installer --scenario katello --certs-update-server -``` - -To regenerate all the certificates used in the Katello server, there -is a `--certs-update-all`. This will generate and deploy the -certificates as well as restart corresponding services. - -**On a Foreman proxy** - -For updating the certificates on a Foreman proxy pass the same -options (either `--certs-update-server` or `--certs-update-all`) to -the `foreman-proxy-certs-generate` script. The new certs tar gets generated -that needs to be transferred to the Foreman proxy and then -`foreman-installer --scenario foreman-content-proxy` needs to be re-run to apply -the updates and restart corresponding services. diff --git a/README.md b/README.md index cac69c84..c97da8b2 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,18 @@ -# Puppet modules for managing Foreman +# Overview -Installs Foreman as a standalone application or using apache passenger. - -Installs Foreman Proxy - -May install an example puppet master setup using passenger as well, including the tweaks required for foreman. +A puppet-based installer that relies on scenarios to provide configuration and default scenario values. +Available scenarios are: + * foreman + * katello + * foreman-proxy-content # Installation -## Stable release - -Releases of foreman-installer are made via RPM and deb packages and are -published via the normal Foreman repositories. +Releases of foreman-installer are made via RPM and deb packages and are published via the normal Foreman repositories. See the manual and quickstart guide available at [theforeman.org](http://theforeman.org/). -## Using GIT - -git clone --recursive git://github.com/theforeman/foreman-installer.git -b develop - -# Requirements - -if you are using RHEL, EPEL repo must be enabled - -if you are using Debian (or Ubuntu), see the additional notes in README.debian - -The Puppet Labs repositories may optionally be enabled for newer versions of Puppet -than are available in base OS repos. - -# Setup - -Please review the "answers" or setup file: /etc/foreman-installer/scenarios.d/foreman-answers.yaml. This file allows -you to override any of the default parameters (as specified in /manifests/params.pp) - -Once you are fine with your answer file, install it with this command: - - foreman-installer - -or if you prefer interactive mode - - foreman-installer -i - - -The answer file is a yaml format. For a module just using the defaults, simply put -"modulename: true" to include, or false to exclude. For a module which you wish to -override any defaults, it becomes a hash, with each overridden parameter as a key-value -pair. - -A few sample files now follow: - -All-in-one installation: - - --- - foreman: true - puppet: - server: true - foreman_proxy: true - -Just Foreman on its own: - - --- - foreman: true - puppet: false - foreman_proxy: false - -Foreman and Foreman-Proxy: - - --- - foreman: true - puppet: false - foreman_proxy: true - -Puppetmaster with Git and Proxy: - - --- - foreman: false - puppet: - server: true - server_git_repo: true - foreman_proxy: true - -Foreman & proxy with a different username: - - --- - foreman: - user: 'myforeman' - puppet: false - foreman_proxy: - user: 'myproxy' - -Extras ------- - -If you just want to include the relavant bits to run on your puppet master you may - - include foreman::params, foreman::config::enc, foreman::config::reports - # Contributing * Fork the project @@ -105,12 +21,6 @@ If you just want to include the relavant bits to run on your puppet master you m See [CONTRIBUTING.md](/CONTRIBUTING.md) for more details. -# Katello - -This repository also contains the tooling required to install Foreman Katello. - -See [KATELLO.md](/KATELLO.md) for details and specifics of that setup. - # More info See http://theforeman.org or at #theforeman irc channel on freenode From da457a590d54a289dee1f914d254437fe067f65e Mon Sep 17 00:00:00 2001 From: Eric Helms Date: Fri, 30 Aug 2024 16:12:52 -0400 Subject: [PATCH 2/2] Update README.md Co-authored-by: Ewoud Kohl van Wijngaarden --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c97da8b2..3cba8594 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Overview -A puppet-based installer that relies on scenarios to provide configuration and default scenario values. +A [Kafo](https://github.com/theforeman/kafo)-based installer that relies on scenarios to provide configuration and default scenario values. Available scenarios are: * foreman