kolla-ansible

deploy docs are misleading wrt version of kolla-ansible being installed

Bug #1844710 reported by Radosław Piliszek
8
This bug affects 1 person
Affects Status Importance Assigned to Milestone
kolla-ansible
Fix Released
High
Adrian Andreias

Bug Description

we should pin the version in docs to avoid confusing ppl by letting them install later release for older deploy guide
e.g. atm rocky guide tricks ppl into installing kolla-ansible for stein which will fail due to stein's placement split
refer to https://docs.openstack.org/project-deploy-guide/kolla-ansible/rocky/quickstart.html

Chason Chan (chen-xing)
Changed in kolla-ansible:
assignee: nobody → Chason Chan (chen-xing)
Revision history for this message
Mark Goddard (mgoddard) wrote :

Makes sense. Can we make this configured via a variable so that we can get it right in multiple places and only change in one with each release?

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix proposed to kolla-ansible (stable/stein)

Fix proposed to branch: stable/stein
Review: https://review.opendev.org/683855

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix proposed to kolla-ansible (stable/rocky)

Fix proposed to branch: stable/rocky
Review: https://review.opendev.org/683856

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix proposed to kolla-ansible (master)

Fix proposed to branch: master
Review: https://review.opendev.org/683857

Changed in kolla-ansible:
status: Triaged → In Progress
Adrian Andreias (adrian-fleio)
Changed in kolla-ansible:
assignee: Chason Chan (chen-xing) → Adrian Andreias (adrian-fleio)
Revision history for this message
Adrian Andreias (adrian-fleio) wrote :

I've been working a bit on this issue and turns out that global variable substitution in Sphinx reST is more complicated (than it should).

Based on:

https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_epilog

and

https://opendev.org/openstack/openstack-ansible/src/commit/5a8e199ca1ac525c1f6a5a5c3d61964f2393dfce/deploy-guide/source/conf.py#L59

I've added in doc/source/conf.py:

rst_epilog = """
.. |MAX_KOLLA_ANSIBLE_VER_EXCLUSIVE| replace:: {MAX_KOLLA_ANSIBLE_VER_EXCLUSIVE}
.. |MAX_ANSIBLE_VER_EXCLUSIVE| replace:: {MAX_ANSIBLE_VER_EXCLUSIVE}
.. |KOLLA_GIT_BRANCH| replace:: {KOLLA_GIT_BRANCH}
.. |KOLLA_ANSIBLE_GIT_BRANCH| replace:: {KOLLA_ANSIBLE_GIT_BRANCH}
""".format(
    MAX_KOLLA_ANSIBLE_VER_EXCLUSIVE=MAX_KOLLA_ANSIBLE_VER_EXCLUSIVE,
    MAX_ANSIBLE_VER_EXCLUSIVE=MAX_ANSIBLE_VER_EXCLUSIVE,
    KOLLA_GIT_BRANCH=KOLLA_GIT_BRANCH,
    KOLLA_ANSIBLE_GIT_BRANCH=KOLLA_ANSIBLE_GIT_BRANCH
)

But unfortunately variables are not replaced in code blocks like this:

   .. code-block:: console

      git clone --branch |KOLLA_GIT_BRANCH| https://opendev.org/openstack/kolla
      git clone --branch |KOLLA_ANSIBLE_GIT_BRANCH| https://opendev.org/openstack/kolla-ansible

also according to https://stackoverflow.com/questions/42158111/variable-substitution-not-working-properly-in-sphinx

Two possible solutions in that thread, neither great:

Option 1: use .. parsed-literal:: instead of .. code-block:: , but this makes the code block have different styling from other code blocks (different text color) and hyperlinks become clickable: https://ibb.co/9VP61vx

Option 2: add a docs dependency lib: https://github.com/adamtheturtle/sphinx-substitution-extensions

Anyone has a better idea?

Revision history for this message
OpenStack Infra (hudson-openstack) wrote :

Fix proposed to branch: master
Review: https://review.opendev.org/c/openstack/kolla-ansible/+/815043

Revision history for this message
Mark Goddard (mgoddard) wrote :

Hi Adrian, here's the approach we used in Kayobe: https://review.opendev.org/c/openstack/kayobe/+/788702

We switched to parsedliteral, only where required.

Revision history for this message
Adrian Andreias (adrian-fleio) wrote :

Hi Mark,

So you went for option 1, that results in inconsistent code block formatting: https://docs.openstack.org/kayobe/latest/contributor/automated.html

I found a third option in the meanwhile. What do you think about https://review.opendev.org/c/openstack/kolla-ansible/+/815043

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix merged to kolla-ansible (master)

Reviewed: https://review.opendev.org/c/openstack/kolla-ansible/+/815043
Committed: https://opendev.org/openstack/kolla-ansible/commit/28b3b83cb202c132884345bc1be8314e22a9cc8e
Submitter: "Zuul (22348)"
Branch: master

