diff options
| -rw-r--r-- | api-ref/source/v3/index.rst | 9 | ||||
| -rw-r--r-- | api-ref/source/v3/parameters.yaml | 13 | ||||
| -rw-r--r-- | api-ref/source/v3/project-tags.inc | 339 | ||||
| -rw-r--r-- | api-ref/source/v3/projects.inc | 1 | ||||
| -rw-r--r-- | api-ref/source/v3/samples/admin/project-create-response.json | 3 | ||||
| -rw-r--r-- | api-ref/source/v3/samples/admin/project-tags-list-response.json | 3 | ||||
| -rw-r--r-- | api-ref/source/v3/samples/admin/project-tags-update-request.json | 3 | ||||
| -rw-r--r-- | api-ref/source/v3/samples/admin/project-tags-update-response.json | 20 | ||||
| -rw-r--r-- | api-ref/source/v3/samples/admin/project-update-response.json | 3 | ||||
| -rw-r--r-- | api-ref/source/v3/samples/admin/projects-list-response.json | 24 | ||||
| -rw-r--r-- | releasenotes/notes/project-tags-1e72a6779d9d02c5.yaml | 18 |
11 files changed, 426 insertions, 10 deletions
diff --git a/api-ref/source/v3/index.rst b/api-ref/source/v3/index.rst index 0d9e3a644..492a778f7 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 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 diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index 237a0f82b..de26ba465 100644 --- a/api-ref/source/v3/parameters.yaml +++ b/api-ref/source/v3/parameters.yaml @@ -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: diff --git a/api-ref/source/v3/project-tags.inc b/api-ref/source/v3/project-tags.inc new file mode 100644 index 000000000..af8ff39c0 --- /dev/null +++ b/api-ref/source/v3/project-tags.inc @@ -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 diff --git a/api-ref/source/v3/projects.inc b/api-ref/source/v3/projects.inc index 912731c6c..6ac35f0aa 100644 --- a/api-ref/source/v3/projects.inc +++ b/api-ref/source/v3/projects.inc @@ -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 ---------------- 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 42c41d6ff..9c7dbe3a6 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 @@ "self": "http://example.com/identity/v3/projects/93ebbcc35335488b96ff9cd7d18cbb2e" }, "name": "myNewProject", - "parent_id": "default" + "parent_id": "default", + "tags": [] } } 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 000000000..887054a00 --- /dev/null +++ b/api-ref/source/v3/samples/admin/project-tags-list-response.json @@ -0,0 +1,3 @@ +{ + "tags": ["foo", "bar"] +} 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 000000000..887054a00 --- /dev/null +++ b/api-ref/source/v3/samples/admin/project-tags-update-request.json @@ -0,0 +1,3 @@ +{ + "tags": ["foo", "bar"] +} 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 000000000..ae65d6d00 --- /dev/null +++ b/api-ref/source/v3/samples/admin/project-tags-update-response.json @@ -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"] + } + ] +} 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 42c0ee2a6..31a943a88 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 @@ "id": "93ebbcc35335488b96ff9cd7d18cbb2e", "is_domain": true, "name": "myUpdatedProject", - "parent_id": null + "parent_id": null, + "tags": [] } } 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 2c12119fd..6bb96e32a 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 @@ "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": [] } ] } diff --git a/releasenotes/notes/project-tags-1e72a6779d9d02c5.yaml b/releasenotes/notes/project-tags-1e72a6779d9d02c5.yaml new file mode 100644 index 000000000..b0b4dadfd --- /dev/null +++ b/releasenotes/notes/project-tags-1e72a6779d9d02c5.yaml @@ -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>`_ |