Various virtual networking resources support tags for use by external systems or any other clients of the Networking service API.
The following use cases refer to adding tags to networks, but the same can be applicable to any other Networking service resource:
The API allows searching/filtering of the GET /v2.0/networks API. The following query parameters are supported:
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.
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 | |
+--------------------------------------+-----------+---------+
Filtering resources with a tag whose name contains a comma is not supported. Thus, do not put such a tag name to resources.
In future release, the Networking service will support setting tags to resources other than network.
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.