commit 28b3b83cb202c132884345bc1be8314e22a9cc8e
Author: Adrian Andreias <email address hidden>
Date: Thu Oct 21 20:40:44 2021 +0300

    docs: Parameterize kolla-ansible version and branch

    Implement simple global variables system in docs and add global variables
    KOLLA_OPENSTACK_RELEASE, KOLLA_ANSIBLE_MAJOR_VERSION and
    KOLLA_BRANCH_NAME.

    Closes-Bug: #1844710
    Change-Id: I2c131463eaf1c51eb8768f6d90e9697c77a7833b
    Signed-off-by: Adrian Andreias <email address hidden>

Changed in kolla-ansible:
status: In Progress → Fix Released
Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Change abandoned on kolla-ansible (master)

Change abandoned by "Radosław Piliszek <email address hidden>" on branch: master
Review: https://review.opendev.org/c/openstack/kolla-ansible/+/683857
Reason: we are going to go with https://review.opendev.org/c/openstack/kolla-ansible/+/816582

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Change abandoned on kolla-ansible (stable/rocky)

Change abandoned by "Radosław Piliszek <email address hidden>" on branch: stable/rocky
Review: https://review.opendev.org/c/openstack/kolla-ansible/+/683856
Reason: we are going to go with https://review.opendev.org/c/openstack/kolla-ansible/+/816582

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Change abandoned on kolla-ansible (stable/stein)

Change abandoned by "Radosław Piliszek <email address hidden>" on branch: stable/stein
Review: https://review.opendev.org/c/openstack/kolla-ansible/+/683855
Reason: we are going to go with https://review.opendev.org/c/openstack/kolla-ansible/+/816582

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Related fix merged to kolla-ansible (master)

Reviewed: https://review.opendev.org/c/openstack/kolla-ansible/+/816582
Committed: https://opendev.org/openstack/kolla-ansible/commit/9dbd6d12e333920360fd36aa90c108c3bbae203a
Submitter: "Zuul (22348)"
Branch: master

commit 9dbd6d12e333920360fd36aa90c108c3bbae203a
Author: Adrian Andreias <email address hidden>
Date: Fri Oct 29 22:35:49 2021 +0300

    docs: Get release name dynamically

    Address comments in https://review.opendev.org/c/openstack/kolla-ansible/+/815043

    Related-Bug: #1844710
    Change-Id: Ibe51db5060e8d809539f5e929a65f285e0f7d343
    Signed-off-by: Adrian Andreias <email address hidden>

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix proposed to kolla-ansible (stable/xena)

Fix proposed to branch: stable/xena
Review: https://review.opendev.org/c/openstack/kolla-ansible/+/817839

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Related fix proposed to kolla-ansible (stable/xena)

Related fix proposed to branch: stable/xena
Review: https://review.opendev.org/c/openstack/kolla-ansible/+/817840

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix proposed to kolla-ansible (stable/wallaby)

Fix proposed to branch: stable/wallaby
Review: https://review.opendev.org/c/openstack/kolla-ansible/+/817841

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Related fix proposed to kolla-ansible (stable/wallaby)

Related fix proposed to branch: stable/wallaby
Review: https://review.opendev.org/c/openstack/kolla-ansible/+/817842

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix proposed to kolla-ansible (stable/victoria)

Fix proposed to branch: stable/victoria
Review: https://review.opendev.org/c/openstack/kolla-ansible/+/817843

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Related fix proposed to kolla-ansible (stable/victoria)

Related fix proposed to branch: stable/victoria
Review: https://review.opendev.org/c/openstack/kolla-ansible/+/817844

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix merged to kolla-ansible (stable/xena)

Reviewed: https://review.opendev.org/c/openstack/kolla-ansible/+/817839
Committed: https://opendev.org/openstack/kolla-ansible/commit/c32eecf347aefaf7379af3f971ee6ad036961d92
Submitter: "Zuul (22348)"
Branch: stable/xena

commit c32eecf347aefaf7379af3f971ee6ad036961d92
Author: Adrian Andreias <email address hidden>
Date: Thu Oct 21 20:40:44 2021 +0300

    docs: Parameterize kolla-ansible version and branch

    Implement simple global variables system in docs and add global variables
    KOLLA_OPENSTACK_RELEASE, KOLLA_ANSIBLE_MAJOR_VERSION and
    KOLLA_BRANCH_NAME.

    Closes-Bug: #1844710
    Change-Id: I2c131463eaf1c51eb8768f6d90e9697c77a7833b
    Signed-off-by: Adrian Andreias <email address hidden>
    (cherry picked from commit 28b3b83cb202c132884345bc1be8314e22a9cc8e)

tags: added: in-stable-xena
Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Related fix merged to kolla-ansible (stable/xena)

Reviewed: https://review.opendev.org/c/openstack/kolla-ansible/+/817840
Committed: https://opendev.org/openstack/kolla-ansible/commit/f9b3709baec65b718881a5a5b66df79db5946452
Submitter: "Zuul (22348)"
Branch: stable/xena

commit f9b3709baec65b718881a5a5b66df79db5946452
Author: Adrian Andreias <email address hidden>
Date: Fri Oct 29 22:35:49 2021 +0300

    docs: Get release name dynamically

    Address comments in https://review.opendev.org/c/openstack/kolla-ansible/+/815043

    Related-Bug: #1844710
    Change-Id: Ibe51db5060e8d809539f5e929a65f285e0f7d343
    Signed-off-by: Adrian Andreias <email address hidden>
    (cherry picked from commit 9dbd6d12e333920360fd36aa90c108c3bbae203a)

