summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZuul <zuul@review.openstack.org>2017-10-19 22:22:03 +0000
committerGerrit Code Review <review@openstack.org>2017-10-19 22:22:03 +0000
commit8e61136effa09cc736536ee272e8b24eff348b8f (patch)
tree45ea77f6203715adc51dc731e5c996de952948eb
parent489e4b1420af26f4d996674723348bb1a67405e9 (diff)
parent0579dec0b985ee42183d66b8b9265ae645f4c47d (diff)
Merge "Add project tags api-ref documentation and reno"13.0.0.0b1
-rw-r--r--api-ref/source/v3/index.rst9
-rw-r--r--api-ref/source/v3/parameters.yaml13
-rw-r--r--api-ref/source/v3/project-tags.inc339
-rw-r--r--api-ref/source/v3/projects.inc1
-rw-r--r--api-ref/source/v3/samples/admin/project-create-response.json3
-rw-r--r--api-ref/source/v3/samples/admin/project-tags-list-response.json3
-rw-r--r--api-ref/source/v3/samples/admin/project-tags-update-request.json3
-rw-r--r--api-ref/source/v3/samples/admin/project-tags-update-response.json20
-rw-r--r--api-ref/source/v3/samples/admin/project-update-response.json3
-rw-r--r--api-ref/source/v3/samples/admin/projects-list-response.json24
-rw-r--r--releasenotes/notes/project-tags-1e72a6779d9d02c5.yaml18
11 files changed, 426 insertions, 10 deletions
diff --git a/api-ref/source/v3/index.rst b/api-ref/source/v3/index.rst
index 0d9e3a6..492a778 100644
--- a/api-ref/source/v3/index.rst
+++ b/api-ref/source/v3/index.rst
@@ -27,6 +27,13 @@ For information about Identity API protection, see
27in the OpenStack Cloud Administrator Guide. 27in the OpenStack Cloud Administrator Guide.
28 28
29========================= 29=========================
30What's New in Version 3.9
31=========================
32
33- Addition of ``tags`` attribute to project.
34- New APIs to interact with the ``tags`` attribute.
35
36=========================
30What's New in Version 3.8 37What's New in Version 3.8
31========================= 38=========================
32 39
@@ -177,6 +184,7 @@ This page lists the Identity API operations in the following order:
177* `Groups`_ 184* `Groups`_
178* `Policies`_ 185* `Policies`_
179* `Projects`_ 186* `Projects`_
187* `Project Tags`_
180* `Regions`_ 188* `Regions`_
181* `Roles`_ 189* `Roles`_
182* `Service catalog and endpoints`_ 190* `Service catalog and endpoints`_
@@ -195,6 +203,7 @@ This page lists the Identity API operations in the following order:
195.. include:: os-pki.inc 203.. include:: os-pki.inc
196.. include:: policies.inc 204.. include:: policies.inc
197.. include:: projects.inc 205.. include:: projects.inc
206.. include:: project-tags.inc
198.. include:: regions-v3.inc 207.. include:: regions-v3.inc
199.. include:: roles.inc 208.. include:: roles.inc
200.. include:: service-catalog.inc 209.. include:: service-catalog.inc
diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml
index 237a0f8..de26ba4 100644
--- a/api-ref/source/v3/parameters.yaml
+++ b/api-ref/source/v3/parameters.yaml
@@ -300,6 +300,13 @@ project_name_query:
300 in: query 300 in: query
301 required: false 301 required: false
302 type: string 302 type: string
303project_tag_query:
304 description: |
305 A simple string associated with a project. Can be used for assigning
306 values to projects and filtering based on those values.
307 in: query
308 required: true
309 type: string
303protocol_id_query: 310protocol_id_query:
304 description: | 311 description: |
305 Filters the response by a protocol ID. 312 Filters the response by a protocol ID.
@@ -1287,6 +1294,12 @@ regions_object:
1287 in: body 1294 in: body
1288 required: true 1295 required: true
1289 type: array 1296 type: array
1297response_body_project_tags_required:
1298 description: |
1299 A list of simple strings assigned to a project.
1300 in: body
1301 required: true
1302 type: array
1290role: 1303role:
1291 description: | 1304 description: |
1292 A ``role`` object, containing: 1305 A ``role`` object, containing:
diff --git a/api-ref/source/v3/project-tags.inc b/api-ref/source/v3/project-tags.inc
new file mode 100644
index 0000000..af8ff39
--- /dev/null
+++ b/api-ref/source/v3/project-tags.inc
@@ -0,0 +1,339 @@
1.. -*- rst -*-
2
3============
4Project tags
5============
6
7Projects within keystone can be tagged with one to many simple strings.
8Tags for projects follow the guidelines for resource tags set by the
9`API Working Group <https://specs.openstack.org/openstack/api-wg/guidelines/tags.html>`_.
10
11Tags for projects have the following restrictions:
12
13.. Note::
14
15 - Tags are case sensitive
16 - Forward Slash ‘/’ is not allowed to be in a tag name
17 - Commas ',' are not allowed to be in a tag name in order
18 to simplify requests that specify lists of tags
19 - Each project can have a maximum of 80 tags
20 - Each tag can be a maximum of 255 characters in length
21
22
23List tags for a project
24=======================
25
26.. rest_method:: GET /v3/projects/{project_id}/tags
27
28Lists all tags within a project.
29
30.. note::
31 HEAD can be used here as well
32
33Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
34
35Request Parameters
36------------------
37
38.. rest_parameters:: parameters.yaml
39
40 - project_id: project_id
41
42Response Parameters
43-------------------
44
45.. rest_parameters:: parameters.yaml
46
47 - tags: response_body_project_tags_required
48
49Status Codes
50------------
51
52.. rest_status_code:: success status.yaml
53
54 - 200
55
56.. rest_status_code:: error status.yaml
57
58 - 400
59 - 401
60 - 403
61 - 404
62
63Request Example
64---------------
65
66.. literalinclude:: ./samples/admin/project-tags-list-response.json
67 :language: javascript
68
69
70Check if project contains tag
71=============================
72
73.. rest_method:: GET /v3/projects/{project_id}/tags/{tag}
74
75Checks if a project contains the specified tag.
76
77.. note::
78 HEAD can be used here as well
79
80Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
81
82Request Parameters
83------------------
84
85.. rest_parameters:: parameters.yaml
86
87 - project_id: project_id
88 - tag: project_tag_query
89
90Status Codes
91------------
92
93.. rest_status_code:: success status.yaml
94
95 - 204
96
97.. rest_status_code:: error status.yaml
98
99 - 400
100 - 401
101 - 403
102 - 404
103
104
105Add single tag to a project
106===========================
107
108.. rest_method:: PUT /v3/projects/{project_id}/tags/{tag}
109
110Creates the specified tag and adds it to the list of tags in the project.
111
112Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
113
114Request Parameters
115------------------
116
117.. rest_parameters:: parameters.yaml
118
119 - project_id: project_id
120 - tag: project_tag_query
121
122Response Parameters
123-------------------
124
125.. rest_parameters:: parameters.yaml
126
127 - tags: response_body_project_tags_required
128
129Status Codes
130------------
131
132.. rest_status_code:: success status.yaml
133
134 - 201
135
136.. rest_status_code:: error status.yaml
137
138 - 400
139 - 401
140 - 403
141 - 404
142
143
144Modify tag list for a project
145=============================
146
147.. rest_method:: PUT /v3/projects/{project_id}/tags
148
149Modifies the tags for a project. Any existing tags not specified will
150be deleted.
151
152Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
153
154Request Parameters
155------------------
156
157.. rest_parameters:: parameters.yaml
158
159 - project_id: project_id
160 - tags: response_body_project_tags_required
161
162Response Parameters
163-------------------
164
165.. rest_parameters:: parameters.yaml
166
167 - tags: response_body_project_tags_required
168
169Status Codes
170~~~~~~~~~~~~
171
172.. rest_status_code:: success status.yaml
173
174 - 200
175
176.. rest_status_code:: error status.yaml
177
178 - 400
179 - 401
180 - 403
181 - 404
182
183Request Example
184---------------
185
186.. literalinclude:: ./samples/admin/project-tags-update-request.json
187 :language: javascript
188
189Response Example
190----------------
191
192.. literalinclude:: ./samples/admin/project-tags-update-response.json
193 :language: javascript
194
195
196Delete single tag from project
197==============================
198
199.. rest_method:: DELETE /v3/projects/{project_id}/tags/{tag}
200
201Remove a single tag from a project.
202
203Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
204
205Request Parameters
206------------------
207
208.. rest_parameters:: parameters.yaml
209
210 - project_id: project_id
211 - tag: project_tag_query
212
213Status Codes
214~~~~~~~~~~~~
215
216.. rest_status_code:: success status.yaml
217
218 - 204
219
220.. rest_status_code:: error status.yaml
221
222 - 400
223 - 401
224 - 403
225 - 404
226
227
228Remove all tags from a project
229==============================
230
231.. rest_method:: DELETE /v3/projects/{project_id}/tags
232
233Remove all tags from a given project.
234
235Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
236
237Request Parameters
238------------------
239
240.. rest_parameters:: parameters.yaml
241
242 - project_id: project_id
243
244Status Codes
245~~~~~~~~~~~~
246
247.. rest_status_code:: success status.yaml
248
249 - 204
250
251.. rest_status_code:: error status.yaml
252
253 - 400
254 - 401
255 - 403
256 - 404
257
258
259===============================
260Filtering and searching by tags
261===============================
262
263Projects can be searched or filtered by tags. The following table and examples
264define how to filter projects by tags. Filters can also be combined for more
265complex searching.
266
267.. list-table::
268 :widths: 100 250
269 :header-rows: 1
270
271 * - Tag Query
272 - Description
273 * - tags
274 - Projects that contain all of the specified tags
275 * - tags-any
276 - Projects that contain at least one of the specified tags
277 * - not-tags
278 - Projects that do not contain exactly all of the specified tags
279 * - not-tags-any
280 - Projects that do not contain any one of the specified tags
281
282
283To request the list of projects that have a single tag, the ``tags`` query
284parameter should be set to the desired tag name. The following example returns
285projects with the "foo" tag:
286
287.. code-block:: bash
288
289 GET /v3/projects?tags=foo
290
291To request the list of projects that have two or more tags, the ``tags``
292argument should be set to the list of tags, separated by commas. In this
293situation, the tags given must all be present for a project to be included
294in the query result. The following example returns projects that have the
295"foo" and "bar" tags:
296
297.. code-block:: bash
298
299 GET /v3/projects?tags=foo,bar
300
301To request the list of projects that have at least one tag from a given list,
302the ``tags-any`` argument should be set to the list of tags, separated
303by commas. In this situation as long as one of the given tags is present,
304the project will be included in the query result. The following example returns
305projects that have the “foo” OR “bar” tag:
306
307.. code-block:: bash
308
309 GET /v3/projects?tags-any=foo,bar
310
311To request the list of projects that do not have a list of tags, the
312``not-tags`` argument should be set to the list of tags, separated by commas.
313In this situation, the tags given must all be absent for a project to be
314included in the query result. The following example returns projects that
315do not have the “foo” nor the “bar” tag:
316
317.. code-block:: bash
318
319 GET /v3/projects?not-tags=foo,bar
320
321To request the list of projects that do not have at least one of a list of
322tags, the ``not-tags-any`` argument should be set to the list of tags,
323separated by commas. In this situation, as long as one of the given tags
324is absent, the project will be included in the query result. Example
325The following example returns projects that do not have the “foo” tag or
326do not have the “bar” tag:
327
328.. code-block:: bash
329
330 GET /v3/projects?not-tags-any=foo,bar
331
332The ``tags``, ``tags-any``, ``not-tags`` and ``not-tags-any`` arguments can
333be combined to build more complex queries. The following example returns
334projects that have the “foo” and “bar” tags, plus at least one of “red”
335and “blue”:
336
337.. code-block:: bash
338
339 GET /v3/projects?tags=foo,bar&tags-any=red,blue
diff --git a/api-ref/source/v3/projects.inc b/api-ref/source/v3/projects.inc
index 912731c..6ac35f0 100644
--- a/api-ref/source/v3/projects.inc
+++ b/api-ref/source/v3/projects.inc
@@ -86,6 +86,7 @@ Response Parameters
86 - links: link_response_body 86 - links: link_response_body
87 - name: project_name_response_body 87 - name: project_name_response_body
88 - parent_id: project_parent_id_response_body 88 - parent_id: project_parent_id_response_body
89 - tags: response_body_project_tags_required
89 90
90Response Example 91Response Example
91---------------- 92----------------
diff --git a/api-ref/source/v3/samples/admin/project-create-response.json b/api-ref/source/v3/samples/admin/project-create-response.json
index 42c41d6..9c7dbe3 100644
--- a/api-ref/source/v3/samples/admin/project-create-response.json
+++ b/api-ref/source/v3/samples/admin/project-create-response.json
@@ -9,6 +9,7 @@
9 "self": "http://example.com/identity/v3/projects/93ebbcc35335488b96ff9cd7d18cbb2e" 9 "self": "http://example.com/identity/v3/projects/93ebbcc35335488b96ff9cd7d18cbb2e"
10 }, 10 },
11 "name": "myNewProject", 11 "name": "myNewProject",
12 "parent_id": "default" 12 "parent_id": "default",
13 "tags": []
13 } 14 }
14} 15}
diff --git a/api-ref/source/v3/samples/admin/project-tags-list-response.json b/api-ref/source/v3/samples/admin/project-tags-list-response.json
new file mode 100644
index 0000000..887054a
--- /dev/null
+++ b/api-ref/source/v3/samples/admin/project-tags-list-response.json
@@ -0,0 +1,3 @@
1{
2 "tags": ["foo", "bar"]
3}
diff --git a/api-ref/source/v3/samples/admin/project-tags-update-request.json b/api-ref/source/v3/samples/admin/project-tags-update-request.json
new file mode 100644
index 0000000..887054a
--- /dev/null
+++ b/api-ref/source/v3/samples/admin/project-tags-update-request.json
@@ -0,0 +1,3 @@
1{
2 "tags": ["foo", "bar"]
3}
diff --git a/api-ref/source/v3/samples/admin/project-tags-update-response.json b/api-ref/source/v3/samples/admin/project-tags-update-response.json
new file mode 100644
index 0000000..ae65d6d
--- /dev/null
+++ b/api-ref/source/v3/samples/admin/project-tags-update-response.json
@@ -0,0 +1,20 @@
1{
2 "links": {
3 "next": null,
4 "previous": null,
5 "self": "http://identity:5000/v3/projects"
6 },
7 "projects": [
8 {
9 "description": "Test Project",
10 "domain_id": "default",
11 "enabled": true,
12 "id": "3d4c2c82bd5948f0bcab0cf3a7c9b48c",
13 "links": {
14 "self": "http://identity:5000/v3/projects/3d4c2c82bd5948f0bcab0cf3a7c9b48c"
15 },
16 "name": "demo",
17 "tags": ["foo", "bar"]
18 }
19 ]
20}
diff --git a/api-ref/source/v3/samples/admin/project-update-response.json b/api-ref/source/v3/samples/admin/project-update-response.json
index 42c0ee2..31a943a 100644
--- a/api-ref/source/v3/samples/admin/project-update-response.json
+++ b/api-ref/source/v3/samples/admin/project-update-response.json
@@ -9,6 +9,7 @@
9 "id": "93ebbcc35335488b96ff9cd7d18cbb2e", 9 "id": "93ebbcc35335488b96ff9cd7d18cbb2e",
10 "is_domain": true, 10 "is_domain": true,
11 "name": "myUpdatedProject", 11 "name": "myUpdatedProject",
12 "parent_id": null 12 "parent_id": null,
13 "tags": []
13 } 14 }
14} 15}
diff --git a/api-ref/source/v3/samples/admin/projects-list-response.json b/api-ref/source/v3/samples/admin/projects-list-response.json
index 2c12119..6bb96e3 100644
--- a/api-ref/source/v3/samples/admin/projects-list-response.json
+++ b/api-ref/source/v3/samples/admin/projects-list-response.json
@@ -15,7 +15,8 @@
15 "self": "http://example.com/identity/v3/projects/0c4e939acacf4376bdcd1129f1a054ad" 15 "self": "http://example.com/identity/v3/projects/0c4e939acacf4376bdcd1129f1a054ad"
16 }, 16 },
17 "name": "admin", 17 "name": "admin",
18 "parent_id": null 18 "parent_id": null,
19 "tags": []
19 }, 20 },
20 { 21 {
21 "is_domain": false, 22 "is_domain": false,
@@ -27,7 +28,8 @@
27 "self": "http://example.com/identity/v3/projects/0cbd49cbf76d405d9c86562e1d579bd3" 28 "self": "http://example.com/identity/v3/projects/0cbd49cbf76d405d9c86562e1d579bd3"
28 }, 29 },
29 "name": "demo", 30 "name": "demo",
30 "parent_id": null 31 "parent_id": null,
32 "tags": []
31 }, 33 },
32 { 34 {
33 "is_domain": false, 35 "is_domain": false,
@@ -39,7 +41,8 @@
39 "self": "http://example.com/identity/v3/projects/2db68fed84324f29bb73130c6c2094fb" 41 "self": "http://example.com/identity/v3/projects/2db68fed84324f29bb73130c6c2094fb"
40 }, 42 },
41 "name": "swifttenanttest2", 43 "name": "swifttenanttest2",
42 "parent_id": null 44 "parent_id": null,
45 "tags": []
43 }, 46 },
44 { 47 {
45 "is_domain": false, 48 "is_domain": false,
@@ -51,7 +54,8 @@
51 "self": "http://example.com/identity/v3/projects/3d594eb0f04741069dbbb521635b21c7" 54 "self": "http://example.com/identity/v3/projects/3d594eb0f04741069dbbb521635b21c7"
52 }, 55 },
53 "name": "service", 56 "name": "service",
54 "parent_id": null 57 "parent_id": null,
58 "tags": []
55 }, 59 },
56 { 60 {
57 "is_domain": false, 61 "is_domain": false,
@@ -63,7 +67,8 @@
63 "self": "http://example.com/identity/v3/projects/43ebde53fc314b1c9ea2b8c5dc744927" 67 "self": "http://example.com/identity/v3/projects/43ebde53fc314b1c9ea2b8c5dc744927"
64 }, 68 },
65 "name": "swifttenanttest1", 69 "name": "swifttenanttest1",
66 "parent_id": null 70 "parent_id": null,
71 "tags": []
67 }, 72 },
68 { 73 {
69 "is_domain": false, 74 "is_domain": false,
@@ -75,7 +80,8 @@
75 "self": "http://example.com/identity/v3/projects/4b1eb781a47440acb8af9850103e537f" 80 "self": "http://example.com/identity/v3/projects/4b1eb781a47440acb8af9850103e537f"
76 }, 81 },
77 "name": "swifttenanttest4", 82 "name": "swifttenanttest4",
78 "parent_id": null 83 "parent_id": null,
84 "tags": []
79 }, 85 },
80 { 86 {
81 "is_domain": false, 87 "is_domain": false,
@@ -87,7 +93,8 @@
87 "self": "http://example.com/identity/v3/projects/5961c443439d4fcebe42643723755e9d" 93 "self": "http://example.com/identity/v3/projects/5961c443439d4fcebe42643723755e9d"
88 }, 94 },
89 "name": "invisible_to_admin", 95 "name": "invisible_to_admin",
90 "parent_id": null 96 "parent_id": null,
97 "tags": []
91 }, 98 },
92 { 99 {
93 "is_domain": false, 100 "is_domain": false,
@@ -99,7 +106,8 @@
99 "self": "http://example.com/identity/v3/projects/fdb8424c4e4f4c0ba32c52e2de3bd80e" 106 "self": "http://example.com/identity/v3/projects/fdb8424c4e4f4c0ba32c52e2de3bd80e"
100 }, 107 },
101 "name": "alt_demo", 108 "name": "alt_demo",
102 "parent_id": null 109 "parent_id": null,
110 "tags": []
103 } 111 }
104 ] 112 ]
105} 113}
diff --git a/releasenotes/notes/project-tags-1e72a6779d9d02c5.yaml b/releasenotes/notes/project-tags-1e72a6779d9d02c5.yaml
new file mode 100644
index 0000000..b0b4dad
--- /dev/null
+++ b/releasenotes/notes/project-tags-1e72a6779d9d02c5.yaml
@@ -0,0 +1,18 @@
1---
2features:
3 - |
4 [`blueprint project-tags <https://blueprints.launchpad.net/keystone/+spec/project-tags>`_]
5 Projects have a new property called tags. These tags
6 are simple strings that can be used to allow projects
7 to be filtered/searched. Project tags will have the
8 following properties:
9
10 * Tags are case sensitive
11 * '/' and ',' are not allowed to be in a tag
12 * Each project can have up to 100 tags
13 * Each tag can be up to 255 characters
14
15 See `Project Tags <https://developer.openstack.org/api-ref/identity/v3/#project-tags>`_
16
17 Project tags are implemented following the guidelines
18 set by the `API Working Group <https://specs.openstack.org/openstack/api-wg/guidelines/tags.html>`_