diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/source/reference/compute/nova-guide.rst | 15 | ||||
| -rw-r--r-- | doc/source/reference/databases/mariadb-guide.rst | 105 | ||||
| -rw-r--r-- | doc/source/reference/message-queues/rabbitmq.rst | 50 | ||||
| -rw-r--r-- | doc/source/reference/shared-services/keystone-guide.rst | 11 | ||||
| -rw-r--r-- | doc/source/user/multi-regions.rst | 8 |
5 files changed, 178 insertions, 11 deletions
diff --git a/doc/source/reference/compute/nova-guide.rst b/doc/source/reference/compute/nova-guide.rst index 577b07104..1069030bb 100644 --- a/doc/source/reference/compute/nova-guide.rst +++ b/doc/source/reference/compute/nova-guide.rst @@ -45,6 +45,21 @@ Valid options are ``none``, ``novnc`` and ``spice``. Additionally, serial console support can be enabled by setting ``enable_nova_serialconsole_proxy`` to ``true``. +``spice`` consoles have additional configuration options used by Kolla Ansible: + +* nova_spice_html5: configures whether the HTML5 transcoding proxy used by + Horizon is enabled, and defaults to ``true``. +* nova_spice_image_compression: which compression algorithm to use for images + when using the SPICE console type. Defaults to ``auto_glz``. +* nova_spice_jpeg_compression: whether or not to use JPEG compression with + SPICE consoles. Defaults to ``auto``. +* nova_spice_zlib_compression: whether or not to use zlib compression with + SPICE consoles. Defaults to ``auto``. +* nova_spice_playback_compression: whether or not to use compression for video + playback. Defaults to ``true``. +* nova_spice_streaming_mode: what streaming mode to use with SPICE consoles. + Defaults to ``filter``. + Cells ===== diff --git a/doc/source/reference/databases/mariadb-guide.rst b/doc/source/reference/databases/mariadb-guide.rst index c4a40740e..b09ab11b6 100644 --- a/doc/source/reference/databases/mariadb-guide.rst +++ b/doc/source/reference/databases/mariadb-guide.rst @@ -69,3 +69,108 @@ Backup and restore is working only for default shard as kolla currently using HAProxy solution for MariaDB loadbalancer which is simple TCP and has configured only default shard hosts as backends, therefore backup script will reach only default shard on ``kolla_internal_vip_address``. + +.. _mariadb-notifications: + +Cluster Event Notifications +--------------------------- + +Kolla Ansible supports native MariaDB Galera cluster notifications. This allows +operators to execute custom logic whenever a node status or cluster membership +changes. + +To enable this feature, you must provide a custom script named +``wsrep-notify.sh`` in the following directory on the control host: +``/etc/kolla/config/mariadb/wsrep-notify.sh``. + +Kolla Ansible will automatically detect the presence of this file, copy it to +the MariaDB nodes, and configure the ``wsrep_notify_cmd`` directive in the +MariaDB configuration. + +Example 1: Integration with Prometheus Alertmanager +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use this feature to send alerts directly to Prometheus Alertmanager. +Save the following content as ``/etc/kolla/config/mariadb/wsrep-notify.sh``: + +.. code-block:: bash + + #!/bin/bash + + # List of Alertmanager instances (direct IP addresses) + # Using kolla_address to bypass VIP for higher reliability + ALERTMANAGERS=( + {% for host in groups['prometheus-alertmanager'] %} + "{{ internal_protocol }}://{{ 'api' | kolla_address(host) | + put_address_in_context('url') }}:{{ hostvars[host] + ['prometheus_alertmanager_port'] }}/api/v2/alerts" + {% endfor %} + ) + + # Authentication credentials from Kolla configuration + AUTH="{{ prometheus_alertmanager_user }}:{{ + prometheus_alertmanager_password }}" + HOSTNAME=$(hostname) + + # Prepare the JSON payload for the Alertmanager API + PAYLOAD=$(cat <<EOF + [ + { + "labels": { + "alertname": "GaleraEvent", + "severity": "warning", + "instance": "$HOSTNAME" + }, + "annotations": { + "description": "Galera cluster event detected: $*", + "summary": "Galera Status Change on $HOSTNAME" + } + } + ] + EOF + ) + + # Iterate through instances until the first successful POST + for URL in "${ALERTMANAGERS[@]}"; do + echo "Attempting to send alert to: $URL" + if curl -X POST "$URL" \ + -u "$AUTH" \ + -H "Content-Type: application/json" \ + -d "$PAYLOAD" \ + --fail --silent --show-error; then + echo "Alert sent successfully." + exit 0 + fi + echo "Failed to reach $URL, trying next instance..." + done + + echo "Error: Could not send alert to any Alertmanager instance." + exit 1 + +.. note:: + + When providing this script, ensure it has the correct permissions. Kolla + Ansible will attempt to set execution permissions (``0755``) automatically + during the deployment. + +Example 2: Logging Cluster Changes to a File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Alternatively, you can log all cluster events to a local file for later audit +or simple monitoring. Save the following content as +``/etc/kolla/config/mariadb/wsrep-notify.sh``: + +.. code-block:: bash + + #!/bin/bash + + LOG_FILE="/var/log/kolla/mariadb/galera_cluster_events.log" + TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S') + + echo "[$TIMESTAMP] Host: $HOSTNAME | Event: $*" >> "$LOG_FILE" + +.. note:: + + When providing this script, ensure it has the correct permissions. Kolla + Ansible will attempt to set execution permissions (``0755``) automatically + during the deployment. diff --git a/doc/source/reference/message-queues/rabbitmq.rst b/doc/source/reference/message-queues/rabbitmq.rst index 375d58fe4..1eed7ef14 100644 --- a/doc/source/reference/message-queues/rabbitmq.rst +++ b/doc/source/reference/message-queues/rabbitmq.rst @@ -159,3 +159,53 @@ different type, the follow procedure will be needed. .. code-block:: console kolla-ansible deploy --tags <service-tags> + + +Upgrading RabbitMQ +~~~~~~~~~~~~~~~~~~ + +RabbitMQ upgrades in Kolla Ansible are typically restricted to a single minor +version increment at a time (e.g., from 4.0.x to 4.1.x). This is a safety +measure to ensure that RabbitMQ's internal data migrations and feature flags +are processed correctly. + +In some cases, specific multi-version upgrade paths are supported (for example, +jumping from 3.13 directly to 4.2). These allowed paths are defined +using the ``rabbitmq_allowed_upgrades`` variable in the RabbitMQ role defaults. + +Operators can customize or extend these allowed upgrade paths by overriding +this variable in ``globals.yml``. + +.. code-block:: yaml + + rabbitmq_allowed_upgrades: + "3.13": + - "4.0" + - "4.1" + - "4.2" + "4.0": + - "4.1" + - "4.2" + +If an invalid upgrade path is detected, the deployment will fail with a +descriptive error message during the ``rabbitmq-version-check`` task, +suggesting the next appropriate intermediate version. + +Handling Stream Replicas +~~~~~~~~~~~~~~~~~~~~~~~~ + +RabbitMQ streams are expected to be replicated across the nodes in the +cluster. However, RabbitMQ itself will only create replicas of a stream when +the stream is initially declared. This means that any streams declared when a +RabbitMQ node is out of service must be explicitly managed by an operator. +RabbitMQ documents how to manage stream replicas here: +https://www.rabbitmq.com/docs/streams#member-management + +An example script to create any missing stream replicas can be found under +`kolla-ansible/contrib/ops/rabbitmq/rabbitmq-repair-stream-replicas.sh +<https://opendev.org/openstack/kolla-ansible/src/branch/master/contrib/ops/rabbitmq/rabbitmq-repair-stream-replicas.sh>`__. +This should be executed from a host running the RabbitMQ container. +Currently, membership changes for streams `is not entirely safe +<https://github.com/rabbitmq/rabbitmq-server/discussions/14246>`__, so this +script should only be used when the RabbitMQ cluster is in a known healthy +state. diff --git a/doc/source/reference/shared-services/keystone-guide.rst b/doc/source/reference/shared-services/keystone-guide.rst index b92230dcb..173766022 100644 --- a/doc/source/reference/shared-services/keystone-guide.rst +++ b/doc/source/reference/shared-services/keystone-guide.rst @@ -96,13 +96,13 @@ used by OpenStack command line client. Example config shown below: keystone_federation_oidc_jwks_uri: "https://<AUTH PROVIDER>/<ID>/discovery/v2.0/keys" -Some identity providers need additional mod_auth_openidc config. -Example for Keycloak shown below: +Some identity providers need additional ``mod_auth_openidc`` config, which can +be passed with the ``keystone_federation_oidc_additional_options`` variable: .. code-block:: yaml keystone_federation_oidc_additional_options: - OIDCTokenBindingPolicy: disabled + OIDCOutgoingProxy: "http://proxy.example.com" When using OIDC, operators can also use the following variable to customize the delay to retry authenticating in the IdP if the @@ -131,6 +131,11 @@ openstack_domain The OpenStack domain that the Identity Provider belongs. +.. note:: + Kolla-Ansible does not support duplicate openstack_domain names, + where the ID of the domain is different, but the name is the same. + This is an edge case that is hard to take into account. + protocol ******** diff --git a/doc/source/user/multi-regions.rst b/doc/source/user/multi-regions.rst index 32ee9d90d..8d4c4043a 100644 --- a/doc/source/user/multi-regions.rst +++ b/doc/source/user/multi-regions.rst @@ -71,14 +71,6 @@ the value of ``kolla_internal_fqdn`` in RegionOne: keystone_internal_url: "{{ internal_protocol }}://{{ kolla_internal_fqdn_r1 }}:{{ keystone_public_port }}" - openstack_auth: - auth_url: "{{ keystone_internal_url }}" - username: "{{ keystone_admin_user }}" - password: "{{ keystone_admin_password }}" - user_domain_name: "{{ default_user_domain_name }}" - project_name: "{{ keystone_admin_project }}" - domain_name: "default" - .. note:: If the ``kolla_internal_vip_address`` and/or the |