summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDinesh Bhor <dinesh.bhor@nttdata.com>2017-11-22 14:19:20 +0530
committerDinesh Bhor <dinesh.bhor@nttdata.com>2017-11-22 14:39:30 +0530
commite44b4731ddf68e01e436aabbd5c0593cd566bd7d (patch)
tree2cfc9764d4f6db937337b60980d3a491429ed784
parentb08b7ce81919218855902d65b7d615b7a465acb4 (diff)
Fix queens spec directory structure
This patch fixes the queens spec directory structure which is missed by this commit: b08b7ce81919218855902d65b7d615b7a465acb4. Change-Id: I31ac869f22ee472a5dced3dee2473bf160dc11c9
Notes
Notes (review): Code-Review+2: Sampath Priyankara (samP) <sam47priya@gmail.com> Code-Review+1: Louie Kwan <louie.kwan@windriver.com> Workflow+1: Tushar Patil <tushar.vitthal.patil@gmail.com> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Wed, 07 Mar 2018 01:24:03 +0000 Reviewed-on: https://review.openstack.org/522219 Project: openstack/masakari-specs Branch: refs/heads/master
-rw-r--r--doc/source/index.rst1
-rw-r--r--doc/source/specs/queens/approved1
-rw-r--r--doc/source/specs/queens/implemented1
-rw-r--r--doc/source/specs/queens/index.rst26
-rw-r--r--doc/source/specs/queens/redirects1
-rw-r--r--doc/source/specs/queens/template.rst1
-rw-r--r--specs/queens-template.rst389
-rw-r--r--specs/queens/approved/queens-template.rst389
-rw-r--r--specs/queens/implemented/queens-template.rst389
-rw-r--r--specs/queens/redirects0
10 files changed, 1198 insertions, 0 deletions
diff --git a/doc/source/index.rst b/doc/source/index.rst
index e37d445..3ae374c 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -12,6 +12,7 @@ Here you can find the specs, and spec template, for each release:
12 :glob: 12 :glob:
13 :maxdepth: 1 13 :maxdepth: 1
14 14
15 specs/queens/index
15 specs/ocata/index 16 specs/ocata/index
16 specs/pike/index 17 specs/pike/index
17 18
diff --git a/doc/source/specs/queens/approved b/doc/source/specs/queens/approved
new file mode 100644
index 0000000..01ec4c2
--- /dev/null
+++ b/doc/source/specs/queens/approved
@@ -0,0 +1 @@
../../../../specs/queens/approved \ No newline at end of file
diff --git a/doc/source/specs/queens/implemented b/doc/source/specs/queens/implemented
new file mode 100644
index 0000000..a929e05
--- /dev/null
+++ b/doc/source/specs/queens/implemented
@@ -0,0 +1 @@
../../../../specs/queens/implemented \ No newline at end of file
diff --git a/doc/source/specs/queens/index.rst b/doc/source/specs/queens/index.rst
new file mode 100644
index 0000000..2fcaa28
--- /dev/null
+++ b/doc/source/specs/queens/index.rst
@@ -0,0 +1,26 @@
1==============================
2Masakari Queens Specifications
3==============================
4
5Template:
6
7.. toctree::
8 :maxdepth: 1
9
10 Specification Template (Queens release) <template>
11
12Queens implemented specs:
13
14.. toctree::
15 :glob:
16 :maxdepth: 1
17
18 implemented/*
19
20Queens approved (but not implemented) specs:
21
22.. toctree::
23 :glob:
24 :maxdepth: 1
25
26 approved/*
diff --git a/doc/source/specs/queens/redirects b/doc/source/specs/queens/redirects
new file mode 100644
index 0000000..fdef00f
--- /dev/null
+++ b/doc/source/specs/queens/redirects
@@ -0,0 +1 @@
../../../../specs/queens/redirects \ No newline at end of file
diff --git a/doc/source/specs/queens/template.rst b/doc/source/specs/queens/template.rst
new file mode 100644
index 0000000..fb217e8
--- /dev/null
+++ b/doc/source/specs/queens/template.rst
@@ -0,0 +1 @@
../../../../specs/queens-template.rst \ No newline at end of file
diff --git a/specs/queens-template.rst b/specs/queens-template.rst
new file mode 100644
index 0000000..1ad6077
--- /dev/null
+++ b/specs/queens-template.rst
@@ -0,0 +1,389 @@
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==========================================
8Example Spec - The title of your blueprint
9==========================================
10
11Include the URL of your launchpad blueprint:
12
13https://blueprints.launchpad.net/masakari/+spec/example
14
15Introduction paragraph -- why are we doing anything? A single paragraph of
16prose that operators can understand. The title and this first paragraph
17should be used as the subject line and body of the commit message
18respectively.
19
20Some notes about the masakari-spec and blueprint process:
21
22* Not all blueprints need a spec. For more information see
23 https://wiki.openstack.org/wiki/Masakari-specs
24
25* The aim of this document is first to define the problem we need to solve,
26 and second agree the overall approach to solve that problem.
27
28* This is not intended to be extensive documentation for a new feature.
29 For example, there is no need to specify the exact configuration changes,
30 nor the exact details of any DB model changes. But you should still define
31 that such changes are required, and be clear on how that will affect
32 upgrades.
33
34* You should aim to get your spec approved before writing your code.
35 While you are free to write prototypes and code before getting your spec
36 approved, its possible that the outcome of the spec review process leads
37 you towards a fundamentally different solution than you first envisaged.
38
39* But, API changes are held to a much higher level of scrutiny.
40 As soon as an API change merges, we must assume it could be in production
41 somewhere, and as such, we then need to support that API change forever.
42 To avoid getting that wrong, we do want lots of details about API changes
43 upfront.
44
45Some notes about using this template:
46
47* Your spec should be in ReSTructured text, like this template.
48
49* Please wrap text at 79 columns.
50
51* The filename in the git repository should match the launchpad URL, for
52 example a URL of: https://blueprints.launchpad.net/masakari/+spec/awesome-thing
53 should be named awesome-thing.rst
54
55* Please do not delete any of the sections in this template. If you have
56 nothing to say for a whole section, just write: None
57
58* For help with syntax, see http://sphinx-doc.org/rest.html
59
60* To test out your formatting, build the docs using tox and see the generated
61 HTML file in doc/build/html/specs/<path_of_your_file>
62
63* If you would like to provide a diagram with your spec, ascii diagrams are
64 required. http://asciiflow.com/ is a very nice tool to assist with making
65 ascii diagrams. The reason for this is that the tool used to review specs is
66 based purely on plain text. Plain text will allow review to proceed without
67 having to look at additional files which can not be viewed in gerrit. It
68 will also allow inline feedback on the diagram itself.
69
70* If your specification proposes any changes to the Masakari REST API such
71 as changing parameters which can be returned or accepted, or even
72 the semantics of what happens when a client calls into the API, then
73 you should add the APIImpact flag to the commit message.
74
75Problem description
76===================
77
78A detailed description of the problem. What problem is this blueprint
79addressing?
80
81Use Cases
82---------
83
84What use cases does this address? What impact on actors does this change have?
85Ensure you are clear about the actors in each use case: Developer, End User,
86Deployer etc.
87
88Proposed change
89===============
90
91Here is where you cover the change you propose to make in detail. How do you
92propose to solve this problem?
93
94If this is one part of a larger effort make it clear where this piece ends. In
95other words, what's the scope of this effort?
96
97At this point, if you would like to just get feedback on if the problem and
98proposed change fit in Masakari, you can stop here and post this for
99review to get preliminary feedback. If so please say:
100Posting to get preliminary feedback on the scope of this spec.
101
102Alternatives
103------------
104
105What other ways could we do this thing? Why aren't we using those? This doesn't
106have to be a full literature review, but it should demonstrate that thought has
107been put into why the proposed solution is an appropriate one.
108
109Data model impact
110-----------------
111
112Changes which require modifications to the data model often have a wider impact
113on the system. The community often has strong opinions on how the data model
114should be evolved, from both a functional and performance perspective. It is
115therefore important to capture and gain agreement as early as possible on any
116proposed changes to the data model.
117
118Questions which need to be addressed by this section include:
119
120* What new data objects and/or database schema changes is this going to
121 require?
122
123* What database migrations will accompany this change.
124
125* How will the initial set of new data objects be generated, for example if you
126 need to take into account existing instances, or modify other existing data
127 describe how that will work.
128
129REST API impact
130---------------
131
132Each API method which is either added or changed should have the following
133
134* Specification for the method
135
136 * A description of what the method does suitable for use in
137 user documentation
138
139 * Method type (POST/PUT/GET/DELETE)
140
141 * Normal http response code(s)
142
143 * Expected error http response code(s)
144
145 * A description for each possible error code should be included
146 describing semantic errors which can cause it such as
147 inconsistent parameters supplied to the method, or when an
148 instance is not in an appropriate state for the request to
149 succeed. Errors caused by syntactic problems covered by the JSON
150 schema definition do not need to be included.
151
152 * URL for the resource
153
154 * URL should not include underscores, and use hyphens instead.
155
156 * Parameters which can be passed via the url
157
158 * JSON schema definition for the request body data if allowed
159
160 * Field names should use snake_case style, not CamelCase or MixedCase
161 style.
162
163 * JSON schema definition for the response body data if any
164
165 * Field names should use snake_case style, not CamelCase or MixedCase
166 style.
167
168* Example use case including typical API samples for both data supplied
169 by the caller and the response
170
171* Discuss any policy changes, and discuss what things a deployer needs to
172 think about when defining their policy.
173
174Note that the schema should be defined as restrictively as
175possible. Parameters which are required should be marked as such and
176only under exceptional circumstances should additional parameters
177which are not defined in the schema be permitted (eg
178additionaProperties should be False).
179
180Reuse of existing predefined parameter types such as regexps for
181passwords and user defined names is highly encouraged.
182
183Security impact
184---------------
185
186Describe any potential security impact on the system. Some of the items to
187consider include:
188
189* Does this change touch sensitive data such as tokens, keys, or user data?
190
191* Does this change alter the API in a way that may impact security, such as
192 a new way to access sensitive information or a new way to login?
193
194* Does this change involve cryptography or hashing?
195
196* Does this change require the use of sudo or any elevated privileges?
197
198* Does this change involve using or parsing user-provided data? This could
199 be directly at the API level or indirectly such as changes to a cache layer.
200
201* Can this change enable a resource exhaustion attack, such as allowing a
202 single API interaction to consume significant server resources? Some examples
203 of this include launching subprocesses for each connection, or entity
204 expansion attacks in XML.
205
206For more detailed guidance, please see the OpenStack Security Guidelines as
207a reference (https://wiki.openstack.org/wiki/Security/Guidelines). These
208guidelines are a work in progress and are designed to help you identify
209security best practices. For further information, feel free to reach out
210to the OpenStack Security Group at openstack-security@lists.openstack.org.
211
212Notifications impact
213--------------------
214
215Please specify any changes to notifications. Be that an extra notification,
216changes to an existing notification, or removing a notification.
217
218Other end user impact
219---------------------
220
221Aside from the API, are there other ways a user will interact with this
222feature?
223
224* Does this change have an impact on python-masakariclient? What does the user
225 interface there look like?
226
227Performance Impact
228------------------
229
230Describe any potential performance impact on the system, for example
231how often will new code be called, and is there a major change to the calling
232pattern of existing code.
233
234Examples of things to consider here include:
235
236* A periodic task might look like a small addition but if it calls conductor or
237 another service the load is multiplied by the number of nodes in the system.
238
239* Scheduler filters get called once per host for every instance being created,
240 so any latency they introduce is linear with the size of the system.
241
242* A small change in a utility function or a commonly used decorator can have a
243 large impacts on performance.
244
245* Calls which result in a database queries (whether direct or via conductor)
246 can have a profound impact on performance when called in critical sections of
247 the code.
248
249* Will the change include any locking, and if so what considerations are there
250 on holding the lock?
251
252Other deployer impact
253---------------------
254
255Discuss things that will affect how you deploy and configure OpenStack
256that have not already been mentioned, such as:
257
258* What config options are being added? Should they be more generic than
259 proposed (for example a flag that other hypervisor drivers might want to
260 implement as well)? Are the default values ones which will work well in
261 real deployments?
262
263* Is this a change that takes immediate effect after its merged, or is it
264 something that has to be explicitly enabled?
265
266* If this change is a new binary, how would it be deployed?
267
268* Please state anything that those doing continuous deployment, or those
269 upgrading from the previous release, need to be aware of. Also describe
270 any plans to deprecate configuration values or features. For example, if we
271 change the directory name that instances are stored in, how do we handle
272 instance directories created before the change landed? Do we move them? Do
273 we have a special case in the code? Do we assume that the operator will
274 recreate all the instances in their cloud?
275
276Developer impact
277----------------
278
279Discuss things that will affect other developers working on OpenStack,
280such as:
281
282* If the blueprint proposes a change to the driver API, discussion of how
283 other hypervisors would implement the feature is required.
284
285
286Implementation
287==============
288
289Assignee(s)
290-----------
291
292Who is leading the writing of the code? Or is this a blueprint where you're
293throwing it out there to see who picks it up?
294
295If more than one person is working on the implementation, please designate the
296primary author and contact.
297
298Primary assignee:
299 <launchpad-id or None>
300
301Other contributors:
302 <launchpad-id or None>
303
304Work Items
305----------
306
307Work items or tasks -- break the feature up into the things that need to be
308done to implement it. Those parts might end up being done by different people,
309but we're mostly trying to understand the timeline for implementation.
310
311
312Dependencies
313============
314
315* Include specific references to specs and/or blueprints in Masakari,
316 or in other projects, that this one either depends on or is related to.
317
318* If this requires functionality of another project that is not currently used
319 by Masakari (such as nova, or masakari-monitors, python-masakariclient),
320 document that fact.
321
322* Does this feature require any new library dependencies or code otherwise not
323 included in OpenStack? Or does it depend on a specific version of library?
324
325
326Testing
327=======
328
329Please discuss the important scenarios needed to test here, as well as
330specific edge cases we should be ensuring work correctly. For each
331scenario please specify if this requires specialized hardware, a full
332openstack environment, or can be simulated inside the Masakari tree.
333
334Please discuss how the change will be tested. We especially want to know what
335tempest tests will be added. It is assumed that unit test coverage will be
336added so that doesn't need to be mentioned explicitly, but discussion of why
337you think unit tests are sufficient and we don't need to add more tempest
338tests would need to be included.
339
340Is this untestable in gate given current limitations (specific hardware /
341software configurations available)? If so, are there mitigation plans (3rd
342party testing, gate enhancements, etc).
343
344
345Documentation Impact
346====================
347
348Which audiences are affected most by this change, and which documentation
349titles on docs.openstack.org should be updated because of this change? Don't
350repeat details discussed above, but reference them here in the context of
351documentation for multiple audiences. For example, the Operations Guide targets
352cloud operators, and the End User Guide would need to be updated if the change
353offers a new feature available through the CLI or dashboard. If a config option
354changes or is deprecated, note here that the documentation needs to be updated
355to reflect this specification's change.
356
357References
358==========
359
360Please add any useful references here. You are not required to have any
361reference. Moreover, this specification should still make sense when your
362references are unavailable. Examples of what you could include are:
363
364* Links to mailing list or IRC discussions
365
366* Links to notes from a summit session
367
368* Links to relevant research, if appropriate
369
370* Related specifications as appropriate (e.g. if it's an EC2 thing, link the
371 EC2 docs)
372
373* Anything else you feel it is worthwhile to refer to
374
375
376History
377=======
378
379Optional section intended to be used each time the spec is updated to describe
380new design, API or any database schema updated. Useful to let reader understand
381what's happened along the time.
382
383.. list-table:: Revisions
384 :header-rows: 1
385
386 * - Release Name
387 - Description
388 * - Queens
389 - Introduced
diff --git a/specs/queens/approved/queens-template.rst b/specs/queens/approved/queens-template.rst
new file mode 100644
index 0000000..1ad6077
--- /dev/null
+++ b/specs/queens/approved/queens-template.rst
@@ -0,0 +1,389 @@
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==========================================
8Example Spec - The title of your blueprint
9==========================================
10
11Include the URL of your launchpad blueprint:
12
13https://blueprints.launchpad.net/masakari/+spec/example
14
15Introduction paragraph -- why are we doing anything? A single paragraph of
16prose that operators can understand. The title and this first paragraph
17should be used as the subject line and body of the commit message
18respectively.
19
20Some notes about the masakari-spec and blueprint process:
21
22* Not all blueprints need a spec. For more information see
23 https://wiki.openstack.org/wiki/Masakari-specs
24
25* The aim of this document is first to define the problem we need to solve,
26 and second agree the overall approach to solve that problem.
27
28* This is not intended to be extensive documentation for a new feature.
29 For example, there is no need to specify the exact configuration changes,
30 nor the exact details of any DB model changes. But you should still define
31 that such changes are required, and be clear on how that will affect
32 upgrades.
33
34* You should aim to get your spec approved before writing your code.
35 While you are free to write prototypes and code before getting your spec
36 approved, its possible that the outcome of the spec review process leads
37 you towards a fundamentally different solution than you first envisaged.
38
39* But, API changes are held to a much higher level of scrutiny.
40 As soon as an API change merges, we must assume it could be in production
41 somewhere, and as such, we then need to support that API change forever.
42 To avoid getting that wrong, we do want lots of details about API changes
43 upfront.
44
45Some notes about using this template:
46
47* Your spec should be in ReSTructured text, like this template.
48
49* Please wrap text at 79 columns.
50
51* The filename in the git repository should match the launchpad URL, for
52 example a URL of: https://blueprints.launchpad.net/masakari/+spec/awesome-thing
53 should be named awesome-thing.rst
54
55* Please do not delete any of the sections in this template. If you have
56 nothing to say for a whole section, just write: None
57
58* For help with syntax, see http://sphinx-doc.org/rest.html
59
60* To test out your formatting, build the docs using tox and see the generated
61 HTML file in doc/build/html/specs/<path_of_your_file>
62
63* If you would like to provide a diagram with your spec, ascii diagrams are
64 required. http://asciiflow.com/ is a very nice tool to assist with making
65 ascii diagrams. The reason for this is that the tool used to review specs is
66 based purely on plain text. Plain text will allow review to proceed without
67 having to look at additional files which can not be viewed in gerrit. It
68 will also allow inline feedback on the diagram itself.
69
70* If your specification proposes any changes to the Masakari REST API such
71 as changing parameters which can be returned or accepted, or even
72 the semantics of what happens when a client calls into the API, then
73 you should add the APIImpact flag to the commit message.
74
75Problem description
76===================
77
78A detailed description of the problem. What problem is this blueprint
79addressing?
80
81Use Cases
82---------
83
84What use cases does this address? What impact on actors does this change have?
85Ensure you are clear about the actors in each use case: Developer, End User,
86Deployer etc.
87
88Proposed change
89===============
90
91Here is where you cover the change you propose to make in detail. How do you
92propose to solve this problem?
93
94If this is one part of a larger effort make it clear where this piece ends. In
95other words, what's the scope of this effort?
96
97At this point, if you would like to just get feedback on if the problem and
98proposed change fit in Masakari, you can stop here and post this for
99review to get preliminary feedback. If so please say:
100Posting to get preliminary feedback on the scope of this spec.
101
102Alternatives
103------------
104
105What other ways could we do this thing? Why aren't we using those? This doesn't
106have to be a full literature review, but it should demonstrate that thought has
107been put into why the proposed solution is an appropriate one.
108
109Data model impact
110-----------------
111
112Changes which require modifications to the data model often have a wider impact
113on the system. The community often has strong opinions on how the data model
114should be evolved, from both a functional and performance perspective. It is
115therefore important to capture and gain agreement as early as possible on any
116proposed changes to the data model.
117
118Questions which need to be addressed by this section include:
119
120* What new data objects and/or database schema changes is this going to
121 require?
122
123* What database migrations will accompany this change.
124
125* How will the initial set of new data objects be generated, for example if you
126 need to take into account existing instances, or modify other existing data
127 describe how that will work.
128
129REST API impact
130---------------
131
132Each API method which is either added or changed should have the following
133
134* Specification for the method
135
136 * A description of what the method does suitable for use in
137 user documentation
138
139 * Method type (POST/PUT/GET/DELETE)
140
141 * Normal http response code(s)
142
143 * Expected error http response code(s)
144
145 * A description for each possible error code should be included
146 describing semantic errors which can cause it such as
147 inconsistent parameters supplied to the method, or when an
148 instance is not in an appropriate state for the request to
149 succeed. Errors caused by syntactic problems covered by the JSON
150 schema definition do not need to be included.
151
152 * URL for the resource
153
154 * URL should not include underscores, and use hyphens instead.
155
156 * Parameters which can be passed via the url
157
158 * JSON schema definition for the request body data if allowed
159
160 * Field names should use snake_case style, not CamelCase or MixedCase
161 style.
162
163 * JSON schema definition for the response body data if any
164
165 * Field names should use snake_case style, not CamelCase or MixedCase
166 style.
167
168* Example use case including typical API samples for both data supplied
169 by the caller and the response
170
171* Discuss any policy changes, and discuss what things a deployer needs to
172 think about when defining their policy.
173
174Note that the schema should be defined as restrictively as
175possible. Parameters which are required should be marked as such and
176only under exceptional circumstances should additional parameters
177which are not defined in the schema be permitted (eg
178additionaProperties should be False).
179
180Reuse of existing predefined parameter types such as regexps for
181passwords and user defined names is highly encouraged.
182
183Security impact
184---------------
185
186Describe any potential security impact on the system. Some of the items to
187consider include:
188
189* Does this change touch sensitive data such as tokens, keys, or user data?
190
191* Does this change alter the API in a way that may impact security, such as
192 a new way to access sensitive information or a new way to login?
193
194* Does this change involve cryptography or hashing?
195
196* Does this change require the use of sudo or any elevated privileges?
197
198* Does this change involve using or parsing user-provided data? This could
199 be directly at the API level or indirectly such as changes to a cache layer.
200
201* Can this change enable a resource exhaustion attack, such as allowing a
202 single API interaction to consume significant server resources? Some examples
203 of this include launching subprocesses for each connection, or entity
204 expansion attacks in XML.
205
206For more detailed guidance, please see the OpenStack Security Guidelines as
207a reference (https://wiki.openstack.org/wiki/Security/Guidelines). These
208guidelines are a work in progress and are designed to help you identify
209security best practices. For further information, feel free to reach out
210to the OpenStack Security Group at openstack-security@lists.openstack.org.
211
212Notifications impact
213--------------------
214
215Please specify any changes to notifications. Be that an extra notification,
216changes to an existing notification, or removing a notification.
217
218Other end user impact
219---------------------
220
221Aside from the API, are there other ways a user will interact with this
222feature?
223
224* Does this change have an impact on python-masakariclient? What does the user
225 interface there look like?
226
227Performance Impact
228------------------
229
230Describe any potential performance impact on the system, for example
231how often will new code be called, and is there a major change to the calling
232pattern of existing code.
233
234Examples of things to consider here include:
235
236* A periodic task might look like a small addition but if it calls conductor or
237 another service the load is multiplied by the number of nodes in the system.
238
239* Scheduler filters get called once per host for every instance being created,
240 so any latency they introduce is linear with the size of the system.
241
242* A small change in a utility function or a commonly used decorator can have a
243 large impacts on performance.
244
245* Calls which result in a database queries (whether direct or via conductor)
246 can have a profound impact on performance when called in critical sections of
247 the code.
248
249* Will the change include any locking, and if so what considerations are there
250 on holding the lock?
251
252Other deployer impact
253---------------------
254
255Discuss things that will affect how you deploy and configure OpenStack
256that have not already been mentioned, such as:
257
258* What config options are being added? Should they be more generic than
259 proposed (for example a flag that other hypervisor drivers might want to
260 implement as well)? Are the default values ones which will work well in
261 real deployments?
262
263* Is this a change that takes immediate effect after its merged, or is it
264 something that has to be explicitly enabled?
265
266* If this change is a new binary, how would it be deployed?
267
268* Please state anything that those doing continuous deployment, or those
269 upgrading from the previous release, need to be aware of. Also describe
270 any plans to deprecate configuration values or features. For example, if we
271 change the directory name that instances are stored in, how do we handle
272 instance directories created before the change landed? Do we move them? Do
273 we have a special case in the code? Do we assume that the operator will
274 recreate all the instances in their cloud?
275
276Developer impact
277----------------
278
279Discuss things that will affect other developers working on OpenStack,
280such as:
281
282* If the blueprint proposes a change to the driver API, discussion of how
283 other hypervisors would implement the feature is required.
284
285
286Implementation
287==============
288
289Assignee(s)
290-----------
291
292Who is leading the writing of the code? Or is this a blueprint where you're
293throwing it out there to see who picks it up?
294
295If more than one person is working on the implementation, please designate the
296primary author and contact.
297
298Primary assignee:
299 <launchpad-id or None>
300
301Other contributors:
302 <launchpad-id or None>
303
304Work Items
305----------
306
307Work items or tasks -- break the feature up into the things that need to be
308done to implement it. Those parts might end up being done by different people,
309but we're mostly trying to understand the timeline for implementation.
310
311
312Dependencies
313============
314
315* Include specific references to specs and/or blueprints in Masakari,
316 or in other projects, that this one either depends on or is related to.
317
318* If this requires functionality of another project that is not currently used
319 by Masakari (such as nova, or masakari-monitors, python-masakariclient),
320 document that fact.
321
322* Does this feature require any new library dependencies or code otherwise not
323 included in OpenStack? Or does it depend on a specific version of library?
324
325
326Testing
327=======
328
329Please discuss the important scenarios needed to test here, as well as
330specific edge cases we should be ensuring work correctly. For each
331scenario please specify if this requires specialized hardware, a full
332openstack environment, or can be simulated inside the Masakari tree.
333
334Please discuss how the change will be tested. We especially want to know what
335tempest tests will be added. It is assumed that unit test coverage will be
336added so that doesn't need to be mentioned explicitly, but discussion of why
337you think unit tests are sufficient and we don't need to add more tempest
338tests would need to be included.
339
340Is this untestable in gate given current limitations (specific hardware /
341software configurations available)? If so, are there mitigation plans (3rd
342party testing, gate enhancements, etc).
343
344
345Documentation Impact
346====================
347
348Which audiences are affected most by this change, and which documentation
349titles on docs.openstack.org should be updated because of this change? Don't
350repeat details discussed above, but reference them here in the context of
351documentation for multiple audiences. For example, the Operations Guide targets
352cloud operators, and the End User Guide would need to be updated if the change
353offers a new feature available through the CLI or dashboard. If a config option
354changes or is deprecated, note here that the documentation needs to be updated
355to reflect this specification's change.
356
357References
358==========
359
360Please add any useful references here. You are not required to have any
361reference. Moreover, this specification should still make sense when your
362references are unavailable. Examples of what you could include are:
363
364* Links to mailing list or IRC discussions
365
366* Links to notes from a summit session
367
368* Links to relevant research, if appropriate
369
370* Related specifications as appropriate (e.g. if it's an EC2 thing, link the
371 EC2 docs)
372
373* Anything else you feel it is worthwhile to refer to
374
375
376History
377=======
378
379Optional section intended to be used each time the spec is updated to describe
380new design, API or any database schema updated. Useful to let reader understand
381what's happened along the time.
382
383.. list-table:: Revisions
384 :header-rows: 1
385
386 * - Release Name
387 - Description
388 * - Queens
389 - Introduced
diff --git a/specs/queens/implemented/queens-template.rst b/specs/queens/implemented/queens-template.rst
new file mode 100644
index 0000000..1ad6077
--- /dev/null
+++ b/specs/queens/implemented/queens-template.rst
@@ -0,0 +1,389 @@
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==========================================
8Example Spec - The title of your blueprint
9==========================================
10
11Include the URL of your launchpad blueprint:
12
13https://blueprints.launchpad.net/masakari/+spec/example
14
15Introduction paragraph -- why are we doing anything? A single paragraph of
16prose that operators can understand. The title and this first paragraph
17should be used as the subject line and body of the commit message
18respectively.
19
20Some notes about the masakari-spec and blueprint process:
21
22* Not all blueprints need a spec. For more information see
23 https://wiki.openstack.org/wiki/Masakari-specs
24
25* The aim of this document is first to define the problem we need to solve,
26 and second agree the overall approach to solve that problem.
27
28* This is not intended to be extensive documentation for a new feature.
29 For example, there is no need to specify the exact configuration changes,
30 nor the exact details of any DB model changes. But you should still define
31 that such changes are required, and be clear on how that will affect
32 upgrades.
33
34* You should aim to get your spec approved before writing your code.
35 While you are free to write prototypes and code before getting your spec
36 approved, its possible that the outcome of the spec review process leads
37 you towards a fundamentally different solution than you first envisaged.
38
39* But, API changes are held to a much higher level of scrutiny.
40 As soon as an API change merges, we must assume it could be in production
41 somewhere, and as such, we then need to support that API change forever.
42 To avoid getting that wrong, we do want lots of details about API changes
43 upfront.
44
45Some notes about using this template:
46
47* Your spec should be in ReSTructured text, like this template.
48
49* Please wrap text at 79 columns.
50
51* The filename in the git repository should match the launchpad URL, for
52 example a URL of: https://blueprints.launchpad.net/masakari/+spec/awesome-thing
53 should be named awesome-thing.rst
54
55* Please do not delete any of the sections in this template. If you have
56 nothing to say for a whole section, just write: None
57
58* For help with syntax, see http://sphinx-doc.org/rest.html
59
60* To test out your formatting, build the docs using tox and see the generated
61 HTML file in doc/build/html/specs/<path_of_your_file>
62
63* If you would like to provide a diagram with your spec, ascii diagrams are
64 required. http://asciiflow.com/ is a very nice tool to assist with making
65 ascii diagrams. The reason for this is that the tool used to review specs is
66 based purely on plain text. Plain text will allow review to proceed without
67 having to look at additional files which can not be viewed in gerrit. It
68 will also allow inline feedback on the diagram itself.
69
70* If your specification proposes any changes to the Masakari REST API such
71 as changing parameters which can be returned or accepted, or even
72 the semantics of what happens when a client calls into the API, then
73 you should add the APIImpact flag to the commit message.
74
75Problem description
76===================
77
78A detailed description of the problem. What problem is this blueprint
79addressing?
80
81Use Cases
82---------
83
84What use cases does this address? What impact on actors does this change have?
85Ensure you are clear about the actors in each use case: Developer, End User,
86Deployer etc.
87
88Proposed change
89===============
90
91Here is where you cover the change you propose to make in detail. How do you
92propose to solve this problem?
93
94If this is one part of a larger effort make it clear where this piece ends. In
95other words, what's the scope of this effort?
96
97At this point, if you would like to just get feedback on if the problem and
98proposed change fit in Masakari, you can stop here and post this for
99review to get preliminary feedback. If so please say:
100Posting to get preliminary feedback on the scope of this spec.
101
102Alternatives
103------------
104
105What other ways could we do this thing? Why aren't we using those? This doesn't
106have to be a full literature review, but it should demonstrate that thought has
107been put into why the proposed solution is an appropriate one.
108
109Data model impact
110-----------------
111
112Changes which require modifications to the data model often have a wider impact
113on the system. The community often has strong opinions on how the data model
114should be evolved, from both a functional and performance perspective. It is
115therefore important to capture and gain agreement as early as possible on any
116proposed changes to the data model.
117
118Questions which need to be addressed by this section include:
119
120* What new data objects and/or database schema changes is this going to
121 require?
122
123* What database migrations will accompany this change.
124
125* How will the initial set of new data objects be generated, for example if you
126 need to take into account existing instances, or modify other existing data
127 describe how that will work.
128
129REST API impact
130---------------
131
132Each API method which is either added or changed should have the following
133
134* Specification for the method
135
136 * A description of what the method does suitable for use in
137 user documentation
138
139 * Method type (POST/PUT/GET/DELETE)
140
141 * Normal http response code(s)
142
143 * Expected error http response code(s)
144
145 * A description for each possible error code should be included
146 describing semantic errors which can cause it such as
147 inconsistent parameters supplied to the method, or when an
148 instance is not in an appropriate state for the request to
149 succeed. Errors caused by syntactic problems covered by the JSON
150 schema definition do not need to be included.
151
152 * URL for the resource
153
154 * URL should not include underscores, and use hyphens instead.
155
156 * Parameters which can be passed via the url
157
158 * JSON schema definition for the request body data if allowed
159
160 * Field names should use snake_case style, not CamelCase or MixedCase
161 style.
162
163 * JSON schema definition for the response body data if any
164
165 * Field names should use snake_case style, not CamelCase or MixedCase
166 style.
167
168* Example use case including typical API samples for both data supplied
169 by the caller and the response
170
171* Discuss any policy changes, and discuss what things a deployer needs to
172 think about when defining their policy.
173
174Note that the schema should be defined as restrictively as
175possible. Parameters which are required should be marked as such and
176only under exceptional circumstances should additional parameters
177which are not defined in the schema be permitted (eg
178additionaProperties should be False).
179
180Reuse of existing predefined parameter types such as regexps for
181passwords and user defined names is highly encouraged.
182
183Security impact
184---------------
185
186Describe any potential security impact on the system. Some of the items to
187consider include:
188
189* Does this change touch sensitive data such as tokens, keys, or user data?
190
191* Does this change alter the API in a way that may impact security, such as
192 a new way to access sensitive information or a new way to login?
193
194* Does this change involve cryptography or hashing?
195
196* Does this change require the use of sudo or any elevated privileges?
197
198* Does this change involve using or parsing user-provided data? This could
199 be directly at the API level or indirectly such as changes to a cache layer.
200
201* Can this change enable a resource exhaustion attack, such as allowing a
202 single API interaction to consume significant server resources? Some examples
203 of this include launching subprocesses for each connection, or entity
204 expansion attacks in XML.
205
206For more detailed guidance, please see the OpenStack Security Guidelines as
207a reference (https://wiki.openstack.org/wiki/Security/Guidelines). These
208guidelines are a work in progress and are designed to help you identify
209security best practices. For further information, feel free to reach out
210to the OpenStack Security Group at openstack-security@lists.openstack.org.
211
212Notifications impact
213--------------------
214
215Please specify any changes to notifications. Be that an extra notification,
216changes to an existing notification, or removing a notification.
217
218Other end user impact
219---------------------
220
221Aside from the API, are there other ways a user will interact with this
222feature?
223
224* Does this change have an impact on python-masakariclient? What does the user
225 interface there look like?
226
227Performance Impact
228------------------
229
230Describe any potential performance impact on the system, for example
231how often will new code be called, and is there a major change to the calling
232pattern of existing code.
233
234Examples of things to consider here include:
235
236* A periodic task might look like a small addition but if it calls conductor or
237 another service the load is multiplied by the number of nodes in the system.
238
239* Scheduler filters get called once per host for every instance being created,
240 so any latency they introduce is linear with the size of the system.
241
242* A small change in a utility function or a commonly used decorator can have a
243 large impacts on performance.
244
245* Calls which result in a database queries (whether direct or via conductor)
246 can have a profound impact on performance when called in critical sections of
247 the code.
248
249* Will the change include any locking, and if so what considerations are there
250 on holding the lock?
251
252Other deployer impact
253---------------------
254
255Discuss things that will affect how you deploy and configure OpenStack
256that have not already been mentioned, such as:
257
258* What config options are being added? Should they be more generic than
259 proposed (for example a flag that other hypervisor drivers might want to
260 implement as well)? Are the default values ones which will work well in
261 real deployments?
262
263* Is this a change that takes immediate effect after its merged, or is it
264 something that has to be explicitly enabled?
265
266* If this change is a new binary, how would it be deployed?
267
268* Please state anything that those doing continuous deployment, or those
269 upgrading from the previous release, need to be aware of. Also describe
270 any plans to deprecate configuration values or features. For example, if we
271 change the directory name that instances are stored in, how do we handle
272 instance directories created before the change landed? Do we move them? Do
273 we have a special case in the code? Do we assume that the operator will
274 recreate all the instances in their cloud?
275
276Developer impact
277----------------
278
279Discuss things that will affect other developers working on OpenStack,
280such as:
281
282* If the blueprint proposes a change to the driver API, discussion of how
283 other hypervisors would implement the feature is required.
284
285
286Implementation
287==============
288
289Assignee(s)
290-----------
291
292Who is leading the writing of the code? Or is this a blueprint where you're
293throwing it out there to see who picks it up?
294
295If more than one person is working on the implementation, please designate the
296primary author and contact.
297
298Primary assignee:
299 <launchpad-id or None>
300
301Other contributors:
302 <launchpad-id or None>
303
304Work Items
305----------
306
307Work items or tasks -- break the feature up into the things that need to be
308done to implement it. Those parts might end up being done by different people,
309but we're mostly trying to understand the timeline for implementation.
310
311
312Dependencies
313============
314
315* Include specific references to specs and/or blueprints in Masakari,
316 or in other projects, that this one either depends on or is related to.
317
318* If this requires functionality of another project that is not currently used
319 by Masakari (such as nova, or masakari-monitors, python-masakariclient),
320 document that fact.
321
322* Does this feature require any new library dependencies or code otherwise not
323 included in OpenStack? Or does it depend on a specific version of library?
324
325
326Testing
327=======
328
329Please discuss the important scenarios needed to test here, as well as
330specific edge cases we should be ensuring work correctly. For each
331scenario please specify if this requires specialized hardware, a full
332openstack environment, or can be simulated inside the Masakari tree.
333
334Please discuss how the change will be tested. We especially want to know what
335tempest tests will be added. It is assumed that unit test coverage will be
336added so that doesn't need to be mentioned explicitly, but discussion of why
337you think unit tests are sufficient and we don't need to add more tempest
338tests would need to be included.
339
340Is this untestable in gate given current limitations (specific hardware /
341software configurations available)? If so, are there mitigation plans (3rd
342party testing, gate enhancements, etc).
343
344
345Documentation Impact
346====================
347
348Which audiences are affected most by this change, and which documentation
349titles on docs.openstack.org should be updated because of this change? Don't
350repeat details discussed above, but reference them here in the context of
351documentation for multiple audiences. For example, the Operations Guide targets
352cloud operators, and the End User Guide would need to be updated if the change
353offers a new feature available through the CLI or dashboard. If a config option
354changes or is deprecated, note here that the documentation needs to be updated
355to reflect this specification's change.
356
357References
358==========
359
360Please add any useful references here. You are not required to have any
361reference. Moreover, this specification should still make sense when your
362references are unavailable. Examples of what you could include are:
363
364* Links to mailing list or IRC discussions
365
366* Links to notes from a summit session
367
368* Links to relevant research, if appropriate
369
370* Related specifications as appropriate (e.g. if it's an EC2 thing, link the
371 EC2 docs)
372
373* Anything else you feel it is worthwhile to refer to
374
375
376History
377=======
378
379Optional section intended to be used each time the spec is updated to describe
380new design, API or any database schema updated. Useful to let reader understand
381what's happened along the time.
382
383.. list-table:: Revisions
384 :header-rows: 1
385
386 * - Release Name
387 - Description
388 * - Queens
389 - Introduced
diff --git a/specs/queens/redirects b/specs/queens/redirects
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/specs/queens/redirects