From 298cd76874e9e10b04971e9f233ac4ddf578bc1f Mon Sep 17 00:00:00 2001 From: Brian Bouterse Date: Tue, 6 Jun 2023 12:07:56 -0400 Subject: [PATCH] Removes leftover docs about ansible installer closes #3834 --- CHANGES/3834.doc | 1 + docs/client_bindings.rst | 24 ------- docs/configuration/applying.rst | 18 ----- docs/configuration/settings.rst | 5 +- docs/installation/instructions.rst | 67 ++++++------------- docs/installation/storage.rst | 19 ++++-- .../plugin-writer/concepts/index.rst | 51 ++------------ docs/troubleshooting.rst | 2 +- 8 files changed, 45 insertions(+), 142 deletions(-) create mode 100644 CHANGES/3834.doc diff --git a/CHANGES/3834.doc b/CHANGES/3834.doc new file mode 100644 index 0000000000..f434833924 --- /dev/null +++ b/CHANGES/3834.doc @@ -0,0 +1 @@ +Removes leftover documentation referring to the deprecated Ansible based installer. diff --git a/docs/client_bindings.rst b/docs/client_bindings.rst index 8724ccfe43..a43fdaf471 100644 --- a/docs/client_bindings.rst +++ b/docs/client_bindings.rst @@ -45,27 +45,3 @@ as a GET parameter. For example for pulp_rpm only endpoints use a query like thi The schema can then be used as input to the openapi-generator-cli. The documentation on getting started with openapi-generator-cli is available on `openapi-generator.tech `_. - - -Generating a client for a dev environment ------------------------------------------ - -The pulp dev environment provided by `pulp_installer `_ -introduces a set of useful -`aliases `_, -such as `pbindings`. - -Examples: - -- generating python bindings for pulp_file: - -.. code-block:: bash - - pbindings pulp_file python - -- generating ruby bindings for pulp_file with '3.0.0rc1.dev.10' version - -.. code-block:: bash - - pbindings pulp_file ruby 3.0.0rc1.dev.10 - diff --git a/docs/configuration/applying.rst b/docs/configuration/applying.rst index 5ef825d3c8..641ab7580e 100644 --- a/docs/configuration/applying.rst +++ b/docs/configuration/applying.rst @@ -10,7 +10,6 @@ to configure Pulp settings using various ways: * :ref:`Environment Variables ` - Enabled by default. * :ref:`Configuration File ` - Disabled by default, but easy to enable. - Enabled by ``pulp_installer``. .. _env-var-settings: @@ -48,20 +47,3 @@ In this example the settings file ends in ".py" so it needs to be valid Python, The configuration file and directories containing the configuration file must be readable by the user Pulp runs as. If using SELinux, assign the ``system_u:object_r:pulpcore_etc_t:s0`` label. - - -.. _pulp-installer-settings: - -pulp_installer --------------- - -The `pulp_installer `_ enables configuration via a -settings file that lives at ``/etc/pulp/settings.py``. It does this by having each systemd file that -starts a Pulp service include:: - - Environment="PULP_SETTINGS=/etc/pulp/settings.py" - -A Pulp upgrade using ``pulp_installer`` will override the original ``/etc/pulp/settings.py``. -To keep your settings through an upgrade, use the "local settings" file located at -``/etc/pulp/settings.local.py`` which takes precedence over ``/etc/pulp/settings.py`` on a -setting-by-setting basis. diff --git a/docs/configuration/settings.rst b/docs/configuration/settings.rst index 8cfa853cf2..4b9628b66a 100644 --- a/docs/configuration/settings.rst +++ b/docs/configuration/settings.rst @@ -57,9 +57,8 @@ DB_ENCRYPTION_KEY The file location of a symmetric fernet key that Pulp uses to encrypt sensitive fields in the database. Default location is ``/etc/pulp/certs/database_fields.symmetric.key``. - The key is automatically generated by default with pulp_installer and single container image. The - key can be generated independently but it must be a url-safe base64-encoded string of 32 random - bytes. + The key is automatically generated by default with the pulp-oci-images. The key can be generated + independently but it must be a url-safe base64-encoded string of 32 random bytes. To generate a key with openssl:: diff --git a/docs/installation/instructions.rst b/docs/installation/instructions.rst index 2a0c8a04db..bb23da71aa 100644 --- a/docs/installation/instructions.rst +++ b/docs/installation/instructions.rst @@ -90,7 +90,8 @@ PyPI Installation 10. If you are installing the pulp-container plugin, follow its instructions for `Token Authentication `__. -11. Go through the :ref:`database-install`, :ref:`redis-install`, and :ref:`systemd-setup` sections. +11. Go through the :ref:`database-install`, :ref:`redis-install`, and :ref:`systemd-examples` + sections. 12. Run Django Migrations:: @@ -111,7 +112,7 @@ PyPI Installation .. note:: - In place of using the systemd unit files provided in the `systemd-setup` section, you can run + In place of using the systemd unit files provided in the `systemd-examples` section, you can run the commands yourself inside of a shell. This is fine for development but not recommended for production:: @@ -224,36 +225,29 @@ You then need to add redis to your :ref:`configuration `, such as REDIS_HOST="localhost" REDIS_PORT=6379 -.. _systemd-setup: +.. _systemd-examples: -Systemd -------- - -To run the four Pulp services, systemd files needs to be created in /usr/lib/systemd/system/. The -`Pulp 3 Ansible Installer `__ makes these for you, but you -can also configure them by hand from the templates below. Custom configuration can be applied using -the ``Environment`` option with various :ref:`Pulp settings `. +Systemd Examples +---------------- +Here are some examples of the service files you can use to have systemd run pulp services. 1. Make a ``pulpcore-content.service`` file for the pulpcore-content service which serves Pulp - content to clients. We recommend starting with the `pulpcore-content template `_ and - setting the variables according to the `pulpcore_content config variables documentation `_ + content to clients. We recommend adapting with the `pulpcore-content template `_. -2. Make a ``pulpcore-api.service`` file for the pulpcore-api service which serves the Pulp REST API. We - recommend starting with the `pulpcore-api template `_ - and setting the variables according to the `pulpcore-api config variables documentation `_ +2. Make a ``pulpcore-api.service`` file for the pulpcore-api service which serves the Pulp REST API. + We recommend adapting the `pulpcore-api template `_. -3. Make a ``pulpcore-worker@.service`` file for the pulpcore-worker processes which allows you to manage - one or more workers. We recommend starting with the `pulpcore-worker template `_ and setting - the variables according to the `pulp_workers config variables documentation `_ +3. Make a ``pulpcore-worker@.service`` file for the pulpcore-worker processes which allows you to + manage one or more workers. We recommend adapting the `pulpcore-worker template `_. -4. Make a `pulpcore.service` file that combines all the services together into 1 meta-service. You can copy - the `pulpcore file `__ - from pulp-installer. +4. Make a `pulpcore.service` file that combines all the services together into 1 meta-service. You + can copy the `pulpcore template `_. These services can then be enabled & started by running the following, assuming you only want 2 workers:: @@ -261,28 +255,11 @@ These services can then be enabled & started by running the following, assuming sudo systemctl enable pulpcore-worker@2 sudo systemctl enable --now pulpcore + .. _ssl-setup: SSL --- -Users should configure HTTPS communication between clients and the reverse proxy that is in front of pulp services -like pulpcore-api and pulpcore-content. The Pulp Installer provides three different options for configuring SSL -certificates for nginx and httpd reverse proxies. - -1. By default, the installer will generate a new Certificate Authority and use it to sign an SSL certificate. In - this case, the Pulp administrator will need to distribute the Certificate Authority certificate or the SSL - certificate to all clients that wish to communicate with Pulp. Clients will need to import one of these - certificates to their system CA trust store. - - The default location for the CA certificate is ``/etc/pulp/certs/root.crt``. The default location for the SSL - certificate is ``/etc/pulp/certs/pulp_webserver.crt``. - -2. If you already have an SSL Cerificate that you want to be used by the reverse proxy to encrypt communication - with clients, the Pulp Installer supports providing a path for ``pulp_webserver_tls_cert`` and - ``pulp_webserver_tls_key``. The administrator is still responsible for making sure that clients trust the - Certificate Authority that signed the SSL certificate. - -3. The Pulp Installer also supports using services that use the ACME protocol, e.g. https://letsencrypt.org/, to - generate trusted SSL certificates. See the Pulp Installer documentation for `instructions and an example playbook - `_. +Users should configure HTTPS communication between clients and the reverse proxy that is in front of +Pulp services like pulpcore-api and pulpcore-content. diff --git a/docs/installation/storage.rst b/docs/installation/storage.rst index 730ee01277..cf7e55c394 100644 --- a/docs/installation/storage.rst +++ b/docs/installation/storage.rst @@ -10,8 +10,6 @@ Storage to use another storage backend such as Amazon Simple Storage Service (S3), you'll need to configure Pulp. - You can also configure Pulp to use Amazon S3 and Azure storage using the Pulp installer. For more information - see the `Pulp installer documentation `_ Local Filesystem ^^^^^^^^^^^^^^^^ @@ -93,9 +91,13 @@ To have Pulp use S3, complete the following steps: pip install django-storages[boto3] -2. Depending on which method you use to install or configure Pulp, you must set ``DEFAULT_FILE_STORAGE`` to ``storages.backends.s3boto3.S3Boto3Storage`` in Pulp Settings. For example, if you use the `Pulp installer `_, the ``default_file_storage`` is part of the ``pulp_settings`` Ansible variables you can define in your Ansible playbook. +2. Depending on which method you use to install or configure Pulp, you must set + ``DEFAULT_FILE_STORAGE`` to ``storages.backends.s3boto3.S3Boto3Storage`` in Pulp Settings. -3. In that same way, add your Amazon S3 configuration settings to ``AWS_ACCESS_KEY_ID``, ``AWS_SECRET_ACCESS_KEY``, and ``AWS_STORAGE_BUCKET_NAME``. For more S3 configuration options, see the `django-storages documents `_. +3. In that same way, add your Amazon S3 configuration settings to ``AWS_ACCESS_KEY_ID``, + ``AWS_SECRET_ACCESS_KEY``, and ``AWS_STORAGE_BUCKET_NAME``. For more S3 configuration options, + see the `django-storages documents `_. Here is an example configuration that will use a bucket called ``pulp3`` that is hosted in region ``eu-central-1``:: @@ -144,7 +146,9 @@ Configuring Pulp to use Azure Blob storage pip install django-storages[azure] -2. Depending on which method you use to install or configure Pulp, you must set ``DEFAULT_FILE_STORAGE`` to ``storages.backends.azure_storage.AzureStorage`` in Pulp Settings. For example, if you use the `Pulp installer `_, the ``default_file_storage`` is part of the ``pulp_settings`` Ansible variables you can define in your Ansible playbook. +2. Depending on which method you use to install or configure Pulp, you must set + ``DEFAULT_FILE_STORAGE`` to ``storages.backends.azure_storage.AzureStorage`` in Pulp Settings. + 3. In the same way, configure the following parameters:: AZURE_ACCOUNT_NAME = 'Storage account name' @@ -155,5 +159,6 @@ Configuring Pulp to use Azure Blob storage AZURE_LOCATION = 'the folder within the container where your pulp objects will be stored' MEDIA_ROOT = '' - For a comprehensive overview of all possible options for the Azure Blob storage backend see the `django-storages[azure] documents - `_. + For a comprehensive overview of all possible options for the Azure Blob storage backend see the + `django-storages[azure] documents `_. diff --git a/docs/plugin_dev/plugin-writer/concepts/index.rst b/docs/plugin_dev/plugin-writer/concepts/index.rst index 2603ae04f4..9669194982 100644 --- a/docs/plugin_dev/plugin-writer/concepts/index.rst +++ b/docs/plugin_dev/plugin-writer/concepts/index.rst @@ -433,18 +433,15 @@ When a plugin requires either Pulp API or Pulp Content App custom urls, the reve either Nginx or Apache, need to receive extra configuration snippets to know which service to route the custom URLs to. -A best practice is to document clearly the custom URL requirements your plugin needs. Although the -installer can automatically install plugin snippets, other environments, e.g. k8s or docker or -docker containers may still need to configure them manually. Having clear docs is a minimum. +A best practice is to document clearly the custom URL requirements your plugin needs. Environments +such as k8s, podman, or docker may need manual configuration. Having clear docs is a minimum. You can ship webserver snippets as part of your Python package with three steps: 1. Create a python package named ``webserver_snippets`` directory inside your app, e.g. ``pulp_ansible.app.webserver_snippets``. Like all Python packages it will have an ``__init__.py``. -2. Create an ``nginx.conf`` and an ``apache.conf``, and the installer will symlink to the correct -one depending on which reverse proxy is installed. Please create both as the installer supports -both. +2. Create an ``nginx.conf`` and an ``apache.conf``. 3. Create an entry in MANIFEST.in to have the packaged plugin include the ``apache.conf`` and ``nginx.conf`` files. @@ -489,7 +486,7 @@ Sometimes a plugin may want to control the reverse proxy behavior of a URL at th example, perhaps an additional header may want to be set at the reverse proxy when those urls are forwarded to the plugin's Django code. To accomplish this, the :ref:`custom app route ` can be used when it specifies a more-specific -route than the installer's base webserver configuration provides. +route than the pulp-oci-images base webserver configuration provides. For example assume the header `FOO` should be set at the url ``/pulp/api/v3/foo_route``. Below are two examples of a snippet that could do this (one for Nginx and another for Apache). @@ -518,8 +515,9 @@ Apache example:: These snippets work because both Nginx and Apache match on "more-specific" routes first regardless -of the order in the config file. The installer ships the a default of ``/pulp/api/v3`` so anything -containing another portion after ``v3`` such as ``/pulp/api/v3/foo_route`` would be more specific. +of the order in the config file. The pulp-oci-env ships the a default of ``/pulp/api/v3`` so +anything containing another portion after ``v3`` such as ``/pulp/api/v3/foo_route`` would be more +specific. .. _deprecation_policy: @@ -636,41 +634,6 @@ bound: declare a new lower bound. -.. _plugin_installation: - -Installation ------------- - -It's recommended to use the `Pulp 3 Installer `_ to -install your plugin. Generally you can do this by configuring ``pulp_install_plugins`` variable with -your Python package's name. For example for ``pulp-file``:: - - pulp_install_plugins: - pulp-file: {} - - -.. _custom-installation-tasks: - -Custom Installation Tasks -------------------------- - -Custom installation steps for a plugin can be added to the installer which are run only when your -plugin is in the ``pulp_install_plugins`` configuration. - -For example, pulp_rpm requires several system-level dependencies that cannot be received from PyPI. -The installer delivers these dependencies at install time through the `pulp_rpm_prerequisites -`_ role. That role -ships with the installer itself. - -It's also possible to add custom install behaviors for developers too. For exampe, the galaxy_ng -plugin desires their web UI to be built from source for devel installs. That occurs `in a custom -galaxy_ui.yml task `_ in the installers ``pulp_devel`` role. - -For help contributing or changing a plugin-specific installation, please reach out to the installer -maintainers. Check out `our help page `_ for different ways to -contact us. - .. _checksum-use-in-plugins: Checksum Use In Plugins diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index e2d252e943..bca7e63e79 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -13,7 +13,7 @@ below. Designating a Python-based settings file, and putting the DEBUG logging configuration there:: - export PULP_SETTINGS=/etc/pulp/settings.py # Note the installer already does this for you + export PULP_SETTINGS=/etc/pulp/settings.py echo "LOGGING = {'dynaconf_merge': True, 'loggers': {'': {'handlers': ['console'], 'level': 'DEBUG'}}}" >> /etc/pulp/settings.py Or via environment variable::