neutron/doc/source/contributor/internals/tag.rst

Add Tags to Neutron Resources

Tag service plugin allows users to set tags on their resources. Tagging resources can be used by external systems or any other clients of the Neutron REST API (and NOT backend drivers).

The following use cases refer to adding tags to networks, but the same can be applicable to any other Neutron resource:

1. Ability to map different networks in different OpenStack locations to one logically same network (for Multi site OpenStack)
2. Ability to map Id's from different management/orchestration systems to OpenStack networks in mixed environments, for example for project Kuryr, map docker network id to neutron network id
3. Leverage tags by deployment tools
4. allow operators to tag information about provider networks (e.g. high-bandwidth, low-latency, etc)
5. new features like get-me-a-network or a similar port scheduler could choose a network for a port based on tags

Which Resources

Tag system uses standardattr mechanism so it's targeting to resources that have the mechanism. Some resources with standard attribute don't suit fit tag support usecases (e.g. security_group_rule). If new tag support resource is added, the resource model should inherit HasStandardAttributes and then it must implement the property 'api_parent' and 'tag_support'. And also the change must include a release note for API user.

Current API resources extended by tag extensions:

• floatingips
• networks
• policies
• ports
• routers
• security_groups
• subnetpools
• subnets
• trunks

Model

Tag is not standalone resource. Tag is always related to existing resources. The following shows tag model:

+------------------+        +------------------+
|     Network      |        |       Tag        |
+------------------+        +------------------+
| standard_attr_id +------> | standard_attr_id |
|                  |        | tag              |
|                  |        |                  |
+------------------+        +------------------+

Tag has two columns only and tag column is just string. These tags are defined per resource. Tag is unique in a resource but it can be overlapped throughout.

API

The following shows basic API for tag. Tag is regarded as a subresource of resource so API always includes id of resource related to tag.

Add a single tag on a network :

PUT /v2.0/networks/{network_id}/tags/{tag}

Returns 201 Created. If the tag already exists, no error is raised, it just returns the 201 Created because the OpenStack Development Mailing List discussion told us that PUT should be no issue updating an existing tag.

Replace set of tags on a network :

PUT /v2.0/networks/{network_id}/tags

with request payload :

{
    'tags': ['foo', 'bar', 'baz']
}

Response :

{
    'tags': ['foo', 'bar', 'baz']
}

Check if a tag exists or not on a network :

GET /v2.0/networks/{network_id}/tags/{tag}

Remove a single tag on a network :

DELETE /v2.0/networks/{network_id}/tags/{tag}

Remove all tags on a network :

DELETE /v2.0/networks/{network_id}/tags

PUT and DELETE for collections are the motivation of extending the API framework.