openstack/keystone
Code Issues Proposed changes

Add project tags api-ref documentation and reno

Browse Source 
This change creates a new page describing the usage of project tags
as well as adds in project tag information into existing projects
refs. The added document highlights the properties of a project
tag, the new API calls created, filtering/searching uses, and examples
for each.

This change also creates a release note for the changes made
that add project tags.

Change-Id: Icff11da9412378ae59c6f392f98b05475c7c501d
Partially-Implements: bp project-tags
This commit is contained in:
Gage Hugo 2017-06-08 14:56:32 -05:00
parent 5329071174
commit 0579dec0b9
11 changed files with 426 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
api-ref/source/v3/index.rst
View File

@ -26,6 +26,13 @@ For information about Identity API protection, see
<https://docs.openstack.org/keystone/latest/admin/identity-service-api-protection.html>`_
in the OpenStack Cloud Administrator Guide.
=========================
What's New in Version 3.9
=========================
- Addition of ``tags`` attribute to project.
- New APIs to interact with the ``tags`` attribute.
=========================
What's New in Version 3.8
=========================
@ -177,6 +184,7 @@ This page lists the Identity API operations in the following order:
* `Groups`_
* `Policies`_
* `Projects`_
* `Project Tags`_
* `Regions`_
* `Roles`_
* `Service catalog and endpoints`_
@ -195,6 +203,7 @@ This page lists the Identity API operations in the following order:
.. include:: os-pki.inc
.. include:: policies.inc
.. include:: projects.inc
.. include:: project-tags.inc
.. include:: regions-v3.inc
.. include:: roles.inc
.. include:: service-catalog.inc

13
api-ref/source/v3/parameters.yaml
View File

@ -300,6 +300,13 @@ project_name_query:
in: query
required: false
type: string
project_tag_query:
description: |
A simple string associated with a project. Can be used for assigning
values to projects and filtering based on those values.
in: query
required: true
type: string
protocol_id_query:
description: |
Filters the response by a protocol ID.
@ -1287,6 +1294,12 @@ regions_object:
in: body
required: true
type: array
response_body_project_tags_required:
description: |
A list of simple strings assigned to a project.
in: body
required: true
type: array
role:
description: |
A ``role`` object, containing:

339
api-ref/source/v3/project-tags.inc Normal file
View File

@ -0,0 +1,339 @@
.. -*- 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
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
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
Request Example
---------------
.. literalinclude:: ./samples/admin/project-tags-list-response.json
:language: javascript
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
- tag: project_tag_query
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
- tag: project_tag_query
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- tags: response_body_project_tags_required
Status Codes
------------
.. rest_status_code:: success status.yaml
- 201
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
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
- tags: response_body_project_tags_required
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
Request Example
---------------
.. literalinclude:: ./samples/admin/project-tags-update-request.json
:language: javascript
Response Example
----------------
.. literalinclude:: ./samples/admin/project-tags-update-response.json
:language: javascript
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
- tag: project_tag_query
Status Codes
~~~~~~~~~~~~
.. rest_status_code:: success status.yaml
- 204
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
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
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

1
api-ref/source/v3/projects.inc
View File

@ -86,6 +86,7 @@ Response Parameters
- links: link_response_body
- name: project_name_response_body
- parent_id: project_parent_id_response_body
- tags: response_body_project_tags_required
Response Example
----------------

3
api-ref/source/v3/samples/admin/project-create-response.json
View File

@ -9,6 +9,7 @@
"self": "http://example.com/identity/v3/projects/93ebbcc35335488b96ff9cd7d18cbb2e"
},
"name": "myNewProject",
"parent_id": "default"
"parent_id": "default",
"tags": []
}
}

3
api-ref/source/v3/samples/admin/project-tags-list-response.json Normal file
View File

@ -0,0 +1,3 @@
{
"tags": ["foo", "bar"]
}

3
api-ref/source/v3/samples/admin/project-tags-update-request.json Normal file
View File

