keystone  18.0.0
About: OpenStack Keystone (Core Service: Identity) provides an authentication and authorization service for other OpenStack services. Provides a catalog of endpoints for all OpenStack services.
The "Victoria" series (maintained release).
  Fossies Dox: keystone-18.0.0.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

project-tags.inc
Go to the documentation of this file.
1 .. -*- rst -*-
2 
3 ============
4 Project tags
5 ============
6 
7 Projects within keystone can be tagged with one to many simple strings.
8 Tags 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 
11 Tags 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 .. warning::
23 
24  We discourage the use of project tags for sensitive information like billing or
25  account codes. By default, access to project tags isn't exclusive to system
26  administrators or users. Domain and project administrators are allowed to
27  tag projects they have authorization to access. Domain and project users
28  (e.g., users with the ``member`` or ``reader`` roles) can view all project
29  tags on all projects within their domain or on projects they are
30  authorized to access.
31 
32 
33 List tags for a project
34 =======================
35 
36 .. rest_method:: GET /v3/projects/{project_id}/tags
37 
38 Lists all tags within a project.
39 
40 .. note::
41  HEAD can be used here as well
42 
43 Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
44 
45 Request
46 -------
47 
48 Parameters
49 ~~~~~~~~~~
50 
51 .. rest_parameters:: parameters.yaml
52 
53  - project_id: project_id_path
54 
55 Response
56 --------
57 
58 Parameters
59 ~~~~~~~~~~
60 
61 .. rest_parameters:: parameters.yaml
62 
63  - tags: response_body_project_tags_required
64 
65 Status Codes
66 ~~~~~~~~~~~~
67 
68 .. rest_status_code:: success status.yaml
69 
70  - 200
71 
72 .. rest_status_code:: error status.yaml
73 
74  - 400
75  - 401
76  - 403
77  - 404
78 
79 Example
80 ~~~~~~~
81 
82 .. literalinclude:: ./samples/admin/project-tags-list-response.json
83  :language: javascript
84 
85 
86 Modify tag list for a project
87 =============================
88 
89 .. rest_method:: PUT /v3/projects/{project_id}/tags
90 
91 Modifies the tags for a project. Any existing tags not specified will
92 be deleted.
93 
94 Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
95 
96 Request
97 -------
98 
99 Parameters
100 ~~~~~~~~~~
101 
102 .. rest_parameters:: parameters.yaml
103 
104  - project_id: project_id_path
105  - tags: response_body_project_tags_required
106 
107 Example
108 ~~~~~~~
109 
110 .. literalinclude:: ./samples/admin/project-tags-update-request.json
111  :language: javascript
112 
113 Response
114 --------
115 
116 Parameters
117 ~~~~~~~~~~
118 
119 .. rest_parameters:: parameters.yaml
120 
121  - tags: response_body_project_tags_required
122 
123 Status Codes
124 ~~~~~~~~~~~~
125 
126 .. rest_status_code:: success status.yaml
127 
128  - 200
129 
130 .. rest_status_code:: error status.yaml
131 
132  - 400
133  - 401
134  - 403
135  - 404
136 
137 Example
138 ~~~~~~~
139 
140 .. literalinclude:: ./samples/admin/project-tags-update-response.json
141  :language: javascript
142 
143 
144 Remove all tags from a project
145 ==============================
146 
147 .. rest_method:: DELETE /v3/projects/{project_id}/tags
148 
149 Remove all tags from a given project.
150 
151 Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
152 
153 Request
154 -------
155 
156 Parameters
157 ~~~~~~~~~~
158 
159 .. rest_parameters:: parameters.yaml
160 
161  - project_id: project_id_path
162 
163 Response
164 --------
165 
166 Status Codes
167 ~~~~~~~~~~~~
168 
169 .. rest_status_code:: success status.yaml
170 
171  - 204
172 
173 .. rest_status_code:: error status.yaml
174 
175  - 400
176  - 401
177  - 403
178 
179 
180 Check if project contains tag
181 =============================
182 
183 .. rest_method:: GET /v3/projects/{project_id}/tags/{tag}
184 
185 Checks if a project contains the specified tag.
186 
187 .. note::
188  HEAD can be used here as well
189 
190 Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
191 
192 Request
193 -------
194 
195 Parameters
196 ~~~~~~~~~~
197 
198 .. rest_parameters:: parameters.yaml
199 
200  - project_id: project_id_path
201  - tag: project_tag_path
202 
203 Response
204 --------
205 
206 Status Codes
207 ~~~~~~~~~~~~
208 
209 .. rest_status_code:: success status.yaml
210 
211  - 204
212 
213 .. rest_status_code:: error status.yaml
214 
215  - 400
216  - 401
217  - 403
218  - 404
219 
220 
221 Add single tag to a project
222 ===========================
223 
224 .. rest_method:: PUT /v3/projects/{project_id}/tags/{tag}
225 
226 Creates the specified tag and adds it to the list of tags in the project.
227 
228 Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
229 
230 Request
231 -------
232 
233 Parameters
234 ~~~~~~~~~~
235 
236 .. rest_parameters:: parameters.yaml
237 
238  - project_id: project_id_path
239  - tag: project_tag_path
240 
241 Response
242 --------
243 
244 Status Codes
245 ~~~~~~~~~~~~
246 
247 .. rest_status_code:: success status.yaml
248 
249  - 201
250 
251 .. rest_status_code:: error status.yaml
252 
253  - 400
254  - 401
255  - 403
256  - 404
257 
258 
259 Delete single tag from project
260 ==============================
261 
262 .. rest_method:: DELETE /v3/projects/{project_id}/tags/{tag}
263 
264 Remove a single tag from a project.
265 
266 Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
267 
268 Request
269 -------
270 
271 Parameters
272 ~~~~~~~~~~
273 
274 .. rest_parameters:: parameters.yaml
275 
276  - project_id: project_id_path
277  - tag: project_tag_path
278 
279 Response
280 --------
281 
282 Status Codes
283 ~~~~~~~~~~~~
284 
285 .. rest_status_code:: success status.yaml
286 
287  - 204
288 
289 .. rest_status_code:: error status.yaml
290 
291  - 400
292  - 401
293  - 403
294  - 404
295 
296 
297 ===============================
298 Filtering and searching by tags
299 ===============================
300 
301 Projects can be searched or filtered by tags. The following table and examples
302 define how to filter projects by tags. Filters can also be combined for more
303 complex searching.
304 
305 .. list-table::
306  :widths: 100 250
307  :header-rows: 1
308 
309  * - Tag Query
310  - Description
311  * - tags
312  - Projects that contain all of the specified tags
313  * - tags-any
314  - Projects that contain at least one of the specified tags
315  * - not-tags
316  - Projects that do not contain exactly all of the specified tags
317  * - not-tags-any
318  - Projects that do not contain any one of the specified tags
319 
320 
321 To request the list of projects that have a single tag, the ``tags`` query
322 parameter should be set to the desired tag name. The following example returns
323 projects with the "foo" tag:
324 
325 .. code-block:: bash
326 
327  GET /v3/projects?tags=foo
328 
329 To request the list of projects that have two or more tags, the ``tags``
330 argument should be set to the list of tags, separated by commas. In this
331 situation, the tags given must all be present for a project to be included
332 in the query result. The following example returns projects that have the
333 "foo" and "bar" tags:
334 
335 .. code-block:: bash
336 
337  GET /v3/projects?tags=foo,bar
338 
339 To request the list of projects that have at least one tag from a given list,
340 the ``tags-any`` argument should be set to the list of tags, separated
341 by commas. In this situation as long as one of the given tags is present,
342 the project will be included in the query result. The following example returns
343 projects that have the “foo” OR “bar” tag:
344 
345 .. code-block:: bash
346 
347  GET /v3/projects?tags-any=foo,bar
348 
349 To request the list of projects that do not have a list of tags, the
350 ``not-tags`` argument should be set to the list of tags, separated by commas.
351 In this situation, the tags given must all be absent for a project to be
352 included in the query result. The following example returns projects that
353 do not have the “foo” nor the “bar” tag:
354 
355 .. code-block:: bash
356 
357  GET /v3/projects?not-tags=foo,bar
358 
359 To request the list of projects that do not have at least one of a list of
360 tags, the ``not-tags-any`` argument should be set to the list of tags,
361 separated by commas. In this situation, as long as one of the given tags
362 is absent, the project will be included in the query result. Example
363 The following example returns projects that do not have the “foo” tag or
364 do not have the “bar” tag:
365 
366 .. code-block:: bash
367 
368  GET /v3/projects?not-tags-any=foo,bar
369 
370 The ``tags``, ``tags-any``, ``not-tags`` and ``not-tags-any`` arguments can
371 be combined to build more complex queries. The following example returns
372 projects that have the “foo” and “bar” tags, plus at least one of “red”
373 and “blue”:
374 
375 .. code-block:: bash
376 
377  GET /v3/projects?tags=foo,bar&tags-any=red,blue
keystone
Definition: __init__.py:1
conf.project
string project
Definition: conf.py:57
keystone.common.validation.parameter_types.name
dictionary name
Definition: parameter_types.py:25