From 0f4958d6f9c04d79125c3e95db85377e31ab6b0a Mon Sep 17 00:00:00 2001 From: Drew Walters Date: Mon, 16 Jul 2018 16:38:48 -0500 Subject: [PATCH] Docs: update proxy troubleshooting guide Currently, the proxy troubleshooting guide does not include the IP address of the Kubernetes API in the defined environment or Ansible playbook variables. This causes deployments to fail when requests are routed through proxy servers. This change adds a proxy configuration section to the beginning of the installation guide and includes the process of adding the Kubernetes API IP address to the environment and Ansible playbook variables. It also removes the unecessary sections from the troubleshooting guide and upgrades the note about resolv.conf being overwritten to a warning. Change-Id: I1ff753517b387027f0cc052b18e8822b638cfb4d --- doc/source/install/common-requirements.rst | 33 ++++++ .../developer/kubernetes-and-common-setup.rst | 2 +- doc/source/troubleshooting/index.rst | 1 - doc/source/troubleshooting/proxy.rst | 110 ------------------ 4 files changed, 34 insertions(+), 112 deletions(-) delete mode 100644 doc/source/troubleshooting/proxy.rst diff --git a/doc/source/install/common-requirements.rst b/doc/source/install/common-requirements.rst index 5175319067..e10866b8f8 100644 --- a/doc/source/install/common-requirements.rst +++ b/doc/source/install/common-requirements.rst @@ -23,3 +23,36 @@ On the host or master node, install the latest versions of Git, CA Certs & Make .. literalinclude:: ../../../tools/deployment/developer/common/000-install-packages.sh :language: shell :lines: 1,17- + +Proxy Configuration +=================== + +.. note:: This guide assumes that users wishing to deploy behind a proxy have already + defined the conventional proxy environment variables ``http_proxy``, + ``https_proxy``, and ``no_proxy``. + +In order to deploy OpenStack-Helm behind corporate proxy servers, add the +following entries to ``openstack-helm-infra/tools/gate/devel/local-vars.yaml``. + +.. code-block:: yaml + + proxy: + http: http://username:password@host:port + https: https://username:password@host:port + noproxy: 127.0.0.1,localhost,172.17.0.1,.svc.cluster.local + +.. note:: The ``.svc.cluster.local`` address is required to allow the OpenStack + client to communicate without being routed through proxy servers. The IP + address ``172.17.0.1`` is the advertised IP address for the Kubernetes API + server. Replace the addresses if your configuration does not match the + one defined above. + +Add the address of the Kubernetes API, ``172.17.0.1``, and +``.svc.cluster.local`` to your ``no_proxy`` and ``NO_PROXY`` environment +variables. + +.. code-block:: bash + + export no_proxy=${no_proxy},172.17.0.1,.svc.cluster.local + export NO_PROXY=${NO_PROXY},172.17.0.1,.svc.cluster.local + diff --git a/doc/source/install/developer/kubernetes-and-common-setup.rst b/doc/source/install/developer/kubernetes-and-common-setup.rst index efc139e452..eb112196e2 100644 --- a/doc/source/install/developer/kubernetes-and-common-setup.rst +++ b/doc/source/install/developer/kubernetes-and-common-setup.rst @@ -17,7 +17,7 @@ should be cloned: git clone https://git.openstack.org/openstack/openstack-helm.git -.. note:: +.. warning:: This installation, by default will use Google DNS servers, 8.8.8.8 or 8.8.4.4 and updates ``resolv.conf``. These DNS nameserver entries can be changed by updating file ``openstack-helm-infra/tools/images/kubeadm-aio/assets/opt/playbooks/vars.yaml`` diff --git a/doc/source/troubleshooting/index.rst b/doc/source/troubleshooting/index.rst index 621f85e3f8..be5783c024 100644 --- a/doc/source/troubleshooting/index.rst +++ b/doc/source/troubleshooting/index.rst @@ -9,7 +9,6 @@ Sometimes things go wrong. These guides will help you solve many common issues w database persistent-storage - proxy ubuntu-hwe-kernel ceph diff --git a/doc/source/troubleshooting/proxy.rst b/doc/source/troubleshooting/proxy.rst deleted file mode 100644 index c28cdc4078..0000000000 --- a/doc/source/troubleshooting/proxy.rst +++ /dev/null @@ -1,110 +0,0 @@ -============= -Proxy Setting -============= - -This guide is to help enterprise users who wish to deploy OpenStack-Helm -behind a corporate firewall and require a corporate proxy to reach the -internet. - -Proxy Environment Variables -=========================== - -Ensure the following proxy environment variables are defined either through -an rc file or through modifying ``/etc/environment``. - -.. code-block:: shell - - export http_proxy="http://username:password@host:port" - export HTTP_PROXY="http://username:password@host:port" - export https_proxy="https://username:password@host:port" - export HTTPS_PROXY="https://username:password@host:port" - export no_proxy="127.0.0.1,localhost,.svc.cluster.local" - export NO_PROXY="127.0.0.1,localhost,.svc.cluster.local" - -Note the ``.svc.cluster.local`` is needed to allow the OpenStack client -to connect without routing the connection to the proxy. Please update to the -appropriate domain name if you have a different configuration. - -External DNS -============ - -In ``tools/images/kubeadm-aio/assets/opt/playbooks/vars.yaml``, under -``external_dns_nameservers``, add the internal DNS IP addresses. -These entries will overwrite the ``/etc/resolv.conf`` on the system. -If your network cannot connect to the Google DNS servers, -``8.8.8.8`` or ``8.8.4.4``, the updates will fail as they cannot resolve -the URLs. - -Ansible Playbook -================ - -Either globally or in the tasks with ``pip`` or ``apt``, ensure you add -the following to the task: - -.. code-block:: yaml - - environment: - http_proxy: http://username:password@host:port - https_proxy: https://username:password@host:port - no_proxy: 127.0.0.1,localhost - - -Docker -====== - -Docker needs to be configured to use the proxy to pull down external images. -For systemd, use a systemd drop-in directory outlined in -https://docs.docker.com/engine/admin/systemd/#httphttps-proxy. - -1. Create a systemd drop-in directory for the docker service: - -.. code-block:: shell - - $ sudo mkdir -p /etc/systemd/system/docker.service.d - -2. Create a file called ``http-proxy.conf`` in the director created and add - in the needed environment variable: - -.. code-block:: ini - - [Service] - Environment="HTTP_PROXY=http://username:password@host:port" - Environment="HTTPS_PROXY=https://username:password@host:port" - Environment="NO_PROXY=127.0.0.1,localhost,docker-registry.somecorporation.com" - -3. Once that's completed, flush the change: - -.. code-block:: shell - - $ systemctl daemon-reload - -4. Restart Docker: - -.. code-block:: shell - - $ systemctl restart docker - -5. Verify the configuration has been loaded: - -.. code-block:: shell - - $ systemctl show --property=Environment docker - Environment=HTTP_PROXY=http://proxy.example.com:80/ - -Kubeadm-AIO Dockerfile -====================== - -In ``tools/images/kubeadm-aio/Dockerfile``, add the following to the -Dockerfile before ``RUN`` instructions. - -.. code-block:: dockerfile - - ENV HTTP_PROXY http://username:password@host:port - ENV HTTPS_PROXY http://username:password@host:port - ENV http_proxy http://username:password@host:port - ENV https_proxy http://username:password@host:port - ENV no_proxy 127.0.0.1,localhost,172.17.0.1 - ENV NO_PROXY 127.0.0.1,localhost,172.17.0.1 - -Note the IP address ``172.17.0.1`` is the advertised IP for the kubernetes -API server. Replace it with the appropriate IP if it is different.