OpenStack Identity (Keystone)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 

377 lines
7.9 KiB

.. -*- 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