From fec7887e87d84fa9ff533fdbefd57fe05ccb0a8d Mon Sep 17 00:00:00 2001 From: "Amy Marrich (spotz)" Date: Thu, 23 Apr 2020 19:42:50 -0500 Subject: [PATCH] Rewording Limited Connectivity for clarity Cleaned up some wording for clairty Change-Id: I2a7095a8121e74f1efc690321ea07bc5aec92a5c --- .../user/limited-connectivity/index.rst | 65 +++++++++---------- 1 file changed, 32 insertions(+), 33 deletions(-) diff --git a/doc/source/user/limited-connectivity/index.rst b/doc/source/user/limited-connectivity/index.rst index 4940cca8cb..38c93856b5 100644 --- a/doc/source/user/limited-connectivity/index.rst +++ b/doc/source/user/limited-connectivity/index.rst @@ -4,7 +4,7 @@ Installing with limited connectivity Many playbooks and roles in OpenStack-Ansible retrieve dependencies from the public Internet by default. The example configurations assume that the deployer -provides good quality Internet connectivity via a router on the OpenStack +provides a good quality Internet connection via a router on the OpenStack management network. Deployments may encounter limited external connectivity for a number of @@ -16,9 +16,9 @@ reasons: - Architectural decisions by the deployer to isolate the OpenStack networks - High security environments where no external connectivity is permitted -We recommend a set of practices and configuration overrides deployers can use -when running OpenStack-Ansible in network environments that block Internet -connectivity. +When running OpenStack-Ansible in network environments that block internet +connectivity, we recommend the following set of practices and configuration +overrides for deployers to use. The options below are not mutually exclusive and may be combined if desired. @@ -44,20 +44,20 @@ Python package repositories Many packages used to run OpenStack are installed using `pip`. We advise mirroring the PyPi package index used by `pip`. A deployer can choose to -actively mirror the entire upstream PyPi repository but this may require -a significant amount of storage. Alternatively a caching pip proxy -can be used to retain local copies of only those packages which are required. +actively mirror the entire upstream PyPi repository, but this may require +a significant amount of storage. Alternatively, a caching pip proxy can +be used to retain local copies of only those packages which are required. -In order to configure the build to use an alternative index, create the file -`/etc/pip.conf` with the following content and ensure that it is placed on -all hosts in the environment. +In order to configure the deployment to use an alternative index, create +the file `/etc/pip.conf` with the following content and ensure that it +resides on all hosts in the environment. .. code-block:: shell-session [global] index-url = http://pip.example.org/simple -In addition it is necessary to configure easy_install to use an alternative +In addition, it is necessary to configure easy_install to use an alternative index. easy_install is used instead of pip to install anything listed under setup_requires in setup.py during wheel builds. See https://pip.pypa.io/en/latest/reference/pip_install/#controlling-setup-requires @@ -69,8 +69,8 @@ To configure easy_install to use an alternative index, create the file [easy_install] index_url = https://pip.example.org/simple -Then, in `/etc/openstack_deploy/user_variables.yml`, inform the deployment -that it needs to copy these files from the host into the container cache image. +Then, in `/etc/openstack_deploy/user_variables.yml`, configure the deployment +to copy these files from the host into the container cache image. .. code-block:: yaml @@ -138,8 +138,8 @@ Some networks have no routed access to the Internet, or require certain traffic to use application specific gateways such as HTTP or SOCKS proxy servers. -Configuration can be applied to target and deployment hosts to reach public -internet resources via HTTP or SOCKS proxy server(s). OpenStack-Ansible may be +Target and deployment hosts can be configured to reach public internet +resources via HTTP or SOCKS proxy server(s). OpenStack-Ansible may be used to configure target hosts to use the proxy server(s). OpenStack-Ansible does not provide automation for creating the proxy server(s). @@ -150,14 +150,12 @@ particular for the system package manager. ``apt-get`` proxy configuration ------------------------------- -See `Setting up apt-get to use a http-proxy`_ - -.. _Setting up apt-get to use a http-proxy: https://help.ubuntu.com/community/AptGet/Howto#Setting_up_apt-get_to_use_a_http-proxy +See `Setting up apt-get to use a http-proxy `_ Other proxy configuration ------------------------- -Further to this basic configuration, there are other network clients on the +In addition to this basic configuration, there are other network clients on the target hosts which may be configured to connect via a proxy. For example: - Most Python network modules @@ -175,20 +173,20 @@ settings. These environment variables can be configured in It is important to note that the proxy server should only be used to access external resources, and communication between the internal components of the -OpenStack deployment should be direct, without going through the proxy. -The ``no_proxy`` environment variable is used to specify hosts that should -be reached directly without going through the proxy. These often are the hosts -in the management network. +OpenStack deployment should be direct and not through the proxy. The ``no_proxy`` +environment variable is used to specify hosts that should be reached directly +without going through the proxy. These often are the hosts in the management +network. OpenStack-Ansible provides two distinct mechanisms for configuring proxy server settings: -#. The default configuration file suggests setting a persistent proxy +1. The default configuration file suggests setting a persistent proxy configuration on all target hosts and defines a persistent ``no_proxy`` environment variable which lists all hosts/containers' management addresses as well as the load balancer internal/external addresses. -#. An alternative method applies proxy configuration in a transient manner +2. An alternative method applies proxy configuration in a transient manner during the execution of Ansible playbooks and defines a minimum set of management network IP addresses for ``no_proxy`` that are required for the playbooks to succeed. These proxy settings do not persist after an Ansible @@ -198,29 +196,30 @@ functional. The deployer must decide which of these approaches is more suitable for the target hosts, taking into account the following guidance: -#. Persistent proxy configuration is a standard practice and network clients on +1. Persistent proxy configuration is a standard practice and network clients on the target hosts will be able to access external resources after deployment. -#. The deployer must ensure that a persistent proxy configuration has complete +2. The deployer must ensure that a persistent proxy configuration has complete coverage of all OpenStack management network host/containers' IP addresses in the ``no_proxy`` environment variable. It is necessary to use a list of IP addresses, CIDR notation is not valid for ``no_proxy``. -#. Transient proxy configuration guarantees that proxy environment variables +3. Transient proxy configuration guarantees that proxy environment variables will not persist, ensuring direct communication between services on the OpenStack management network after deployment. Target host network clients such as ``wget`` will not be able to access external resources after deployment. -#. The maximum length of ``no_proxy`` should not exceed 1024 characters due to +4. The maximum length of ``no_proxy`` should not exceed 1024 characters due to a fixed size buffer in the ``pam_env`` PAM module. Longer environment variables will be truncated during deployment operations and this will lead to unpredictable errors during or after deployment. -Once the number of hosts/containers in a deployment reaches a certain size -the length of ``no_proxy`` will exceed 1024 characters. It is then mandatory to -use the transient proxy settings which only requires a subset of the management -network IP addresses to be present in ``no_proxy`` at deployment time. +Once the number of hosts/containers in a deployment reaches a certain size, +the length of ``no_proxy`` will exceed 1024 characters at which point it is +mandatory to use the transient proxy settings which only requires a subset of +the management network IP addresses to be present in ``no_proxy`` at deployment +time. Refer to `global_environment_variables:` and `deployment_environment_variables:` in the example `user_variables.yml` for