From 188e113915e26487bd4c77010e347ccd9dc37ec1 Mon Sep 17 00:00:00 2001 From: Pierre Riteau Date: Thu, 16 Jul 2026 15:56:00 +0200 Subject: [PATCH] Add 2026.1 documentation The OpenStack upgrade page still needs a full review. --- .readthedocs.yaml | 2 +- doc/source/conf.py | 4 +- .../contributor/environments/aufn-ceph.rst | 2 +- .../contributor/environments/ci-aio.rst | 6 +- .../contributor/environments/ci-multinode.rst | 2 +- .../contributor/environments/ci-tenks.rst | 2 +- doc/source/contributor/package-updates.rst | 10 +- .../contributor/testing-ci-automation.rst | 2 +- doc/source/operations/customising-horizon.rst | 2 +- doc/source/operations/index.rst | 1 - doc/source/operations/ubuntu-noble.rst | 10 - doc/source/operations/upgrading-openstack.rst | 295 +----------------- doc/source/release-notes.rst | 8 +- doc/source/usage.rst | 3 +- 14 files changed, 26 insertions(+), 323 deletions(-) delete mode 100644 doc/source/operations/ubuntu-noble.rst diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 6cbc9d3e27..f7878668c4 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -13,7 +13,7 @@ build: python: "3.12" jobs: post_checkout: - - git remote set-branches origin master stackhpc/master stackhpc/2025.1 stackhpc/2024.1 stackhpc/2023.1 stackhpc/zed stackhpc/yoga stackhpc/xena stackhpc/wallaby + - git remote set-branches origin master stackhpc/master stackhpc/2026.1 stackhpc/2025.1 stackhpc/2024.1 stackhpc/2023.1 stackhpc/zed stackhpc/yoga stackhpc/xena stackhpc/wallaby - git fetch --unshallow # Build documentation in the doc/source/ directory with Sphinx diff --git a/doc/source/conf.py b/doc/source/conf.py index a6376d3018..ff2841f57a 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -29,8 +29,8 @@ # -- StackHPC Kayobe configuration -------------------------------------- # Variables to override -current_series = "2025.1" -previous_series = "2024.1" +current_series = "2026.1" +previous_series = "2025.1" branch = f"stackhpc/{current_series}" ceph_series = "squid" diff --git a/doc/source/contributor/environments/aufn-ceph.rst b/doc/source/contributor/environments/aufn-ceph.rst index 537dd66310..130ee69708 100644 --- a/doc/source/contributor/environments/aufn-ceph.rst +++ b/doc/source/contributor/environments/aufn-ceph.rst @@ -9,7 +9,7 @@ This environment creates a Universe-from-nothing_-style deployment of Kayobe con .. warning:: This guide was written for the Yoga release and has not been validated for - 2025.1. Proceed with caution. + 2026.1. Proceed with caution. Prerequisites ============= diff --git a/doc/source/contributor/environments/ci-aio.rst b/doc/source/contributor/environments/ci-aio.rst index 2a45c667a5..74a19aeb50 100644 --- a/doc/source/contributor/environments/ci-aio.rst +++ b/doc/source/contributor/environments/ci-aio.rst @@ -29,7 +29,7 @@ Download the setup script: .. parsed-literal:: - curl -LO https://raw.githubusercontent.com/stackhpc/stackhpc-kayobe-config/stackhpc/2025.1/etc/kayobe/environments/ci-aio/automated-setup.sh + curl -LO https://raw.githubusercontent.com/stackhpc/stackhpc-kayobe-config/stackhpc/2026.1/etc/kayobe/environments/ci-aio/automated-setup.sh Change the permissions on the script: @@ -52,9 +52,9 @@ following options: * ``BASE_PATH`` (default: ``~``) - Directory to deploy from. The directory must exist before running the script. -* ``KAYOBE_BRANCH`` (default: ``stackhpc/2025.1``) - The branch of Kayobe +* ``KAYOBE_BRANCH`` (default: ``stackhpc/2026.1``) - The branch of Kayobe source code to use. -* ``KAYOBE_CONFIG_BRANCH`` (default: ``stackhpc/2025.1``) - The branch of +* ``KAYOBE_CONFIG_BRANCH`` (default: ``stackhpc/2026.1``) - The branch of ``stackhpc-kayobe-config`` to use. * ``KAYOBE_AIO_LVM`` (default: ``true``) - Whether the image uses LVM. * ``KAYOBE_CONFIG_EDIT_PAUSE`` (default: ``false``) - Option to pause diff --git a/doc/source/contributor/environments/ci-multinode.rst b/doc/source/contributor/environments/ci-multinode.rst index 06509ce86e..3c5274ffa4 100644 --- a/doc/source/contributor/environments/ci-multinode.rst +++ b/doc/source/contributor/environments/ci-multinode.rst @@ -5,7 +5,7 @@ Multinode Test Environment .. warning:: This guide was written for the Yoga release and has not been validated for - 2025.1. Proceed with caution. + 2026.1. Proceed with caution. The ``ci-multinode`` environment provides a Kayobe configuration for multi-node clouds to be used for test and development purposes. It is designed to be used diff --git a/doc/source/contributor/environments/ci-tenks.rst b/doc/source/contributor/environments/ci-tenks.rst index 9146d631af..983a6222f7 100644 --- a/doc/source/contributor/environments/ci-tenks.rst +++ b/doc/source/contributor/environments/ci-tenks.rst @@ -52,7 +52,7 @@ Download the setup script: .. parsed-literal:: - curl -LO https://raw.githubusercontent.com/stackhpc/stackhpc-kayobe-config/stackhpc/2025.1/etc/kayobe/environments/ci-tenks/automated-deployment.sh + curl -LO https://raw.githubusercontent.com/stackhpc/stackhpc-kayobe-config/stackhpc/2026.1/etc/kayobe/environments/ci-tenks/automated-deployment.sh Change the permissions on the script: diff --git a/doc/source/contributor/package-updates.rst b/doc/source/contributor/package-updates.rst index cb4450eff3..b2e1cccdf4 100644 --- a/doc/source/contributor/package-updates.rst +++ b/doc/source/contributor/package-updates.rst @@ -7,13 +7,13 @@ This section describes the Release Train process of creating new package reposit Preparations ============ -1. Before building images, you should check for any outstanding PRs into the earliest supported release. Below are the links for the 2025.1 branches. +1. Before building images, you should check for any outstanding PRs into the earliest supported release. Below are the links for the 2026.1 branches. - kayobe-config: https://github.com/stackhpc/stackhpc-kayobe-config/pulls?q=is%3Apr+is%3Aopen+base%3Astackhpc%2F2025.1+ + kayobe-config: https://github.com/stackhpc/stackhpc-kayobe-config/pulls?q=is%3Apr+is%3Aopen+base%3Astackhpc%2F2026.1+ - kolla: https://github.com/stackhpc/kolla/pulls?q=is%3Apr+is%3Aopen+base%3Astackhpc%2F2025.1+ + kolla: https://github.com/stackhpc/kolla/pulls?q=is%3Apr+is%3Aopen+base%3Astackhpc%2F2026.1+ - kolla-ansible: https://github.com/stackhpc/kolla-ansible/pulls?q=is%3Apr+is%3Aopen+base%3Astackhpc%2F2025.1+ + kolla-ansible: https://github.com/stackhpc/kolla-ansible/pulls?q=is%3Apr+is%3Aopen+base%3Astackhpc%2F2026.1+ You should also check any referenced source trees in etc/kayobe/kolla.yml. @@ -165,7 +165,7 @@ Upgrading OpenStack to the next release in a multinode environment .. warning:: This guide was written for the Wallaby release and has not been validated - for 2025.1. Proceed with caution. + for 2026.1. Proceed with caution. As this is not a full production system, only a reduced number of steps need to be followed to upgrade to a new release. Below describes these steps, with ``stackhpc/wallaby`` as the starting branch: diff --git a/doc/source/contributor/testing-ci-automation.rst b/doc/source/contributor/testing-ci-automation.rst index 4601c74dbd..e46460f7c0 100644 --- a/doc/source/contributor/testing-ci-automation.rst +++ b/doc/source/contributor/testing-ci-automation.rst @@ -113,7 +113,7 @@ job. The workflow performs the following high-level steps: #. Deploy a VM on an OpenStack cloud using the `aio - `_ + `_ Terraform configuration. #. Deploy OpenStack in the VM using Kayobe and the :doc:`ci-aio ` environment. If this is an upgrade job, the previous diff --git a/doc/source/operations/customising-horizon.rst b/doc/source/operations/customising-horizon.rst index 97c6a84901..d6fe29d4ba 100644 --- a/doc/source/operations/customising-horizon.rst +++ b/doc/source/operations/customising-horizon.rst @@ -13,7 +13,7 @@ Creating a custom Horizon theme A simple custom theme for Horizon can be implemented as small modifications of an existing theme, such as the `Default -`__ +`__ one. A theme contains at least two files: ``static/_styles.scss``, which can be empty, and diff --git a/doc/source/operations/index.rst b/doc/source/operations/index.rst index 2ef0929a5d..58a1b8b604 100644 --- a/doc/source/operations/index.rst +++ b/doc/source/operations/index.rst @@ -23,4 +23,3 @@ This guide is for operators of the StackHPC Kayobe configuration project. tempest upgrading-openstack upgrading-ceph - ubuntu-noble diff --git a/doc/source/operations/ubuntu-noble.rst b/doc/source/operations/ubuntu-noble.rst deleted file mode 100644 index 6e7435894c..0000000000 --- a/doc/source/operations/ubuntu-noble.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _upgrading-to-ubuntu-noble: - -============ -Ubuntu Noble -============ - -.. warning:: - - Before upgrading to the 2025.1 release of OpenStack, all Ubuntu hosts must first be upgraded to Ubuntu Noble (24.04). - Please follow the upgrade instructions provided in the 2024.1 release documentation, available `here `__. diff --git a/doc/source/operations/upgrading-openstack.rst b/doc/source/operations/upgrading-openstack.rst index 6b414eb65f..d1fc91b368 100644 --- a/doc/source/operations/upgrading-openstack.rst +++ b/doc/source/operations/upgrading-openstack.rst @@ -35,177 +35,14 @@ Notable changes in the |current_release| Release There are many changes in the OpenStack |current_release| release described in the release notes for each project. Here are some notable ones. -stackhpc.linux collection -------------------------- - -The ``stackhpc.linux`` collection version has been bumped to 1.3.0. Note this -version uses systemd to activate virtual functions. This change is restricted -to the ``stackhpc.linux.sriov`` role, which is not used by Kayobe. If a custom -playbook uses this role, you can retain existing behaviour by setting -``sriov_numvfs_driver`` to ``udev``. - -Neutron driver defaults ------------------------ - -The default Neutron ML2 type drivers and tenant network types now use -``geneve`` instead of ``vxlan`` when OVN is enabled. This affects the -``kolla_neutron_ml2_type_drivers`` and -``kolla_neutron_ml2_tenant_network_types`` variables. - -Custom inspector_keep_ports ---------------------------- - -If you have customized ``inspector_keep_ports``, ensure it is set to one of: -``all``, ``present``, or ``added``. If you are relying on the previous -behaviour you should set ironic_keep_ports to present. - -Seed/Infra VM boot firmware ---------------------------- - -The default boot firmware for Seed and Infra VMs has changed from ``bios`` to -``efi``. Set ``infra_vm_boot_firmware`` and ``seed_vm_boot_firmware`` to bios -to retain existing behaviour. - -Prometheus MSteams ------------------- - -The ``prometheus-msteams`` integration in Kolla Ansible has been removed, users -should switch to the `native -`__ -Prometheus Teams integration. - -Prometheus blackbox exporter endpoints --------------------------------------- - -Many endpoints for the Blackbox exporter are now templated in the Kolla-Ansible -group vars for the cloud. This means that the -``prometheus_blackbox_exporter_endpoints`` variable can be removed from the -environment's ``kolla/globals.yml`` file (if applicable) and the endpoints will -fallback to the ones templated in the group vars. Backend endpoints such as -`these `__ -are not yet templated by Kolla-Ansible. - -Additional endpoints may still be added. - -For Kolla-Ansible templating, use ``stackhpc_prometheus_blackbox_exporter_endpoints_custom``. -For example: - -.. code-block:: yaml - :caption: ``etc/kayobe/kolla/inventory/group_vars/prometheus-blackbox-exporter`` - - stackhpc_prometheus_blackbox_exporter_endpoints_custom: - - 'custom_service:http_2xx:{{ public_protocol }}://{{ external_fqdn | put_address_in_context('url') }}:{{ custom_serivce_port }}' - -Alternatively, for Kayobe templating, use the ``prometheus_blackbox_exporter_endpoints_kayobe`` variable. -For example: - -.. code-block:: yaml - :caption: ``kolla/globals.yml`` - - prometheus_blackbox_exporter_endpoints_kayobe: - - endpoints: - - "pulp:http_2xx:{{ pulp_url }}/pulp/api/v3/status/" - enabled: "{{ seed_pulp_container_enabled | bool }}" - -Ansible playbook subdirectories -------------------------------- - -The playbooks under ``etc/kayobe/ansible`` have been subdivided into different -categories to make them easier to navigate. This change may result in merge -conflicts where playbooks have been edited downstream, and broken hooks where -symlinks have been used. - -To mitigate the impact of these changes, two scripts have been added: +Ironic Inspector removal +------------------------ -* ``tools/get-new-playbook-path.sh`` - Returns the new category of a given - playbook. For example ``tools/get-new-playbook-path.sh - deploy-os-capacity-exporter.yml`` returns ``deployment/`` -* ``tools/magic-symlink-fix.sh`` - Uses the previous script to attempt to fix - any broken symlinks in the kayobe configuration. - -If playbooks are referenced in different methods other than symlinks, they'll -need to be manually resolved by operators. (e.g. Shell scripts running -playbooks with file paths, ``import_playbook`` command in custom playbooks) +The separate Ironic Inspector service was replaced by the Ironic built-in inspector. Known issues ============ -Cinder ------- - -`Enhancement of Ceph integration of multiple clusters -`__ -means the Cinder role now requires ``user`` and ``pool`` set to the each item of kolla dict -variable ``cinder_ceph_backends`` at ``$KAYOBE_CONFIG_PATH/kolla/globals.yml`` -(``$KAYOBE_CONFIG_PATH/environments//kolla/globals.yml`` if using environments) -For example, - -.. code:: yaml - - cinder_ceph_backends: - - name: rbd-1 - cluster: ceph - user: cinder - pool: volumes - enabled: true - - name: rbd-2 - cluster: ceph-hdd - user: cinder - pool: volumes-hdd - enabled: true - -You can find the name of pools from ``cephadm_pools`` in cephadm.yml and name of the users -will be ``cinder`` unless changed to otherwise. - -The K-A upstream change `#909974 `__ -requires users to manually set Cinder cluster name. -You can find the current name of the cluster from ``cluster`` variable in -``DEFAULT`` category in ``cinder.conf``. - -For example, - -.. code:: - - [DEFAULT] - cluster = ceph - -Match the name of the cluster by setting ``cinder_cluster_name`` in ``$KAYOBE_CONFIG_PATH/kolla/globals.yml`` -(``$KAYOBE_CONFIG_PATH/environments//kolla/globals.yml`` if using environments). - -.. code:: yaml - - cinder_cluster_name: ceph - -CloudKitty ----------- - -The Elasticsearch storage driver is no longer compatible with Opensearch storage backend. -Set CloudKitty storage backend to ``opensearch`` if it was set to be ``elasticsearch`` before. -This can be set at ``$KAYOBE_CONFIG_PATH/kolla/globals.yml`` -(``$KAYOBE_CONFIG_PATH/environments//kolla/globals.yml`` if using environments) - -.. code:: yaml - - cloudkitty_storage_backend: opensearch - -Ironic ------- - -From Dalmatian, `Kayobe no longer provides its own default driver & interfaces -`__ -for Ironic and follows Ironic's default. -This can cause your Ironic configuration ``ironic.conf`` to regress. -Check the configuration difference before applying and re-add your options at -``$KAYOBE_CONFIG_PATH/kolla/config/ironic.conf`` -(``$KAYOBE_CONFIG_PATH/environments//kolla/config/ironic.conf`` if using environments) - -For example, - -.. code:: yaml - - [DEFAULT] - enabled_network_interfaces = neutron - RabbitMQ -------- @@ -220,7 +57,7 @@ A proper fix is still WIP, in the meantime these errors can be resolved with thi Security baseline ================= -As part of the 2025.1 Epoxy release we are looking to improve the security +As part of the 2026.1 Gazpacho release we are looking to improve the security baseline of StackHPC OpenStack deployments. If any of the following have not been done, they should be completed before the upgrade begins. @@ -261,122 +98,6 @@ suggestions: generally be found in the documentation of each project. For example, Nova policy: https://docs.openstack.org/nova/latest/configuration/policy.html -Ubuntu Noble migration ----------------------- - -Ubuntu Jammy support has been removed from the 2025.1 release onwards. Hosts -must be migrated to Ubuntu 24.04 before upgrading OpenStack services. -You can find the upgrade procedure from :ref:`upgrading-to-ubuntu-noble` -documentation. - - -RabbitMQ Prerequisites ----------------------- - -.. warning:: - - StackHPC Kayobe Config sets RabbitMQ 4.1 as the default for the Epoxy release. - Existing transient queues must be migrated to durable queues with Queue Manager - before upgrading to RabbitMQ 4.1. - - This means that queue migration and the RabbitMQ 4.1 upgrade must be completed - before upgrading to Epoxy. - -Queue Migration -~~~~~~~~~~~~~~~ - -.. warning:: - - This migration will stop all services using RabbitMQ and cause an extended - API outage while queues are migrated. It should only be performed in a - pre-agreed maintenance window. - - If you are using Azimuth or the ClusterAPI driver for Magnum, you should - make sure to pause reconciliation of all clusters before the API outage - window. See the `Azimuth docs - `__ - for instructions. - -Set the following variables in your kolla globals file (i.e. -``$KAYOBE_CONFIG_PATH/kolla/globals.yml`` or -``$KAYOBE_CONFIG_PATH/environments/$KAYOBE_ENVIRONMENT/kolla/globals.yml``): - -.. code-block:: yaml - - om_enable_queue_manager: true - om_enable_rabbitmq_quorum_queues: true - om_enable_rabbitmq_transient_quorum_queue: true - om_enable_rabbitmq_stream_fanout: true - -Then execute the migration script: - -.. code-block:: bash - - $KAYOBE_CONFIG_PATH/../../tools/rabbitmq-queue-migration.sh - -.. note:: - - After migrating to durable queues, messages are sent to all receivers, but - only one will respond. This results in high numbers of messages staying in - the ready state, so the Prometheus alert ``RabbitMQTooMuchReady`` will start - firing. This alert can be ignored, and will be removed when Prometheus is - reconfigured. - -RabbitMQ Upgrade -~~~~~~~~~~~~~~~~ - -After the queue migration is finished, upgrade RabbitMQ to 4.1. - -1. Sync and publish latest Kolla container images to ensure local pulp has RabbitMQ 4.1 image. - (This can be skipped if local pulp is not used.) - - .. code-block:: bash - - kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/pulp-container-sync.yml - kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/pulp-container-publish.yml - -2. Upgrade RabbitMQ to 4.1 with Kolla-Ansible - - .. code-block:: bash - - kayobe kolla ansible run "rabbitmq-upgrade 4.1" - -.. _python-3-12: - -Python 3.12 ------------ - -From OpenStack 2025.1, Kayobe and Kolla-Ansible require Python 3.12. - -Ubuntu 24.04 has a default Python of version 3.12. -You can find the upgrade procedure from :ref:`upgrading-to-ubuntu-noble` - -For Rocky Linux 9, install Python 3.12 manually. - -.. code-block:: bash - - dnf install python3.12 - -For both Operating Systems, Kayobe and Kolla-Ansible Python virtual environments -created with older Python versions will not work with OpenStack 2025.1. - -Create a new Kayobe environment and bootstrap the Ansible control host with Python 3.12. -Beokay is recommended when creating and managing the local Kayobe environment. -You can find more information from the :ref:`beokay` documentation. - -.. note:: - - For Rocky Linux 9, ``beokay create`` must be used with the ``--python python3.12`` - option to specify Beokay to use Python 3.12 as it is not the default. - -Kayobe Automation -~~~~~~~~~~~~~~~~~ - -For deployments using Kayobe Automation CI, the Kayobe Docker image also needs -to be rebuilt with Python 3.12. In GitHub, run the ``Build Kayobe Docker -Image`` workflow. In GitLab, run the ``build_kayobe_image`` pipeline. In either -case, the image will automatically be rebuilt with Python 3.12. - Preparation =========== @@ -494,12 +215,6 @@ configuration. The output of the command may be restricted using the Upgrading local Kayobe environment ---------------------------------- -.. warning:: - - Python 3.12 is required for OpenStack 2025.1 Kayobe environments. - The environment cannot be upgraded for this release, it must be rebuilt. - You can find more information at :ref:`python-3-12` - The local Kayobe environment should be either recreated or upgraded to use the new release. It may be beneficial to keep a Kayobe environment for the old release in case it is necessary before the upgrade begins. @@ -569,7 +284,7 @@ To upgrade the Ansible control host: Upgrading Pulp -------------- -The local Pulp server needs to be upgraded before synchronising 2025.1 +The local Pulp server needs to be upgraded before synchronising 2026.1 container images. The following command will deploy the latest Pulp container without upgrading Bifrost: diff --git a/doc/source/release-notes.rst b/doc/source/release-notes.rst index cec010e00e..0b2491488f 100644 --- a/doc/source/release-notes.rst +++ b/doc/source/release-notes.rst @@ -1,6 +1,6 @@ -================================= -2025.1 Epoxy Series Release Notes -================================= +==================================== +2026.1 Gazpacho Series Release Notes +==================================== .. release-notes:: - :branch: stackhpc/2025.1 + :branch: stackhpc/2026.1 diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 0b503e7641..b5fbc1b192 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -16,8 +16,7 @@ when used with Kayobe's :kayobe-doc:`multiple environments ` feature. This configuration should be consumed using the `StackHPC Kayobe fork -`__, which includes -backported support for Ansible collections. +`__. New deployments ---------------