Coverage for nova/conf/api.py: 93%
15 statements
« prev ^ index » next coverage.py v7.6.12, created at 2025-04-17 15:08 +0000
1# Copyright 2015 OpenStack Foundation
2# All Rights Reserved.
3#
4# Licensed under the Apache License, Version 2.0 (the "License"); you may
5# not use this file except in compliance with the License. You may obtain
6# a copy of the License at
7#
8# http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13# License for the specific language governing permissions and limitations
14# under the License.
16from oslo_config import cfg
18api_group = cfg.OptGroup('api',
19 title='API options',
20 help="""
21Options under this group are used to define Nova API.
22""")
24auth_opts = [
25 cfg.StrOpt("auth_strategy",
26 default="keystone",
27 choices=[
28 ("keystone", "Use keystone for authentication."),
29 ("noauth2", "Designed for testing only, as it does no actual "
30 "credential checking. 'noauth2' provides administrative "
31 "credentials only if 'admin' is specified as the username."),
32 ],
33 deprecated_for_removal=True,
34 deprecated_since='21.0.0',
35 deprecated_reason="""
36The only non-default choice, ``noauth2``, is for internal development and
37testing purposes only and should not be used in deployments. This option and
38its middleware, NoAuthMiddleware[V2_18], will be removed in a future release.
39""",
40 help="""
41Determine the strategy to use for authentication.
42"""),
43]
45metadata_opts = [
46 cfg.StrOpt("config_drive_skip_versions",
47 default=("1.0 2007-01-19 2007-03-01 2007-08-29 2007-10-10 "
48 "2007-12-15 2008-02-01 2008-09-01"),
49 deprecated_group="DEFAULT",
50 help="""
51When gathering the existing metadata for a config drive, the EC2-style
52metadata is returned for all versions that don't appear in this option.
53As of the Liberty release, the available versions are:
55* 1.0
56* 2007-01-19
57* 2007-03-01
58* 2007-08-29
59* 2007-10-10
60* 2007-12-15
61* 2008-02-01
62* 2008-09-01
63* 2009-04-04
65The option is in the format of a single string, with each version separated
66by a space.
68Possible values:
70* Any string that represents zero or more versions, separated by spaces.
71"""),
72 cfg.ListOpt('vendordata_providers',
73 item_type=cfg.types.String(choices=[
74 ('StaticJSON', 'Load a JSON file from the path configured by '
75 '``vendordata_jsonfile_path`` and use this as the source for '
76 '``vendor_data.json`` and ``vendor_data2.json``.'),
77 ('DynamicJSON', 'Build a JSON file using values defined in '
78 '``vendordata_dynamic_targets`` and use this as the source '
79 'for ``vendor_data2.json``.'),
80 ]),
81 default=['StaticJSON'],
82 deprecated_group="DEFAULT",
83 help="""
84A list of vendordata providers.
86vendordata providers are how deployers can provide metadata via configdrive
87and metadata that is specific to their deployment.
89For more information on the requirements for implementing a vendordata
90dynamic endpoint, please see the vendordata.rst file in the nova developer
91reference.
93Related options:
95* ``vendordata_dynamic_targets``
96* ``vendordata_dynamic_ssl_certfile``
97* ``vendordata_dynamic_connect_timeout``
98* ``vendordata_dynamic_read_timeout``
99* ``vendordata_dynamic_failure_fatal``
100"""),
101 cfg.ListOpt('vendordata_dynamic_targets',
102 default=[],
103 deprecated_group="DEFAULT",
104 help="""
105A list of targets for the dynamic vendordata provider. These targets are of
106the form ``<name>@<url>``.
108The dynamic vendordata provider collects metadata by contacting external REST
109services and querying them for information about the instance. This behaviour
110is documented in the vendordata.rst file in the nova developer reference.
111"""),
112 cfg.StrOpt('vendordata_dynamic_ssl_certfile',
113 default='',
114 deprecated_group="DEFAULT",
115 help="""
116Path to an optional certificate file or CA bundle to verify dynamic
117vendordata REST services ssl certificates against.
119Possible values:
121* An empty string, or a path to a valid certificate file
123Related options:
125* vendordata_providers
126* vendordata_dynamic_targets
127* vendordata_dynamic_connect_timeout
128* vendordata_dynamic_read_timeout
129* vendordata_dynamic_failure_fatal
130"""),
131 cfg.IntOpt('vendordata_dynamic_connect_timeout',
132 default=5,
133 min=3,
134 deprecated_group="DEFAULT",
135 help="""
136Maximum wait time for an external REST service to connect.
138Possible values:
140* Any integer with a value greater than three (the TCP packet retransmission
141 timeout). Note that instance start may be blocked during this wait time,
142 so this value should be kept small.
144Related options:
146* vendordata_providers
147* vendordata_dynamic_targets
148* vendordata_dynamic_ssl_certfile
149* vendordata_dynamic_read_timeout
150* vendordata_dynamic_failure_fatal
151"""),
152 cfg.IntOpt('vendordata_dynamic_read_timeout',
153 default=5,
154 min=0,
155 deprecated_group="DEFAULT",
156 help="""
157Maximum wait time for an external REST service to return data once connected.
159Possible values:
161* Any integer. Note that instance start is blocked during this wait time,
162 so this value should be kept small.
164Related options:
166* vendordata_providers
167* vendordata_dynamic_targets
168* vendordata_dynamic_ssl_certfile
169* vendordata_dynamic_connect_timeout
170* vendordata_dynamic_failure_fatal
171"""),
172 cfg.BoolOpt('vendordata_dynamic_failure_fatal',
173 default=False,
174 help="""
175Should failures to fetch dynamic vendordata be fatal to instance boot?
177Related options:
179* vendordata_providers
180* vendordata_dynamic_targets
181* vendordata_dynamic_ssl_certfile
182* vendordata_dynamic_connect_timeout
183* vendordata_dynamic_read_timeout
184"""),
185 cfg.IntOpt("metadata_cache_expiration",
186 default=15,
187 min=0,
188 deprecated_group="DEFAULT",
189 help="""
190This option is the time (in seconds) to cache metadata. When set to 0,
191metadata caching is disabled entirely; this is generally not recommended for
192performance reasons. Increasing this setting should improve response times
193of the metadata API when under heavy load. Higher values may increase memory
194usage, and result in longer times for host metadata changes to take effect.
195"""),
196 cfg.BoolOpt("local_metadata_per_cell",
197 default=False,
198 help="""
199Indicates that the nova-metadata API service has been deployed per-cell, so
200that we can have better performance and data isolation in a multi-cell
201deployment. Users should consider the use of this configuration depending on
202how neutron is setup. If you have networks that span cells, you might need to
203run nova-metadata API service globally. If your networks are segmented along
204cell boundaries, then you can run nova-metadata API service per cell. When
205running nova-metadata API service per cell, you should also configure each
206Neutron metadata-agent to point to the corresponding nova-metadata API
207service.
208"""),
209 cfg.StrOpt("dhcp_domain",
210 deprecated_group="DEFAULT",
211 default="novalocal",
212 help="""
213Domain name used to configure FQDN for instances.
215Configure a fully-qualified domain name for instance hostnames. The value is
216suffixed to the instance hostname from the database to construct the hostname
217that appears in the metadata API. To disable this behavior (for example in
218order to correctly support microversion's 2.94 FQDN hostnames), set this to the
219empty string.
221Possible values:
223* Any string that is a valid domain name.
224"""),
225]
227file_opts = [
228 cfg.StrOpt("vendordata_jsonfile_path",
229 deprecated_group="DEFAULT",
230 help="""
231Cloud providers may store custom data in vendor data file that will then be
232available to the instances via the metadata service, and to the rendering of
233config-drive. The default class for this, JsonFileVendorData, loads this
234information from a JSON file, whose path is configured by this option. If
235there is no path set by this option, the class returns an empty dictionary.
237Note that when using this to provide static vendor data to a configuration
238drive, the nova-compute service must be configured with this option and the
239file must be accessible from the nova-compute host.
241Possible values:
243* Any string representing the path to the data file, or an empty string
244 (default).
245""")
246]
248osapi_opts = [
249 cfg.IntOpt("max_limit",
250 default=1000,
251 min=0,
252 deprecated_group="DEFAULT",
253 deprecated_name="osapi_max_limit",
254 help="""
255As a query can potentially return many thousands of items, you can limit the
256maximum number of items in a single response by setting this option.
257"""),
258 cfg.StrOpt("compute_link_prefix",
259 deprecated_group="DEFAULT",
260 deprecated_name="osapi_compute_link_prefix",
261 help="""
262This string is prepended to the normal URL that is returned in links to the
263OpenStack Compute API. If it is empty (the default), the URLs are returned
264unchanged.
266Possible values:
268* Any string, including an empty string (the default).
269"""),
270 cfg.StrOpt("glance_link_prefix",
271 deprecated_group="DEFAULT",
272 deprecated_name="osapi_glance_link_prefix",
273 help="""
274This string is prepended to the normal URL that is returned in links to
275Glance resources. If it is empty (the default), the URLs are returned
276unchanged.
278Possible values:
280* Any string, including an empty string (the default).
281"""),
282 cfg.BoolOpt("instance_list_per_project_cells",
283 default=False,
284 help="""
285When enabled, this will cause the API to only query cell databases
286in which the tenant has mapped instances. This requires an additional
287(fast) query in the API database before each list, but also
288(potentially) limits the number of cell databases that must be queried
289to provide the result. If you have a small number of cells, or tenants
290are likely to have instances in all cells, then this should be
291False. If you have many cells, especially if you confine tenants to a
292small subset of those cells, this should be True.
293"""),
294 cfg.StrOpt("instance_list_cells_batch_strategy",
295 default="distributed",
296 choices=[
297 ("distributed", "Divide the "
298 "limit requested by the user by the number of cells in the "
299 "system. This requires counting the cells in the system "
300 "initially, which will not be refreshed until service restart "
301 "or SIGHUP. The actual batch size will be increased by 10% "
302 "over the result of ($limit / $num_cells)."),
303 ("fixed", "Request fixed-size batches from each cell, as defined "
304 "by ``instance_list_cells_batch_fixed_size``. "
305 "If the limit is smaller than the batch size, the limit "
306 "will be used instead. If you do not wish batching to be used "
307 "at all, setting the fixed size equal to the ``max_limit`` "
308 "value will cause only one request per cell database to be "
309 "issued."),
310 ],
311 help="""
312This controls the method by which the API queries cell databases in
313smaller batches during large instance list operations. If batching is
314performed, a large instance list operation will request some fraction
315of the overall API limit from each cell database initially, and will
316re-request that same batch size as records are consumed (returned)
317from each cell as necessary. Larger batches mean less chattiness
318between the API and the database, but potentially more wasted effort
319processing the results from the database which will not be returned to
320the user. Any strategy will yield a batch size of at least 100 records,
321to avoid a user causing many tiny database queries in their request.
323Related options:
325* instance_list_cells_batch_fixed_size
326* max_limit
327"""),
328 cfg.IntOpt("instance_list_cells_batch_fixed_size",
329 min=100,
330 default=100,
331 help="""
332This controls the batch size of instances requested from each cell
333database if ``instance_list_cells_batch_strategy``` is set to ``fixed``.
334This integral value will define the limit issued to each cell every time
335a batch of instances is requested, regardless of the number of cells in
336the system or any other factors. Per the general logic called out in
337the documentation for ``instance_list_cells_batch_strategy``, the
338minimum value for this is 100 records per batch.
340Related options:
342* instance_list_cells_batch_strategy
343* max_limit
344"""),
345 cfg.BoolOpt("list_records_by_skipping_down_cells",
346 default=True,
347 help="""
348When set to False, this will cause the API to return a 500 error if there is an
349infrastructure failure like non-responsive cells. If you want the API to skip
350the down cells and return the results from the up cells set this option to
351True.
353Note that from API microversion 2.69 there could be transient conditions in the
354deployment where certain records are not available and the results could be
355partial for certain requests containing those records. In those cases this
356option will be ignored. See "Handling Down Cells" section of the Compute API
357guide (https://docs.openstack.org/api-guide/compute/down_cells.html) for
358more information.
359"""),
360]
362os_network_opts = [
363 cfg.BoolOpt("use_neutron_default_nets",
364 default=False,
365 deprecated_group="DEFAULT",
366 help="""
367When True, the TenantNetworkController will query the Neutron API to get the
368default networks to use.
370Related options:
372* neutron_default_tenant_id
373"""),
374 cfg.StrOpt("neutron_default_tenant_id",
375 default="default",
376 deprecated_group="DEFAULT",
377 help="""
378Tenant ID for getting the default network from Neutron API (also referred in
379some places as the 'project ID') to use.
381Related options:
383* use_neutron_default_nets
384"""),
385]
387enable_inst_pw_opts = [
388 cfg.BoolOpt("enable_instance_password",
389 default=True,
390 deprecated_group="DEFAULT",
391 help="""
392Enables returning of the instance password by the relevant server API calls
393such as create, rebuild, evacuate, or rescue. If the hypervisor does not
394support password injection, then the password returned will not be correct,
395so if your hypervisor does not support password injection, set this to False.
396""")
397]
399validation_opts = [
400 cfg.StrOpt(
401 "response_validation",
402 choices=(
403 (
404 "error",
405 "Raise a HTTP 500 (Server Error) for responses that fail "
406 "response body schema validation",
407 ),
408 (
409 "warn",
410 "Log a warning for responses that fail response body schema "
411 "validation",
412 ),
413 (
414 "ignore",
415 "Ignore response body schema validation failures",
416 ),
417 ),
418 default="warn",
419 help="""\
420Configure validation of API responses.
422``warn`` is the current recommendation for production environments. This is
423expected to change to ``error`` in a future release.
425If you find it necessary to enable the ``ignore`` option, please report the
426issues you are seeing to the Nova team so we can improve our schemas.
427""",
428 ),
429]
431API_OPTS = (auth_opts +
432 metadata_opts +
433 file_opts +
434 osapi_opts +
435 os_network_opts +
436 enable_inst_pw_opts +
437 validation_opts)
440def register_opts(conf):
441 conf.register_group(api_group)
442 conf.register_opts(API_OPTS, group=api_group)
445def list_opts():
446 return {api_group: API_OPTS}