Resource tags¶
Various virtual networking resources support tags for use by external systems or any other clients of the Networking service API.
The currently supported resources are:
- networks
- subnets
- subnetpools
- ports
- routers
Use cases¶
The following use cases refer to adding tags to networks, but the same can be applicable to any other supported Networking service resource:
- Ability to map different networks in different OpenStack locations to one logically same network (for multi-site OpenStack).
- Ability to map IDs from different management/orchestration systems to OpenStack networks in mixed environments. For example, in the Kuryr project, the Docker network ID is mapped to the Neutron network ID.
- Ability to leverage tags by deployment tools.
- Ability to tag information about provider networks (for example, high-bandwidth, low-latency, and so on).
Filtering with tags¶
The API allows searching/filtering of the GET /v2.0/networks API. The
following query parameters are supported:
tagstags-anynot-tagsnot-tags-any
To request the list of networks that have a single tag, tags argument
should be set to the desired tag name. Example:
GET /v2.0/networks?tags=red
To request the list of networks that have two or more tags, the tags
argument should be set to the list of tags, separated by commas. In this case,
the tags given must all be present for a network to be included in the query
result. Example that returns networks that have the “red” and “blue” tags:
GET /v2.0/networks?tags=red,blue
To request the list of networks that have one or more of a list of given tags,
the tags-any argument should be set to the list of tags, separated by
commas. In this case, as long as one of the given tags is present, the network
will be included in the query result. Example that returns the networks that
have the “red” or the “blue” tag:
GET /v2.0/networks?tags-any=red,blue
To request the list of networks that do not have one or more tags, the
not-tags argument should be set to the list of tags, separated by commas.
In this case, only the networks that do not have any of the given tags will be
included in the query results. Example that returns the networks that do not
have either “red” or “blue” tag:
GET /v2.0/networks?not-tags=red,blue
To request the list of networks 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 case, only the networks that do not have at least
one of the given tags will be included in the query result. Example that
returns the networks that do not have the “red” tag, or do not have the “blue”
tag:
GET /v2.0/networks?not-tags-any=red,blue
The tags, tags-any, not-tags, and not-tags-any arguments can be
combined to build more complex queries. Example:
GET /v2.0/networks?tags=red,blue&tags-any=green,orange
The above example returns any networks that have the “red” and “blue” tags, plus at least one of “green” and “orange”.
Complex queries may have contradictory parameters. Example:
GET /v2.0/networks?tags=blue¬-tags=blue
In this case, we should let the Networking service find these networks. Obviously, there are no such networks and the service will return an empty list.
User workflow¶
Add a tag to a resource:
$ neutron tag-add --resource-type network --resource ab442634-1cc9-49e5-bd49-0dac9c811f69 --tag red
$ neutron net-show net
+-------------------------+--------------------------------------+
| Field | Value |
+-------------------------+--------------------------------------+
| admin_state_up | True |
| availability_zone_hints | |
| availability_zones | |
| id | ab442634-1cc9-49e5-bd49-0dac9c811f69 |
| ipv4_address_scope | |
| ipv6_address_scope | |
| mtu | 1450 |
| name | net |
| port_security_enabled | True |
| router:external | False |
| shared | False |
| status | ACTIVE |
| subnets | |
| tags | red |
| tenant_id | e6710680bfd14555891f265644e1dd5c |
+-------------------------+--------------------------------------+
Remove a tag from a resource:
$ neutron tag-remove --resource-type network --resource ab442634-1cc9-49e5-bd49-0dac9c811f69 --tag red
$ neutron net-show net
+-------------------------+--------------------------------------+
| Field | Value |
+-------------------------+--------------------------------------+
| admin_state_up | True |
| availability_zone_hints | |
| availability_zones | |
| id | ab442634-1cc9-49e5-bd49-0dac9c811f69 |
| ipv4_address_scope | |
| ipv6_address_scope | |
| mtu | 1450 |
| name | net |
| port_security_enabled | True |
| router:external | False |
| shared | False |
| status | ACTIVE |
| subnets | |
| tags | |
| tenant_id | e6710680bfd14555891f265644e1dd5c |
+-------------------------+--------------------------------------+
Replace all tags on the resource:
$ neutron tag-replace --resource-type network --resource ab442634-1cc9-49e5-bd49-0dac9c811f69 --tag red --tag blue
$ neutron net-show net
+-------------------------+--------------------------------------+
| Field | Value |
+-------------------------+--------------------------------------+
| admin_state_up | True |
| availability_zone_hints | |
| availability_zones | |
| id | ab442634-1cc9-49e5-bd49-0dac9c811f69 |
| ipv4_address_scope | |
| ipv6_address_scope | |
| mtu | 1450 |
| name | net |
| port_security_enabled | True |
| router:external | False |
| shared | False |
| status | ACTIVE |
| subnets | |
| tags | red |
| | blue |
| tenant_id | e6710680bfd14555891f265644e1dd5c |
+-------------------------+--------------------------------------+
Clear tags from a resource:
$ neutron tag-remove --resource-type network --resource ab442634-1cc9-49e5-bd49-0dac9c811f69 --all
$ neutron net-show net
+-------------------------+--------------------------------------+
| Field | Value |
+-------------------------+--------------------------------------+
| admin_state_up | True |
| availability_zone_hints | |
| availability_zones | |
| id | ab442634-1cc9-49e5-bd49-0dac9c811f69 |
| ipv4_address_scope | |
| ipv6_address_scope | |
| mtu | 1450 |
| name | net |
| port_security_enabled | True |
| router:external | False |
| shared | False |
| status | ACTIVE |
| subnets | |
| tags | |
| tenant_id | e6710680bfd14555891f265644e1dd5c |
+-------------------------+--------------------------------------+
Get list of resources with tag filters from networks. The networks are: test-net1 with “red” tag, test-net2 with “red” and “blue” tags, test-net3 with “red”, “blue”, and “green” tags, and test-net4 with “green” tag.
Get list of resources with tags filter:
$ neutron net-list --tags red,blue
+--------------------------------------+-----------+---------+
| id | name | subnets |
+--------------------------------------+-----------+---------+
| 8ca3b9ed-f578-45fa-8c44-c53f13aec05a | test-net3 | |
| e736e63d-42e4-4f4c-836c-6ad286ffd68a | test-net2 | |
+--------------------------------------+-----------+---------+
Get list of resources with tags-any filter:
$ neutron net-list --tags-any red,blue
+--------------------------------------+-----------+---------+
| id | name | subnets |
+--------------------------------------+-----------+---------+
| 30491224-3855-431f-a688-fb29df004d82 | test-net1 | |
| 8ca3b9ed-f578-45fa-8c44-c53f13aec05a | test-net3 | |
| e736e63d-42e4-4f4c-836c-6ad286ffd68a | test-net2 | |
+--------------------------------------+-----------+---------+
Get list of resources with not-tags filter:
$ neutron net-list --not-tags red,blue
+--------------------------------------+-----------+---------+
| id | name | subnets |
+--------------------------------------+-----------+---------+
| 30491224-3855-431f-a688-fb29df004d82 | test-net1 | |
| cdb3ed08-ca63-4090-ba12-30b366372993 | test-net4 | |
+--------------------------------------+-----------+---------+
Get list of resources with not-tags-any filter:
$ neutron net-list --not-tags-any red,blue
+--------------------------------------+-----------+---------+
| id | name | subnets |
+--------------------------------------+-----------+---------+
| cdb3ed08-ca63-4090-ba12-30b366372993 | test-net4 | |
+--------------------------------------+-----------+---------+
Limitations¶
Filtering resources with a tag whose name contains a comma is not supported. Thus, do not put such a tag name to resources.
Future support¶
In future releases, the Networking service may support setting tags for additional resources.
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.