Improved documentation

[Dan MacDonald]

I have now been trying for months to create a LB with Octavia, as configured by the charm overlaid on top of the telemetry bundle. I do not believe the current documentation is clear enough and it seems it is either incomplete and/or outdated.

Ideally what I would like to see is a clear and easy to follow set of instructions that takes a user from having deployed the telemetry bundle with Octavia overlay using juju to creating a simple LB, with every step required contained within one guide and using the default, simplest, lowest common denominator settings so as to minimise confusion and increase the users chances of success.

The documentation for using the base bundle is sufficient to get a user up and running with openstack, I have the deploying of regular instances working OK but there is no equivalent document that I have been able to find for Octavia and the user has to piece together bits of info from at least three or four separate docs in order to get Octavia running, namely:

https://github.com/openstack/charm-octavia

https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-octavia.html

and

https://docs.openstack.org/octavia/latest/install/install-ubuntu.html

I personally would like to see all of the info required to get going with Octavia in the README.md for the charm but I wouldn't mind if this was a new document if it was linked to within the Octavia Charm readme.md.

SPECIFIC ISSUES

The Octavia charm readme (
https://github.com/openstack/charm-octavia ) is incomplete at least because it doesn't give the user the openstack command to create a LB. It current seems to give most but not of the config steps required to get up and running.

An example command to create a LB is given on https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-octavia.html :

lb_vip_port_id=$(openstack loadbalancer create -f value -c vip_port_id --name lb1 --vip-subnet-id private_subnet)

but that seems like quite a convoluted example to me, if I could get it to work! Other examples I've seen online don't use the -f and -c options. Are they really required for a basic example? The example command should be kept as simple as possible.

Another issue with https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-octavia.html is that it starts off with instructions for Neutron ML2+OVS and some for Neutron ML2+OVN, expecting the reader to know the difference and which applies to them. Please explain how the user can check which set of instructions they are to use.

Before running this command to create a LB it seems that an extra step (or more) is entirely missing, that is creating a special rc file for using Octavia. This step is only mentioned on https://docs.openstack.org/octavia/latest/install/install-ubuntu.html but that page contains lots of other steps that are probably not necessary for someone who has installed Octavia using a Charm.

Creating the octavia rc file raises another undocumented issue and that is that after installing the bundle there are two services projects and two admin projects. This is certainly the case for the Train bundles at least. How does the user work out the correct services project to use for Octavia? My guess is that the user should use the services project that has the octavia-diskimage-retrofit user in it.

The charm README should at least specify which parts of this doc are relevant to someone who has just installed Octavia as an overlay.

https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-octavia.html contains the following command:

juju add-relation glance-simplestreams-sync rabbitmq-server

Which I was told in the charms IRC channel is deprecated.

I configured the Octavia overlay to use bionic train with my most recent install attempts but I discovered I still needed to use this command to set the amphora image correctly:

juju config octavia-diskimage-retrofit retrofit-series=bionic retrofit-uca-pocket=train

When deploying glance-simplestreams-sync I had to use a slightly modified command because I didn't have an extra machine to dedicate to it:

juju deploy glance-simplestreams-sync --config source=ppa:simplestreams-dev/trunk --to lxd:2

I'm sure there are other relevant bits of information missing from these documents that I've either forgot to mention or I don't know about yet but I think that covers the main issues as-is.

[Dan MacDonald (allcoms)]

There are at least two more steps involved in creating an Octavia LB than I thought a few days ago because it seems you must also create an octavia flavor first:

https://docs.openstack.org/octavia/latest/admin/flavors.html

I discovered this by trying to create an LB using the dashboard. I am able to create LBs 'successfully' under Horizon but I cannot ping6 them from the octavia unit and assigning FIPs doesn't seem to work. It says it has assigned the FIP in a notification pop-up but it doesn't show the FIP as being assigned on the LB info page.

[Dan MacDonald (allcoms)]

Done it!

It has probably took me about a year, on and off, to get the Octavia charm working but it seems I'm finally there and users can now create loadbalancers although I've not actually tested its fully, genuinely working yet. It looks like it should.

What I wrote about creating an octavia rc file above is nonsense. Instead that is handled by assigning users the correct Octavia Policy role like so:

openstack role add --project sgs548 --user sgs548 --user-domain astronomy load-balancer_admin

[Dan MacDonald (allcoms)]

I have uploaded my notes on installing Openstack and Octavia using charms to github here:

https://htmlpreview.github.io/?https://github.com/danboid/dox/blob/main/openstack/juju.html

That should give you a good idea of what I think should be covered in the official documentation.