Browse Source

Merge "rehome db api and utils into neutron-lib"

Zuul 1 year ago
parent
commit
d4aa5a56b8
1 changed files with 145 additions and 0 deletions
  1. 145
    0
      specs/rocky/neutronlib-decouple-db-apiutils.rst

+ 145
- 0
specs/rocky/neutronlib-decouple-db-apiutils.rst View File

@@ -0,0 +1,145 @@
1
+..
2
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
3
+ License.
4
+
5
+ http://creativecommons.org/licenses/by/3.0/legalcode
6
+
7
+==================================================
8
+Decoupling database imports/access for neutron-lib
9
+==================================================
10
+
11
+This work is not related to an enhancement request and therefore doesn't have
12
+a RFE. Rather the intent herein is to discuss how we decouple ``neutron.db``
13
+and related database imports/access as part of the overall neutron-lib effort.
14
+
15
+Current neutron database access can be broken into the following high-level
16
+categories:
17
+
18
+- Database API & Utilities
19
+- Core & Extension Database Mixins
20
+- Database Resource Models
21
+- Database Migration
22
+
23
+As the database access patterns span a wide range of logic/code, a set of specs
24
+will be proposed each focusing on a single access pattern.
25
+
26
+This spec specifically address the Database API & Utilities access.
27
+
28
+For current neutron-lib related blueprints, see [1]_ and [2]_.
29
+
30
+
31
+Problem Description
32
+===================
33
+
34
+As part of our neutron-lib effort, we need to decouple out-of-tree networking
35
+projects that depend on (e.g. ``import``) neutron. However, today a large
36
+number of neutron consumers import database related neutron modules [3]_ [4]_
37
+[5]_. While some of these dependencies are rehomeable into neutron-lib without
38
+significant effort, others create a large dependency chain with neutron
39
+internals, coupling them to neutron itself.
40
+
41
+The intent of this spec is to propose how we can rehome the neutron database
42
+API and utilities into neutron-lib breaking consumer dependencies on these
43
+neutron modules. The access patterns herein were gathered by inspecting usages
44
+of the respective modules using [3]_, [4]_, [5]_, [6]_.
45
+
46
+Proposed Change
47
+===============
48
+
49
+This spec proposes we rehome the generic database API/utility functionality
50
+into neutron-lib. The following considerations must be taken into account
51
+for all applicable code:
52
+
53
+- If the functionality is private and not used outside of neutron today,
54
+  it can likely stay in neutron as private to reduce public API surface area.
55
+- If the functionality is private, but used outside of neutron, it's a
56
+  candidate for rehoming.
57
+- For code applicable to rehoming, determine the best form for the
58
+  implementation. If used by non-OVO consumers then likely it'll be
59
+  necessary to rehome as "generic database logic". However if applicable
60
+  to OVO, it may make sense to incorporate the logic into neutron objects
61
+  that will be rehomed in subsequent work.
62
+
63
+When the work for this spec is done, we should no longer have any consumers
64
+using neutron's database API or utils [3]_, [4]_, [5]_, [6]_, but rather
65
+using them from neutron-lib.
66
+
67
+Subsequent subsections describe each module in greater detail.
68
+
69
+Note that ``provisioning_blocks`` will be addressed in subsequent specs
70
+as it requires versioned objects and thus will need access to them via
71
+neutron-lib in order to implement.
72
+
73
+Database API
74
+------------
75
+
76
+The ``neutron.db.api`` module is used broadly today [3]_ and has already begun
77
+rehoming into neutron-lib [7]_. Therefore this spec proposes we finish the
78
+database API rehoming work by:
79
+
80
+- Rehoming the remaining externally used functions in the API. This includes
81
+  generic functions such as ``is_retriable`` as well as decorators like
82
+  ``retry_db_errors`` and ``retry_if_session_inactive``.
83
+- Removing deprecated and unused functions such as ``load_one_to_manys`` and
84
+  ``get_session``.
85
+- The osprofiler setup/initialization will need to be addressed to ensure
86
+  proper profiling functionality.
87
+- Unit tests will need to be in place for the rehomed functionality; rehomed
88
+  and/or written as needed.
89
+- Consuming the rehomed changes once released.
90
+
91
+Generic Utils
92
+-------------
93
+
94
+The ``neutron.db._utils`` module contains generic logic and is thus used by
95
+some consumers today [4]_. This spec therefore proposes we rehome the used
96
+functionality into neutron-lib by:
97
+
98
+- Rehoming the used functions such as ``resource_fields`` and
99
+  ``get_marker_obj``
100
+- Rehoming any functions use in the model query utils (see subsequent section)
101
+  into neutron-lib.
102
+- Ensuring the proper unit test coverage is in place for the rehomed code.
103
+- Consuming the rehomed changes once released.
104
+
105
+Model Query Utils
106
+-----------------
107
+
108
+While today ``neutron.db._model_query`` is private, some consumers use it [5]_.
109
+As this module contains generic database logic, it's a candidate for rehoming
110
+to neutron-lib as a generic model hook module by:
111
+
112
+- Rehoming the logic in the ``_model_query`` module itself to neutron-lib.
113
+- Ensuring the generic utils are in lib that are required for this module.
114
+  See the previous section on generic utils.
115
+- Rehoming the few used functions from ``neutron.common.utils`` used in the
116
+  module query module. These are generic in nature and thus don't raise any
117
+  red flags for rehoming.
118
+- Rehoming ``neutron.objects.utils`` to neutron-lib as its used in the model
119
+  query logic.
120
+- Ensuring the proper unit test coverage is in place for the rehomed code.
121
+- Consuming the rehomed changes once released.
122
+
123
+Resource Extend
124
+---------------
125
+
126
+The ``neutron.db._resource_extend`` module is used by consumers today [6]_ and
127
+as it contains generic functionality, can also move into neutron-lib by:
128
+
129
+- Rehoming the resource extend module into neutron-lib.
130
+- Rehoming the single generic ``neutron.common.util`` function required
131
+  by the module into neutron-lib.
132
+- Ensuring the proper unit test coverage is in place for the rehomed code.
133
+- Consuming the rehomed changes once released.
134
+
135
+
136
+References
137
+==========
138
+
139
+.. [1] https://blueprints.launchpad.net/neutron/+spec/neutron-lib-networking-ovn
140
+.. [2] https://blueprints.launchpad.net/neutron/+spec/neutron-lib-dynr
141
+.. [3] http://codesearch.openstack.org/?q=from%20neutron%5C.db%20import%20api
142
+.. [4] http://codesearch.openstack.org/?q=from%20neutron%5C.db%20import%20_utils
143
+.. [5] http://codesearch.openstack.org/?q=from%20neutron%5C.db%20import%20_model_query
144
+.. [6] http://codesearch.openstack.org/?q=from%20neutron%5C.db%20import%20_resource_extend
145
+.. [7] https://github.com/openstack/neutron-lib/blob/master/neutron_lib/db/api.py

Loading…
Cancel
Save