tags: added: in-stable-wallaby
Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix merged to kolla-ansible (stable/wallaby)

Reviewed: https://review.opendev.org/c/openstack/kolla-ansible/+/817841
Committed: https://opendev.org/openstack/kolla-ansible/commit/e6827412c5fd5a0d33a31ea9b7662db20ecbb97c
Submitter: "Zuul (22348)"
Branch: stable/wallaby

commit e6827412c5fd5a0d33a31ea9b7662db20ecbb97c
Author: Adrian Andreias <email address hidden>
Date: Thu Oct 21 20:40:44 2021 +0300

    docs: Parameterize kolla-ansible version and branch

    Implement simple global variables system in docs and add global variables
    KOLLA_OPENSTACK_RELEASE, KOLLA_ANSIBLE_MAJOR_VERSION and
    KOLLA_BRANCH_NAME.

    Closes-Bug: #1844710
    Change-Id: I2c131463eaf1c51eb8768f6d90e9697c77a7833b
    Signed-off-by: Adrian Andreias <email address hidden>
    (cherry picked from commit 28b3b83cb202c132884345bc1be8314e22a9cc8e)

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Related fix merged to kolla-ansible (stable/wallaby)

Reviewed: https://review.opendev.org/c/openstack/kolla-ansible/+/817842
Committed: https://opendev.org/openstack/kolla-ansible/commit/9a9b609a6c1e90217e1983515d061c34a144165c
Submitter: "Zuul (22348)"
Branch: stable/wallaby

commit 9a9b609a6c1e90217e1983515d061c34a144165c
Author: Adrian Andreias <email address hidden>
Date: Fri Oct 29 22:35:49 2021 +0300

    docs: Get release name dynamically

    Address comments in https://review.opendev.org/c/openstack/kolla-ansible/+/815043

    Related-Bug: #1844710
    Change-Id: Ibe51db5060e8d809539f5e929a65f285e0f7d343
    Signed-off-by: Adrian Andreias <email address hidden>
    (cherry picked from commit 9dbd6d12e333920360fd36aa90c108c3bbae203a)

tags: added: in-stable-victoria
Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix merged to kolla-ansible (stable/victoria)

Reviewed: https://review.opendev.org/c/openstack/kolla-ansible/+/817843
Committed: https://opendev.org/openstack/kolla-ansible/commit/1c031910fc22e3473dc58084f8db0e743a1bc027
Submitter: "Zuul (22348)"
Branch: stable/victoria

commit 1c031910fc22e3473dc58084f8db0e743a1bc027
Author: Adrian Andreias <email address hidden>
Date: Thu Oct 21 20:40:44 2021 +0300

    docs: Parameterize kolla-ansible version and branch

    Implement simple global variables system in docs and add global variables
    KOLLA_OPENSTACK_RELEASE, KOLLA_ANSIBLE_MAJOR_VERSION and
    KOLLA_BRANCH_NAME.

    Closes-Bug: #1844710
    Change-Id: I2c131463eaf1c51eb8768f6d90e9697c77a7833b
    Signed-off-by: Adrian Andreias <email address hidden>
    (cherry picked from commit 28b3b83cb202c132884345bc1be8314e22a9cc8e)

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Related fix merged to kolla-ansible (stable/victoria)

Reviewed: https://review.opendev.org/c/openstack/kolla-ansible/+/817844
Committed: https://opendev.org/openstack/kolla-ansible/commit/36fdd6cf0d3b43d26dd686b2d3f692f0f43d3c93
Submitter: "Zuul (22348)"
Branch: stable/victoria

commit 36fdd6cf0d3b43d26dd686b2d3f692f0f43d3c93
Author: Adrian Andreias <email address hidden>
Date: Fri Oct 29 22:35:49 2021 +0300

    docs: Get release name dynamically

    Address comments in https://review.opendev.org/c/openstack/kolla-ansible/+/815043

    Related-Bug: #1844710
    Change-Id: Ibe51db5060e8d809539f5e929a65f285e0f7d343
    Signed-off-by: Adrian Andreias <email address hidden>
    (cherry picked from commit 9dbd6d12e333920360fd36aa90c108c3bbae203a)

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix included in openstack/kolla-ansible 13.0.0.0rc3

This issue was fixed in the openstack/kolla-ansible 13.0.0.0rc3 release candidate.

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix included in openstack/kolla-ansible 11.2.0

This issue was fixed in the openstack/kolla-ansible 11.2.0 release.

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix included in openstack/kolla-ansible 12.3.0

This issue was fixed in the openstack/kolla-ansible 12.3.0 release.

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix included in openstack/kolla-ansible 14.0.0.0rc1

This issue was fixed in the openstack/kolla-ansible 14.0.0.0rc1 release candidate.

To post a comment you must log in.
This report contains Public information  
Everyone can see this information.
Subscribing...

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.