diff options
Diffstat (limited to 'doc')
19 files changed, 152 insertions, 56 deletions
diff --git a/doc/requirements.txt b/doc/requirements.txt index da3f3abff..cd53b9f22 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,12 +1,5 @@ -# The order of packages is significant, because pip processes them in the order -# of appearance. Changing the order has an impact on the overall integration -# process, which may cause wedges in the gate later. -# Order matters to the pip dependency resolver, so sorting this file -# changes how packages are installed. New dependencies should be -# added in alphabetical order, however, some dependencies may need to -# be installed in a specific order. openstackdocstheme>=2.2.1 # Apache-2.0 reno>=3.1.0 # Apache-2.0 sphinx>=2.0.0,!=2.1.0 # BSD sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD -whereto>=0.3.0 # Apache-2.0 +whereto>=0.5.0 # Apache-2.0 diff --git a/doc/source/admin/advanced-configuration.rst b/doc/source/admin/advanced-configuration.rst index c0177341a..579dd11ca 100644 --- a/doc/source/admin/advanced-configuration.rst +++ b/doc/source/admin/advanced-configuration.rst @@ -271,10 +271,6 @@ By default, HAProxy uses ``local1``. syslog_haproxy_facility: "local1" -If Glance TLS backend is enabled (``glance_enable_tls_backend``), the syslog -facility for the ``glance_tls_proxy`` service uses ``local2`` by default. This -can be set via ``syslog_glance_tls_proxy_facility``. - Mount additional Docker volumes in containers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/admin/mariadb-backup-and-restore.rst b/doc/source/admin/mariadb-backup-and-restore.rst index 69fd411fd..596b7f952 100644 --- a/doc/source/admin/mariadb-backup-and-restore.rst +++ b/doc/source/admin/mariadb-backup-and-restore.rst @@ -41,11 +41,11 @@ Backup Procedure To perform a full backup, run the following command: -``kolla-ansible mariadb_backup -i INVENTORY`` +``kolla-ansible mariadb-backup -i INVENTORY`` Or to perform an incremental backup: -``kolla-ansible mariadb_backup -i INVENTORY --incremental`` +``kolla-ansible mariadb-backup -i INVENTORY --incremental`` Kolla doesn't currently manage the scheduling of these backups, so you'll need to configure an appropriate scheduler (i.e cron) to run these commands @@ -127,7 +127,7 @@ pointing to the first node of the cluster: .. code-block:: console - kolla-ansible mariadb_recovery -i multinode -e mariadb_recover_inventory_name=controller1 + kolla-ansible mariadb-recovery -i multinode -e mariadb_recover_inventory_name=controller1 The above procedure is valid also for a disaster recovery scenario. In such case, first copy MariaDB backup file from the external source into diff --git a/doc/source/admin/password-rotation.rst b/doc/source/admin/password-rotation.rst index fe5b5bdb0..e5cfd0261 100644 --- a/doc/source/admin/password-rotation.rst +++ b/doc/source/admin/password-rotation.rst @@ -142,7 +142,7 @@ manually. .. code:: bash - mysql --batch -uroot -p + mariadb --batch -uroot -p #. Check the current state of the ``root`` user: diff --git a/doc/source/admin/production-architecture-guide.rst b/doc/source/admin/production-architecture-guide.rst index d1da7eaad..ced3571fa 100644 --- a/doc/source/admin/production-architecture-guide.rst +++ b/doc/source/admin/production-architecture-guide.rst @@ -14,6 +14,8 @@ Node types and services running on them A basic Kolla inventory consists of several types of nodes, known in Ansible as ``groups``. +* Deployment - Host from which you're running kolla-ansible CLI + * Control - Cloud controller nodes which host control services like APIs and databases. This group should have odd number of nodes for quorum. @@ -29,6 +31,14 @@ A basic Kolla inventory consists of several types of nodes, known in Ansible as * Monitoring - Monitor nodes which host monitoring services. +.. warning:: + + All hosts should be hardened and access to them should be limited, + because Ansible can leak administrative passwords and other secrets to + system log. The same leaked passwords can be observed in OpenSearch if + you're pushing your system logs there. + + Network configuration ~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/conf.py b/doc/source/conf.py index 785cb15e2..af435eeb3 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -142,10 +142,10 @@ else: TESTED_RUNTIMES_GOVERNANCE_URL =\ 'https://governance.openstack.org/tc/reference/runtimes/{}.html'.format(KOLLA_OPENSTACK_RELEASE) -ANSIBLE_CORE_VERSION_MIN = '2.18' -ANSIBLE_CORE_VERSION_MAX = '2.19' -ANSIBLE_VERSION_MIN = '11' -ANSIBLE_VERSION_MAX = '12' +ANSIBLE_CORE_VERSION_MIN = '2.19' +ANSIBLE_CORE_VERSION_MAX = '2.20' +ANSIBLE_VERSION_MIN = '12' +ANSIBLE_VERSION_MAX = '13' GLOBAL_VARIABLE_MAP = { '|ANSIBLE_CORE_VERSION_MIN|': ANSIBLE_CORE_VERSION_MIN, diff --git a/doc/source/contributor/ci-matrix.csv b/doc/source/contributor/ci-matrix.csv new file mode 100644 index 000000000..c49b72868 --- /dev/null +++ b/doc/source/contributor/ci-matrix.csv @@ -0,0 +1,24 @@ +Scenario;Disabled;Voting;Tempest;Core;Upgrade;SLURP;Multinode;TLS;Ceph;Cinder;Octavia;Valkey;Notes
+AIO core;–;✅;✅;✅;✅;✅;–;✅;–;–;–;–;"Core OpenStack (Keystone/Glance/Neutron/Nova/Heat) with Horizon; RabbitMQ/MariaDB/Memcached; Fluentd."
+Bifrost;–;–;–;–;–;–;–;–;–;–;–;–;Bifrost baremetal provisioning standalone.
+Cells;–;✅;✅;–;✅;–;✅;–;–;–;–;–;"Nova Cells v2 + ProxySQL; Horizon/Heat on; dashboard sanity."
+Cephadm;–;✅;✅;✅;✅;✅;✅;✅;✅;–;✅;✅;"External Ceph (cinder/glance/nova) + RGW; RabbitMQ tuned."
+Container engine migration;❌;–;✅;✅;–;–;✅;✅;–;–;–;–;"Container engine migration playbook; Tempest smoke; currently disabled (failing)."
+Federation;–;–;✅;–;✅;–;✅;✅;–;–;–;–;Keystone federation behind httpd.
+HAProxy FQDN;–;–;✅;–;–;–;✅;✅;–;–;–;–;HAProxy VIP/FQDN handling.
+Ironic;–;–;✅;✅;–;–;–;–;–;–;–;–;"Ironic + Tenks; Prometheus on; DNSMasq/iSCSI helpers."
+IPv6;❌;–;✅;–;✅;–;–;–;–;–;–;–;"IPv6-only deployment; currently disabled (disk pressure)."
+Kayobe;–;–;–;–;–;–;–;–;–;–;–;–;Kayobe overcloud smoke (non-voting).
+KVM;–;–;–;✅;–;–;✅;–;–;–;–;–;Nested virt compute (KVM).
+Let's Encrypt;–;✅;✅;–;✅;–;✅;–;–;–;–;–;"Pebble ACME end-to-end, dashboard; DB/Rabbit TLS."
+Magnum;–;–;✅;–;–;–;–;–;–;–;–;–;Magnum + Designate + Trove.
+MariaDB;–;✅;–;✅;✅;–;✅;–;–;–;–;–;Galera + ProxySQL, Fluentd, HAProxy, Keepalived.
+Masakari;–;–;✅;–;–;–;–;–;–;–;–;✅;Masakari + Pacemaker.
+NFV;–;–;✅;–;✅;–;–;–;–;–;✅;✅;Tacker + Neutron SFC, Barbican, Mistral, Aodh.
+Octavia;–;–;✅;–;–;–;–;–;✅;✅;–;–;Octavia/Amphora.
+OpenBao;–;–;–;–;–;–;–;–;–;–;–;–;"OpenBao-backed password management (password round-trip only; no deploy)."
+OVN;–;✅;✅;✅;✅;–;✅;✅;–;✅;–;–;Neutron ML2/OVN + OVN Octavia provider.
+Prometheus + OpenSearch;–;–;–;✅;–;✅;✅;–;–;–;–;–;Fluentd, OpenSearch, Grafana, Prometheus, RabbitMQ/DB core.
+Skyline;❌;–;✅;–;–;✅;–;–;–;–;–;–;"Skyline dashboard; currently disabled (SSO issues)."
+Telemetry;–;–;✅;–;–;✅;–;–;–;–;✅;✅;Aodh, Ceilometer, Gnocchi.
+Zun;–;✅;✅;–;✅;✅;✅;✅;–;–;–;–;"Zun + Kuryr + Cinder LVM; etcd; dashboard."
diff --git a/doc/source/contributor/ci.rst b/doc/source/contributor/ci.rst index 71f9e3032..0ffd7d498 100644 --- a/doc/source/contributor/ci.rst +++ b/doc/source/contributor/ci.rst @@ -28,3 +28,21 @@ consumes a large amount of logging resources. Please note that git usually strips lines beginning with `#` from the commit message. This can be avoided by preceding the string with a space. + +CI coverage matrix +~~~~~~~~~~~~~~~~~~ + +Zuul job templates live in ``zuul.d`` and are applied in +``zuul.d/project.yaml``. Pipelines always run tox/python style+unit checks, +docs/release builds, and requirements checks; the matrix below shows the +scenario jobs in ``check``/``gate``. + +.. csv-table:: Scenario matrix + :header-rows: 1 + :file: ci-matrix.csv + :widths: 12 7 7 7 7 7 7 7 7 7 7 7 7 12 + :delim: ; + +Legend: ✅ = covered, ❌ = disabled, – = not covered. ``Core`` means the standard +Keystone/Glance/Neutron/Nova/Heat stack is deployed; ``Tempest`` indicates +smoke tests run; ``SLURP`` = Skip Level Upgrade Release Process. diff --git a/doc/source/reference/bare-metal/ironic-guide.rst b/doc/source/reference/bare-metal/ironic-guide.rst index 99e8bbefb..962ece762 100644 --- a/doc/source/reference/bare-metal/ironic-guide.rst +++ b/doc/source/reference/bare-metal/ironic-guide.rst @@ -52,6 +52,16 @@ For example it can be the same address as default router for the range: routers: "192.168.5.1" ntp_server: "192.168.5.1" +Provide a DNS server if the inspection ramdisk (IPA) needs to resolve +Fully Qualified Domain Names (FQDNs) for API access. To specify multiple +servers, use a comma-separated list. + +.. code-block:: yaml + + ironic_dnsmasq_dhcp_ranges: + - range: "192.168.5.100,192.168.5.110" + dns_servers: "192.168.5.10,192.168.5.11" + To support DHCP relay, it is also possible to define a netmask in the range. It is advisable to also provide a router to allow the traffic to reach the Ironic server. @@ -136,6 +146,22 @@ The port used for conductor's HTTP server is controlled via ironic_http_port: "8089" +Configure Ironic Python Agent NTP server (optional) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The Ironic Python Agent requires that the system clock is set correctly for +the heartbeat mechanism to work. One way of achieving this is to pass +the address of an NTP server via the kernel commandline, which is then +used to set the system clock when IPA first starts. This is not a hard +requirement, and you may use other methods. For example DHCP, or functionality +built into the BMC. + +If you wish to use this option you can set ``ironic_ntp_server`` in +``/etc/kolla/globals.yml``. Eg. + +.. code-block:: yaml + + ironic_ntp_server: "192.168.33.3" + Revert to plain PXE (not recommended) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Starting with Yoga, Ironic has changed the default PXE from plain PXE to iPXE. diff --git a/doc/source/reference/compute/nova-guide.rst b/doc/source/reference/compute/nova-guide.rst index 3cf5848d4..8e083f241 100644 --- a/doc/source/reference/compute/nova-guide.rst +++ b/doc/source/reference/compute/nova-guide.rst @@ -121,3 +121,13 @@ effectively remove the configuration when the Nova Compute service is restarted. If you choose to undefine `nova_cell_compute_provider_config` on a host, you must manually remove the generated config from inside the container, or recreate the container. + +Emulated virtual Trusted Platform Module (vTPM) +=============================================== + +Nova supports adding an emulated virtual Trusted Platform Module (vTPM) to +instances. This feature is implemented with the SWTPM (Software TPM Emulator) +package. To enable this feature, set ``enable_nova_swtpm`` to ``true``. +Beware of `limitations`__ that come with this solution. + + __ https://docs.openstack.org/nova/latest/admin/emulated-tpm.html#limitations diff --git a/doc/source/reference/databases/mariadb-guide.rst b/doc/source/reference/databases/mariadb-guide.rst index e34e4bf0a..c4a40740e 100644 --- a/doc/source/reference/databases/mariadb-guide.rst +++ b/doc/source/reference/databases/mariadb-guide.rst @@ -22,7 +22,7 @@ an independent Galera cluster. This section explains how to configure multiple database shards. Currently, only one shard is accessible via the HAProxy load balancer and supported -by the ``kolla-ansible mariadb_backup`` command. This will be improved +by the ``kolla-ansible mariadb-backup`` command. This will be improved in future by using ProxySQL, allowing load balanced access to all shards. Deployment diff --git a/doc/source/reference/logging-and-monitoring/grafana-guide.rst b/doc/source/reference/logging-and-monitoring/grafana-guide.rst index 12f123a20..6f89c2016 100644 --- a/doc/source/reference/logging-and-monitoring/grafana-guide.rst +++ b/doc/source/reference/logging-and-monitoring/grafana-guide.rst @@ -9,7 +9,7 @@ Overview `Grafana <https://grafana.com>`_ is open and composable observability and data visualization platform. Visualize metrics, logs, and traces from -multiple sources like Prometheus, Loki, Elasticsearch, InfluxDB, +multiple sources like Prometheus, Loki, Elasticsearch, Postgres and many more.. Preparation and deployment @@ -30,6 +30,55 @@ If you would like to set up Prometheus as a data source, additionally set: Please follow :doc:`Prometheus Guide <prometheus-guide>` for more information. +LDAP Authentication +~~~~~~~~~~~~~~~~~~~ + +Grafana can be configured to use LDAP for user authentication. To enable this +feature, set the following variable in ``/etc/kolla/globals.yml``: + +.. code-block:: yaml + + grafana_ldap_enabled: true + +The configuration for the LDAP server should be provided in a ``ldap.toml`` +file placed in the ``{{ node_custom_config }}/grafana/`` folder on the control +host. + +Example ``ldap.toml`` configuration: + +.. code-block:: ini + + [[servers]] + host = "openstack.org" + port = 389 + use_ssl = false + start_tls = true + + bind_dn = "CN=svc-openstack-grafana,OU=serviceaccounts,DC=openstack,DC=org" + bind_password = "strong_password" + + search_filter = "(sAMAccountName=%s)" + search_base_dns = ["OU=Users,DC=openstack,DC=org"] + + [servers.attributes] + name = "givenName" + surname = "sn" + username = "uid" + member_of = "memberOf" + email = "mail" + + [[servers.group_mappings]] + group_dn = "cn=grafana-admins,ou=groups,dc=openstack,dc=org" + org_role = "Admin" + + [[servers.group_mappings]] + group_dn = "cn=grafana-editors,ou=groups,dc=openstack,dc=org" + org_role = "Editor" + + [[servers.group_mappings]] + group_dn = "*" + org_role = "Viewer" + Custom dashboards provisioning ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/reference/logging-and-monitoring/index.rst b/doc/source/reference/logging-and-monitoring/index.rst index 09d017547..05d0b96b7 100644 --- a/doc/source/reference/logging-and-monitoring/index.rst +++ b/doc/source/reference/logging-and-monitoring/index.rst @@ -10,6 +10,5 @@ logging and monitoring services available in kolla. central-logging-guide grafana-guide - influxdb-guide osprofiler-guide prometheus-guide diff --git a/doc/source/reference/logging-and-monitoring/influxdb-guide.rst b/doc/source/reference/logging-and-monitoring/influxdb-guide.rst deleted file mode 100644 index 6bb460d0c..000000000 --- a/doc/source/reference/logging-and-monitoring/influxdb-guide.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _influxdb-guide: - -=============================== -InfluxDB - Time Series Database -=============================== - -Overview -~~~~~~~~ - -InfluxDB is a time series database developed by InfluxData. It is -possible to deploy a single instance without charge. To use the -clustering features you will require a commercial license. - -InfluxDB -~~~~~~~~ - -The `recommendation <https://docs.influxdata.com/influxdb/v1.7/guides/hardware_sizing/#what-kind-of-storage-do-i-need>`_ -is to use flash storage for InfluxDB. If docker is configured to use -spinning disks by default, or you have some higher performance drives -available, it may be desirable to control where the docker volume is -located. This can be achieved by setting a path for -``influxdb_datadir_volume`` in ``/etc/kolla/globals.yml``: - -.. code-block:: yaml - - influxdb_datadir_volume: /mnt/ssd/influxdb/ - -The default is to use a named volume, ``influxdb``. diff --git a/doc/source/reference/message-queues/rabbitmq.rst b/doc/source/reference/message-queues/rabbitmq.rst index 0cb465e0d..375d58fe4 100644 --- a/doc/source/reference/message-queues/rabbitmq.rst +++ b/doc/source/reference/message-queues/rabbitmq.rst @@ -23,7 +23,6 @@ Encryption of the following channels is not currently supported: * RabbitMQ cluster traffic between RabbitMQ server nodes * RabbitMQ CLI communication with RabbitMQ server nodes -* RabbitMQ Management API and UI (backend connection from HAProxy to RabbitMQ) Client-server ------------- diff --git a/doc/source/reference/rating/cloudkitty-guide.rst b/doc/source/reference/rating/cloudkitty-guide.rst index 061e09675..dbe88b9c7 100644 --- a/doc/source/reference/rating/cloudkitty-guide.rst +++ b/doc/source/reference/rating/cloudkitty-guide.rst @@ -60,7 +60,7 @@ Cloudkitty Storage Backend ~~~~~~~~~~~~~~~~~~~~~~~~~~ As for collectors, CloudKitty supports multiple backend to store ratings. -By default, Kolla Ansible uses the InfluxDB based backend. +By default, Kolla Ansible uses the SQLAlchemy based backend. Another famous alternative is OpenSearch and can be activated in Kolla Ansible using the ``cloudkitty_storage_backend`` configuration option in diff --git a/doc/source/user/operating-kolla.rst b/doc/source/user/operating-kolla.rst index a48f3357f..8e931997d 100644 --- a/doc/source/user/operating-kolla.rst +++ b/doc/source/user/operating-kolla.rst @@ -240,7 +240,7 @@ containers. ``kolla-ansible destroy -i INVENTORY`` is used to clean up containers and volumes in the cluster. -``kolla-ansible mariadb_recovery -i INVENTORY`` is used to recover a +``kolla-ansible mariadb-recovery -i INVENTORY`` is used to recover a completely stopped mariadb cluster. ``kolla-ansible prechecks -i INVENTORY`` is used to check if all requirements diff --git a/doc/source/user/quickstart.rst b/doc/source/user/quickstart.rst index b4d855367..f02401fc2 100644 --- a/doc/source/user/quickstart.rst +++ b/doc/source/user/quickstart.rst @@ -261,7 +261,7 @@ There are a few options that are required to deploy Kolla Ansible: * Virtual environment It is recommended to use a virtual environment to execute tasks on the remote - hosts. This is covered + hosts. This is covered in :kolla-ansible-doc:`Virtual Environments <user/virtual-environments.html>`. Deployment diff --git a/doc/source/user/support-matrix.rst b/doc/source/user/support-matrix.rst index 8925a2c02..b2ce35427 100644 --- a/doc/source/user/support-matrix.rst +++ b/doc/source/user/support-matrix.rst @@ -14,7 +14,7 @@ Kolla Ansible supports the following host Operating Systems (OS): Linux 10 images instead. * CentOS Stream 10 -* Debian Bookworm (12) +* Debian Trixie (13) * Rocky Linux 10 * Ubuntu Noble (24.04) |