From 4d21656ba3a4654273499fd7b782e8e4ca1ec2ee Mon Sep 17 00:00:00 2001 From: Arnaud Morin Date: Mon, 24 Oct 2022 10:18:36 +0200 Subject: [PATCH] Rework the journey indexing This patch propose a rework of the toctree so we have all configure resources available in a subfolder instead of only one page. This is also solving the issue introduced in 862100 (duplicate menu entry). Signed-off-by: Arnaud Morin Change-Id: I9b45309a981d0f0ddedc006b90499036b137360b --- doc/source/index.rst | 21 ++++++++-- doc/source/journey/configure.rst | 37 ----------------- doc/source/journey/configure/index.rst | 46 +++++++++++++++++++-- doc/source/journey/index.rst | 4 +- doc/source/journey/monitor.rst | 6 +-- doc/source/journey/scale_out.rst | 6 +-- doc/source/journey/scale_up.rst | 10 ++--- doc/source/journey/upgrade_and_maintain.rst | 4 +- 8 files changed, 75 insertions(+), 59 deletions(-) delete mode 100644 doc/source/journey/configure.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 7de54d4..61a8afc 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,12 +1,27 @@ .. include:: ../../README.rst -Contents: +Large-scale journey +------------------- + +.. toctree:: + :maxdepth: 3 + + journey/index + +Large-scale stories +------------------- .. toctree:: :maxdepth: 1 - journey/index - journey/configure/index stories/index + +Other +----- + +.. toctree:: + :maxdepth: 1 + other/index contributing + diff --git a/doc/source/journey/configure.rst b/doc/source/journey/configure.rst deleted file mode 100644 index fe327ed..0000000 --- a/doc/source/journey/configure.rst +++ /dev/null @@ -1,37 +0,0 @@ ------------------- -Stage 1: Configure ------------------- - -The first stage in the :doc:`Scaling Journey <../index>` is Configure. - -This stage is about fine-tuning configuration options and optimizing the parameters for your OpenStack cluster, so that it can handle additional load. The default values for configuration parameters in OpenStack are not always well-suited for handling scale, and OpenStack documentation does not always indicate which parameters to adjust with scale. This page aims to help answer those early questions. - -Once your cluster is properly configured to handle scale, you can go to the second stage of the Scaling Journey: :doc:`Monitor `. - - -Resources ---------- - -* :doc:`Large Scale Configuration guidelines for RabbitMQ ` -* :doc:`Large Scale Configuration guidelines for Database ` -* :doc:`Large Scale Configuration guidelines (other/extra) ` - - -External resources ------------------- - -* Neutron backends performance comparison: https://thesaitech.wordpress.com/2019/02/15/a-comparative-study-of-openstack-networking-architectures/ -* Evaluation of performance before deployment - - * https://superuser.openstack.org/articles/collaborations-cross-industries-openstack-neutron-and-discovery-open-science-initiative/ - * Enos: https://github.com/BeyondTheClouds/enos and Enoslib: https://gitlab.inria.fr/discovery/enoslib - - -How to help ------------ - -* Document better configuration defaults for large scale - - * Collect input at https://etherpad.opendev.org/p/large-scale-sig-documentation - * Curate and add new content in configure resources - * Push to official doc, pointing back to the guidelines page diff --git a/doc/source/journey/configure/index.rst b/doc/source/journey/configure/index.rst index 1afddcc..ef4014c 100644 --- a/doc/source/journey/configure/index.rst +++ b/doc/source/journey/configure/index.rst @@ -1,12 +1,50 @@ -================= - Other resources -================= +================== +Stage 1: Configure +================== Contents: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 rabbitmq database other + +--------- +Configure +--------- + +The first stage in the :doc:`Scaling Journey ` is Configure. + +This stage is about fine-tuning configuration options and optimizing the parameters for your OpenStack cluster, so that it can handle additional load. The default values for configuration parameters in OpenStack are not always well-suited for handling scale, and OpenStack documentation does not always indicate which parameters to adjust with scale. This page aims to help answer those early questions. + +Once your cluster is properly configured to handle scale, you can go to the second stage of the Scaling Journey: :doc:`Monitor `. + + +Resources +--------- + +* :doc:`Large Scale Configuration guidelines for RabbitMQ ` +* :doc:`Large Scale Configuration guidelines for Database ` +* :doc:`Large Scale Configuration guidelines (other/extra) ` + + +External resources +------------------ + +* Neutron backends performance comparison: https://thesaitech.wordpress.com/2019/02/15/a-comparative-study-of-openstack-networking-architectures/ +* Evaluation of performance before deployment + + * https://superuser.openstack.org/articles/collaborations-cross-industries-openstack-neutron-and-discovery-open-science-initiative/ + * Enos: https://github.com/BeyondTheClouds/enos and Enoslib: https://gitlab.inria.fr/discovery/enoslib + + +How to help +----------- + +* Document better configuration defaults for large scale + + * Collect input at https://etherpad.opendev.org/p/large-scale-sig-documentation + * Curate and add new content in configure resources + * Push to official doc, pointing back to the guidelines page diff --git a/doc/source/journey/index.rst b/doc/source/journey/index.rst index 8c9cbef..1dad701 100644 --- a/doc/source/journey/index.rst +++ b/doc/source/journey/index.rst @@ -12,9 +12,9 @@ articles, presentations. When documentation or tools are missing, we help to produce them. .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - configure + configure/index monitor scale_up scale_out diff --git a/doc/source/journey/monitor.rst b/doc/source/journey/monitor.rst index 86c779a..419535d 100644 --- a/doc/source/journey/monitor.rst +++ b/doc/source/journey/monitor.rst @@ -2,11 +2,11 @@ Stage 2: Monitor ================ -The second stage in the :doc:`Scaling Journey <../index>` is Monitor. +The second stage in the :doc:`Scaling Journey ` is Monitor. -Once you have properly :doc:`configured ` your cluster to handle scale, you will need to properly monitor it for signs of load stress. Monitoring in OpenStack can be a bit overwhelming and it's sometimes hard to determine how to meaningfully monitor your deployment to get advance warning of when load is just too high. This page aims to help answer those questions. +Once you have properly :doc:`configured ` your cluster to handle scale, you will need to properly monitor it for signs of load stress. Monitoring in OpenStack can be a bit overwhelming and it's sometimes hard to determine how to meaningfully monitor your deployment to get advance warning of when load is just too high. This page aims to help answer those questions. -Once meaningful monitoring is in place, you are ready to proceed to the third stage of the Scaling Journey: :doc:`Scale Up `. +Once meaningful monitoring is in place, you are ready to proceed to the third stage of the Scaling Journey: :doc:`Scale Up `. FAQ diff --git a/doc/source/journey/scale_out.rst b/doc/source/journey/scale_out.rst index ef8054a..4ce2e89 100644 --- a/doc/source/journey/scale_out.rst +++ b/doc/source/journey/scale_out.rst @@ -2,11 +2,11 @@ Stage 4: Scale Out ================== -The fourth stage in the :doc:`Scaling Journey <../index>` is Scale Out. +The fourth stage in the :doc:`Scaling Journey ` is Scale Out. -No matter how much you manage to :doc:`Scale up ` a single cluster, at one point you will have to scale out to multiple clusters, zones, regions or cells. It can be difficult to navigate the various choices you have and pick the best architecture. This page aims to help answer those questions. +No matter how much you manage to :doc:`Scale up ` a single cluster, at one point you will have to scale out to multiple clusters, zones, regions or cells. It can be difficult to navigate the various choices you have and pick the best architecture. This page aims to help answer those questions. -Once you are past that stage, you are ready to proceed to the final stage of the Scaling Journey: :doc:`Upgrade and Maintain `. +Once you are past that stage, you are ready to proceed to the final stage of the Scaling Journey: :doc:`Upgrade and Maintain `. FAQ diff --git a/doc/source/journey/scale_up.rst b/doc/source/journey/scale_up.rst index 214a282..34ad56d 100644 --- a/doc/source/journey/scale_up.rst +++ b/doc/source/journey/scale_up.rst @@ -2,11 +2,11 @@ Stage 3: Scale Up ================= -The third stage in the :doc:`Scaling Journey <../index>` is Scale Up. +The third stage in the :doc:`Scaling Journey ` is Scale Up. -As you :doc:`monitor ` your cluster at scale, you will see that it hits scaling limits within one cluster. All hope is not lost, though! There are things you can put in place push back how much a single cluster can handle, before having to resort to setting up a more complex deployment configuration. This page aims to help answer those questions. +As you :doc:`monitor ` your cluster at scale, you will see that it hits scaling limits within one cluster. All hope is not lost, though! There are things you can put in place push back how much a single cluster can handle, before having to resort to setting up a more complex deployment configuration. This page aims to help answer those questions. -Once you are past that stage, you are ready to proceed to next stage of the Scaling Journey: :doc:`Scale Out `. +Once you are past that stage, you are ready to proceed to next stage of the Scaling Journey: :doc:`Scale Out `. FAQ @@ -36,7 +36,7 @@ A: If you found out that your rabbitmq queue keep piling up for a certain servic Resources --------- -* A curated collection of :doc:`scaling stories <../stories/index>`, as we collect them +* A curated collection of :doc:`scaling stories `, as we collect them * Evaluation of internal messaging @@ -70,4 +70,4 @@ Other SIG work on that stage * Submit scaling stories on https://etherpad.openstack.org/p/scaling-stories - * Curate them on :doc:`scaling stories <../stories/index>` + * Curate them on :doc:`scaling stories ` diff --git a/doc/source/journey/upgrade_and_maintain.rst b/doc/source/journey/upgrade_and_maintain.rst index 0d3255f..f7402c8 100644 --- a/doc/source/journey/upgrade_and_maintain.rst +++ b/doc/source/journey/upgrade_and_maintain.rst @@ -2,9 +2,9 @@ Stage 5: Upgrade And Maintain ============================= -The final stage in the :doc:`Scaling Journey <../index>` is Upgrade and Maintain. +The final stage in the :doc:`Scaling Journey ` is Upgrade and Maintain. -Once you have successfully :doc:`scaled out `, how to do you effectively upgrade and maintain your deployment going forward? This stage is about establishing regular operations to keep your deployment up to date and benefit from the latest bugfixes and operating system improvements. This page aims to help answer those questions. +Once you have successfully :doc:`scaled out `, how to do you effectively upgrade and maintain your deployment going forward? This stage is about establishing regular operations to keep your deployment up to date and benefit from the latest bugfixes and operating system improvements. This page aims to help answer those questions. FAQ