@ -0,0 +1,3 @@
{
"tags": ["foo", "bar"]
}

20
api-ref/source/v3/samples/admin/project-tags-update-response.json Normal file
View File

@ -0,0 +1,20 @@
{
"links": {
"next": null,
"previous": null,
"self": "http://identity:5000/v3/projects"
},
"projects": [
{
"description": "Test Project",
"domain_id": "default",
"enabled": true,
"id": "3d4c2c82bd5948f0bcab0cf3a7c9b48c",
"links": {
"self": "http://identity:5000/v3/projects/3d4c2c82bd5948f0bcab0cf3a7c9b48c"
},
"name": "demo",
"tags": ["foo", "bar"]
}
]
}

3
api-ref/source/v3/samples/admin/project-update-response.json
View File

@ -9,6 +9,7 @@
"id": "93ebbcc35335488b96ff9cd7d18cbb2e",
"is_domain": true,
"name": "myUpdatedProject",
"parent_id": null
"parent_id": null,
"tags": []
}
}

24
api-ref/source/v3/samples/admin/projects-list-response.json
View File

@ -15,7 +15,8 @@
"self": "http://example.com/identity/v3/projects/0c4e939acacf4376bdcd1129f1a054ad"
},
"name": "admin",
"parent_id": null
"parent_id": null,
"tags": []
},
{
"is_domain": false,
@ -27,7 +28,8 @@
"self": "http://example.com/identity/v3/projects/0cbd49cbf76d405d9c86562e1d579bd3"
},
"name": "demo",
"parent_id": null
"parent_id": null,
"tags": []
},
{
"is_domain": false,
@ -39,7 +41,8 @@
"self": "http://example.com/identity/v3/projects/2db68fed84324f29bb73130c6c2094fb"
},
"name": "swifttenanttest2",
"parent_id": null
"parent_id": null,
"tags": []
},
{
"is_domain": false,
@ -51,7 +54,8 @@
"self": "http://example.com/identity/v3/projects/3d594eb0f04741069dbbb521635b21c7"
},
"name": "service",
"parent_id": null
"parent_id": null,
"tags": []
},
{
"is_domain": false,
@ -63,7 +67,8 @@
"self": "http://example.com/identity/v3/projects/43ebde53fc314b1c9ea2b8c5dc744927"
},
"name": "swifttenanttest1",
"parent_id": null
"parent_id": null,
"tags": []
},
{
"is_domain": false,
@ -75,7 +80,8 @@
"self": "http://example.com/identity/v3/projects/4b1eb781a47440acb8af9850103e537f"
},
"name": "swifttenanttest4",
"parent_id": null
"parent_id": null,
"tags": []
},
{
"is_domain": false,
@ -87,7 +93,8 @@
"self": "http://example.com/identity/v3/projects/5961c443439d4fcebe42643723755e9d"
},
"name": "invisible_to_admin",
"parent_id": null
"parent_id": null,
"tags": []
},
{
"is_domain": false,
@ -99,7 +106,8 @@
"self": "http://example.com/identity/v3/projects/fdb8424c4e4f4c0ba32c52e2de3bd80e"
},
"name": "alt_demo",
"parent_id": null
"parent_id": null,
"tags": []
}
]
}

18
releasenotes/notes/project-tags-1e72a6779d9d02c5.yaml Normal file
View File

@ -0,0 +1,18 @@
---
features:
- |
[`blueprint project-tags <https://blueprints.launchpad.net/keystone/+spec/project-tags>`_]
Projects have a new property called tags. These tags
are simple strings that can be used to allow projects
to be filtered/searched. Project tags will have the
following properties:
* Tags are case sensitive
* '/' and ',' are not allowed to be in a tag
* Each project can have up to 100 tags
* Each tag can be up to 255 characters
See `Project Tags <https://developer.openstack.org/api-ref/identity/v3/#project-tags>`_
Project tags are implemented following the guidelines
set by the `API Working Group <https://specs.openstack.org/openstack/api-wg/guidelines/tags.html>`_