From f8e68ddcd9d2fa6bcad7bef57d1e04f4af90984c Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Wed, 14 Apr 2021 12:02:38 +0100 Subject: [PATCH] docs: Document location of nova.conf files Turns out oslo.config actually supports executable-specific configuration files as well as directories of configuration files. Who knew? Change-Id: Ifb71a45ed4df3c9cacd2193beed904f948f5cdc8 Signed-off-by: Stephen Finucane --- doc/source/configuration/index.rst | 45 ++++++++++++++++++++++++++---- 1 file changed, 39 insertions(+), 6 deletions(-) diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index 7fd6a43810..f7f40790f1 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/configuration/index.rst @@ -10,6 +10,29 @@ Guide `. Configuration ------------- +Nova, like most OpenStack projects, uses INI-style configuration files to +configure various services and utilities. This functionality is provided by the +`oslo.config`__ project. *oslo.config* supports loading configuration from both +individual configuration files and a directory of configuration files. By +default, nova will search the below directories for two config files - +``nova.conf`` and ``{prog}.conf``, where ``prog`` corresponds to the name of +the service or utility being configured such as :program:`nova-compute` - and +two config directories - ``nova.conf.d`` and ``{prog}.conf.d``: + +- ``${HOME}/.nova`` +- ``${HOME}`` +- ``/etc/nova`` +- ``/etc`` +- ``${SNAP_COMMON}/etc/nova/`` +- ``${SNAP}/etc/nova/`` + +Where a matching file is found, all other directories will be skipped. +This behavior can be overridden by using the ``--config-file`` and +``--config-dir`` options provided for each executable. + +More information on how you can use the configuration options to configure +services and what configuration options are available can be found below. + * :doc:`Configuration Guide `: Detailed configuration guides for various parts of your Nova system. Helpful reference for setting up specific hypervisor backends. @@ -42,11 +65,23 @@ Configuration sample-config +.. __: https://docs.openstack.org/oslo.config/latest/ + Policy ------ Nova, like most OpenStack projects, uses a policy language to restrict -permissions on REST API actions. +permissions on REST API actions. This functionality is provided by the +`oslo.policy`__ project. *oslo.policy* supports loading policy configuration +from both an individual configuration file, which defaults to ``policy.yaml``, +and one or more directories of configuration files, which defaults to +``policy.d``. These must be located in the same directory as the ``nova.conf`` +file(s). This behavior can be overridden by setting the +:oslo.config:option:`oslo_policy.policy_file` and +:oslo.config:option:`oslo_policy.policy_dirs` configuration options. + +More information on how nova's policy configuration works and about what +policies are available can be found below. * :doc:`Policy Concepts `: Starting in the Ussuri release, Nova API policy defines new default roles with system scope @@ -54,11 +89,6 @@ permissions on REST API actions. manageability of Nova API as they are richer in terms of handling access at system and project level token with 'Read' and 'Write' roles. -.. toctree:: - :hidden: - - policy-concepts - * :doc:`Policy Reference `: A complete reference of all policy points in nova and what they impact. @@ -75,6 +105,7 @@ permissions on REST API actions. .. toctree:: :hidden: + policy-concepts policy .. # NOTE(amotoki): Sample files are only available in HTML document. @@ -87,6 +118,8 @@ permissions on REST API actions. sample-policy +.. __: https://docs.openstack.org/oslo.policy/latest/ + Extra Specs -----------