openstack/openstack-helm
Code Issues Proposed changes

Add docs for FQDN support

Browse Source 
This PS adds documentation regarding FQDN support and how to
override FQDNs.

Change-Id: I607a729a09d2d5ace50ae3ef74dd22bb5b0452f2
This commit is contained in:
lukepatrick 2017-09-28 14:12:31 -06:00 committed by Larry Rensing
parent c31016b724
commit 64fcfcd2a9
2 changed files with 244 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

243
doc/source/install/ext-dns-fqdn.rst Normal file
View File

@ -0,0 +1,243 @@
============================
External DNS to FQDN/Ingress
============================
Overview
========
In order to access your OpenStack deployment on Kubernetes we can use the Ingress Controller
or NodePorts to provide a pathway in. A background on Ingress, OpenStack-Helm fully qualified
domain name (FQDN) overrides, installation, examples, and troubleshooting will be discussed here.
Ingress
=======
OpenStack-Helm utilizes the `Kubernetes Ingress Controller
<https://kubernetes.io/docs/concepts/services-networking/ingress/>`__
An Ingress is a collection of rules that allow inbound connections to reach the cluster services.
::
internet
|
[ Ingress ]
--|-----|--
[ Services ]
It can be configured to give services externally-reachable URLs, load balance traffic,
terminate SSL, offer name based virtual hosting, and more.
Essentially the use of Ingress for OpenStack-Helm is an Nginx proxy service. Ingress (Nginx) is
accessible by your cluster public IP - e.g. the IP associated with
``kubectl get pods -o wide --all-namespaces | grep ingress-api``
Ingress/Nginx will be listening for server name requests of "keystone" or "keystone.openstack"
and will route those requests to the proper internal K8s Services.
These public listeners in Ingress must match the external DNS that you will set up to access
your OpenStack deployment. Note each rule also has a Service that directs Ingress Controllers
allow access to the endpoints from within the cluster.
External DNS and FQDN
=====================
Prepare ahead of time your FQDN and DNS layouts. There are a handful of OpenStack endpoints
you will want exposed for API and Dashboard access.
Update your lab/environment DNS server with your appropriate host values creating A Records
for the edge node IP's and various FQDN's. Alternatively you can test these settings locally by
editing your ``/ect/hosts``. Below is an example with a dummy domain ``os.foo.org`` and
dummy Ingress IP ``1.2.3.4``.
::
A Records
1.2.3.4 horizon.os.foo.org
1.2.3.4 neutron.os.foo.org
1.2.3.4 keystone.os.foo.org
1.2.3.4 nova.os.foo.org
1.2.3.4 metadata.os.foo.org
1.2.3.4 glance.os.foo.org
The default FQDN's for OpenStack-Helm are
::
horizon.openstack.svc.cluster.local
neutron.openstack.svc.cluster.local
keystone.openstack.svc.cluster.local
nova.openstack.svc.cluster.local
metadata.openstack.svc.cluster.local
glance.openstack.svc.cluster.local
We want to change the ***public*** configurations to match our DNS layouts above. In each Chart
``values.yaml`` is a ``endpoints`` configuration that has ``host_fqdn_override``'s for each API
that the Chart either produces or is dependant on. `Read more about how Endpoints are developed
<http://openstack-helm.readthedocs.io/en/latest/devref/endpoints.html>`__.
Note while Glance Registry is listening on a Ingress http endpoint, you will not need to expose
the registry for external services.
Installation
============
Implementing the FQDN overrides **must** be done at install time. If you run these as helm upgrades,
Ingress will notice the updates though none of the endpoint build-out jobs will run again,
unless they are cleaned up manually or using a tool like Armada.
Two similar options exist to set the FQDN overrides for External DNS mapping.
**First**, edit the ``values.yaml`` for Neutron, Glance, Horizon, Keystone, and Nova.
Using Horizon as an example, find the ``endpoints`` config.
For ``identity`` and ``dashboard`` at ``host_fdqn_override.public`` replace ``null`` with the
value as ``keystone.os.foo.org`` and ``horizon.os.foo.org``
.. code:: bash
endpoints:
cluster_domain_suffix: cluster.local
identity:
name: keystone
hosts:
default: keystone-api
public: keystone
host_fqdn_override:
default: null
public: keystone.os.foo.org
.
.
dashboard:
name: horizon
hosts:
default: horizon-int
public: horizon
host_fqdn_override:
default: null
public: horizon.os.foo.org
After making the configuration changes, run a ``make`` and then install as you would from
AIO or MultiNode instructions.
**Second** option would be as ``--set`` flags when calling ``helm install``
Add to the Install steps these flags - also adding a shell environment variable to save on
repeat code.
.. code-block:: shell
export FQDN=os.foo.org
helm install --name=horizon ./horizon --namespace=openstack \
--set network.enable_node_port=true \
--set endpoints.dashboard.host_fqdn_override.public=horizon.$FQDN \
--set endpoints.identity.host_fqdn_override.public=keystone.$FQDN
Note if you need to make a DNS change, you will have to do a uninstall (``helm delete <chart>``)
and install again.
Once installed, access the API's or Dashboard at `http://horizon.os.foo.org`
Examples
========
Code examples below.
If doing an `AIO install
<http://openstack-helm.readthedocs.io/en/latest/install/developer/all-in-one.html>`__,
all the ``--set`` flags
.. code-block:: shell
export FQDN=os.foo.org
helm install --name=keystone local/keystone --namespace=openstack \
--set endpoints.identity.host_fqdn_override.public=keystone.$FQDN
helm install --name=glance local/glance --namespace=openstack \
--set storage=pvc \
--set endpoints.image.host_fqdn_override.public=glance.$FQDN \
--set endpoints.identity.host_fqdn_override.public=keystone.$FQDN
helm install --name=nova local/nova --namespace=openstack \
--values=./tools/overrides/mvp/nova.yaml \
--set=conf.nova.libvirt.nova.conf.virt_type=qemu \
--set endpoints.compute.host_fqdn_override.public=nova.$FQDN \
--set endpoints.compute_metadata.host_fqdn_override.public=metadata.$FQDN \
--set endpoints.image.host_fqdn_override.public=glance.$FQDN \
--set endpoints.network.host_fqdn_override.public=neutron.$FQDN \
--set endpoints.identity.host_fqdn_override.public=keystone.$FQDN
helm install --name=neutron local/neutron \
--namespace=openstack --values=./tools/overrides/mvp/neutron-ovs.yaml \
--set endpoints.network.host_fqdn_override.public=neutron.$FQDN \
--set endpoints.compute.host_fqdn_override.public=nova.$FQDN \
--set endpoints.identity.host_fqdn_override.public=keystone.$FQDN
helm install --name=horizon local/horizon --namespace=openstack \
--set=network.enable_node_port=true \
--set endpoints.dashboard.host_fqdn_override.public=horizon.$FQDN \
--set endpoints.identity.host_fqdn_override.public=keystone.$FQDN
Troubleshooting
===============
**Review the Ingress configuration.**
Get the Nginx configuration from the Ingress Pod:
.. code-block:: shell
kubectl exec -it ingress-api-2210976527-92cq0 -n openstack -- cat /etc/nginx/nginx.conf
Look for *server* configuration with a *server_name* matching your desired FQDN
::
server {
server_name nova.os.foo.org;
listen [::]:80;
set $proxy_upstream_name "-";
location / {
set $proxy_upstream_name "openstack-nova-api-n-api";
.
.
}
**Check Chart Status**
Get the ``helm status`` of your chart.
.. code-block:: shell
helm status keystone
Verify the *v1beta1/Ingress* resource has a Host with your FQDN value
::
LAST DEPLOYED: Thu Sep 28 20:00:49 2017
NAMESPACE: openstack
STATUS: DEPLOYED
RESOURCES:
==> v1beta1/Ingress
NAME HOSTS ADDRESS PORTS AGE
keystone keystone,keystone.os.foo.org 1.2.3.4 80 35m

1
doc/source/install/index.rst
View File

@ -8,3 +8,4 @@ Contents:
developer/index
multinode
ext-dns-fqdn