378 lines
7.9 KiB
ReStructuredText
378 lines
7.9 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
============
|
|
Project tags
|
|
============
|
|
|
|
Projects within keystone can be tagged with one to many simple strings.
|
|
Tags for projects follow the guidelines for resource tags set by the
|
|
`API Working Group <https://specs.openstack.org/openstack/api-wg/guidelines/tags.html>`_.
|
|
|
|
Tags for projects have the following restrictions:
|
|
|
|
.. Note::
|
|
|
|
- Tags are case sensitive
|
|
- Forward Slash '/' is not allowed to be in a tag name
|
|
- Commas ',' are not allowed to be in a tag name in order
|
|
to simplify requests that specify lists of tags
|
|
- Each project can have a maximum of 80 tags
|
|
- Each tag can be a maximum of 255 characters in length
|
|
|
|
.. warning::
|
|
|
|
We discourage the use of project tags for sensitive information like billing or
|
|
account codes. By default, access to project tags isn't exclusive to system
|
|
administrators or users. Domain and project administrators are allowed to
|
|
tag projects they have authorization to access. Domain and project users
|
|
(e.g., users with the ``member`` or ``reader`` roles) can view all project
|
|
tags on all projects within their domain or on projects they are
|
|
authorized to access.
|
|
|
|
|
|
List tags for a project
|
|
=======================
|
|
|
|
.. rest_method:: GET /v3/projects/{project_id}/tags
|
|
|
|
Lists all tags within a project.
|
|
|
|
.. note::
|
|
HEAD can be used here as well
|
|
|
|
Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
|
|
|
|
Request
|
|
-------
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project_id: project_id_path
|
|
|
|
Response
|
|
--------
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tags: response_body_project_tags_required
|
|
|
|
Status Codes
|
|
~~~~~~~~~~~~
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 200
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 403
|
|
- 404
|
|
|
|
Example
|
|
~~~~~~~
|
|
|
|
.. literalinclude:: ./samples/admin/project-tags-list-response.json
|
|
:language: javascript
|
|
|
|
|
|
Modify tag list for a project
|
|
=============================
|
|
|
|
.. rest_method:: PUT /v3/projects/{project_id}/tags
|
|
|
|
Modifies the tags for a project. Any existing tags not specified will
|
|
be deleted.
|
|
|
|
Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
|
|
|
|
Request
|
|
-------
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project_id: project_id_path
|
|
- tags: response_body_project_tags_required
|
|
|
|
Example
|
|
~~~~~~~
|
|
|
|
.. literalinclude:: ./samples/admin/project-tags-update-request.json
|
|
:language: javascript
|
|
|
|
Response
|
|
--------
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tags: response_body_project_tags_required
|
|
|
|
Status Codes
|
|
~~~~~~~~~~~~
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 200
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 403
|
|
- 404
|
|
|
|
Example
|
|
~~~~~~~
|
|
|
|
.. literalinclude:: ./samples/admin/project-tags-update-response.json
|
|
:language: javascript
|
|
|
|
|
|
Remove all tags from a project
|
|
==============================
|
|
|
|
.. rest_method:: DELETE /v3/projects/{project_id}/tags
|
|
|
|
Remove all tags from a given project.
|
|
|
|
Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
|
|
|
|
Request
|
|
-------
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project_id: project_id_path
|
|
|
|
Response
|
|
--------
|
|
|
|
Status Codes
|
|
~~~~~~~~~~~~
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 204
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 403
|
|
|
|
|
|
Check if project contains tag
|
|
=============================
|
|
|
|
.. rest_method:: GET /v3/projects/{project_id}/tags/{tag}
|
|
|
|
Checks if a project contains the specified tag.
|
|
|
|
.. note::
|
|
HEAD can be used here as well
|
|
|
|
Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
|
|
|
|
Request
|
|
-------
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project_id: project_id_path
|
|
- tag: project_tag_path
|
|
|
|
Response
|
|
--------
|
|
|
|
Status Codes
|
|
~~~~~~~~~~~~
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 204
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 403
|
|
- 404
|
|
|
|
|
|
Add single tag to a project
|
|
===========================
|
|
|
|
.. rest_method:: PUT /v3/projects/{project_id}/tags/{tag}
|
|
|
|
Creates the specified tag and adds it to the list of tags in the project.
|
|
|
|
Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
|
|
|
|
Request
|
|
-------
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project_id: project_id_path
|
|
- tag: project_tag_path
|
|
|
|
Response
|
|
--------
|
|
|
|
Status Codes
|
|
~~~~~~~~~~~~
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 201
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 403
|
|
- 404
|
|
|
|
|
|
Delete single tag from project
|
|
==============================
|
|
|
|
.. rest_method:: DELETE /v3/projects/{project_id}/tags/{tag}
|
|
|
|
Remove a single tag from a project.
|
|
|
|
Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/projects``
|
|
|
|
Request
|
|
-------
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project_id: project_id_path
|
|
- tag: project_tag_path
|
|
|
|
Response
|
|
--------
|
|
|
|
Status Codes
|
|
~~~~~~~~~~~~
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 204
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 403
|
|
- 404
|
|
|
|
|
|
===============================
|
|
Filtering and searching by tags
|
|
===============================
|
|
|
|
Projects can be searched or filtered by tags. The following table and examples
|
|
define how to filter projects by tags. Filters can also be combined for more
|
|
complex searching.
|
|
|
|
.. list-table::
|
|
:widths: 100 250
|
|
:header-rows: 1
|
|
|
|
* - Tag Query
|
|
- Description
|
|
* - tags
|
|
- Projects that contain all of the specified tags
|
|
* - tags-any
|
|
- Projects that contain at least one of the specified tags
|
|
* - not-tags
|
|
- Projects that do not contain exactly all of the specified tags
|
|
* - not-tags-any
|
|
- Projects that do not contain any one of the specified tags
|
|
|
|
|
|
To request the list of projects that have a single tag, the ``tags`` query
|
|
parameter should be set to the desired tag name. The following example returns
|
|
projects with the "foo" tag:
|
|
|
|
.. code-block:: bash
|
|
|
|
GET /v3/projects?tags=foo
|
|
|
|
To request the list of projects that have two or more tags, the ``tags``
|
|
argument should be set to the list of tags, separated by commas. In this
|
|
situation, the tags given must all be present for a project to be included
|
|
in the query result. The following example returns projects that have the
|
|
"foo" and "bar" tags:
|
|
|
|
.. code-block:: bash
|
|
|
|
GET /v3/projects?tags=foo,bar
|
|
|
|
To request the list of projects that have at least one tag from a given list,
|
|
the ``tags-any`` argument should be set to the list of tags, separated
|
|
by commas. In this situation as long as one of the given tags is present,
|
|
the project will be included in the query result. The following example returns
|
|
projects that have the “foo” OR “bar” tag:
|
|
|
|
.. code-block:: bash
|
|
|
|
GET /v3/projects?tags-any=foo,bar
|
|
|
|
To request the list of projects that do not have a list of tags, the
|
|
``not-tags`` argument should be set to the list of tags, separated by commas.
|
|
In this situation, the tags given must all be absent for a project to be
|
|
included in the query result. The following example returns projects that
|
|
do not have the “foo” nor the “bar” tag:
|
|
|
|
.. code-block:: bash
|
|
|
|
GET /v3/projects?not-tags=foo,bar
|
|
|
|
To request the list of projects that do not have at least one of a list of
|
|
tags, the ``not-tags-any`` argument should be set to the list of tags,
|
|
separated by commas. In this situation, as long as one of the given tags
|
|
is absent, the project will be included in the query result. Example
|
|
The following example returns projects that do not have the “foo” tag or
|
|
do not have the “bar” tag:
|
|
|
|
.. code-block:: bash
|
|
|
|
GET /v3/projects?not-tags-any=foo,bar
|
|
|
|
The ``tags``, ``tags-any``, ``not-tags`` and ``not-tags-any`` arguments can
|
|
be combined to build more complex queries. The following example returns
|
|
projects that have the “foo” and “bar” tags, plus at least one of “red”
|
|
and “blue”:
|
|
|
|
.. code-block:: bash
|
|
|
|
GET /v3/projects?tags=foo,bar&tags-any=red,blue
|